Honeycluster Docs – Get creator-distribution BFS graph for a token

tokens

Get creator-distribution BFS graph for a token

get

/token/{tokenSlug}/flow

operationId: token-flow

Returns a breadth-first graph rooted at the token's issuer, showing how XRP volume cascaded outward to early counterparties (up to maxDepth hops; default 3). Each node carries its depth, cumulative drops received from upstream nodes inside the traversed subgraph, and latest observed XRP balance in drops. Edges are directed and aggregate every XRP movement between the pair. Returns empty arrays when no token matches the supplied key.

Authorizations

Name	Location	Details
`BearerAuth`	Authorization header · bearer	JWT issued by the Honeycluster auth service for the `indexer` audience. Present as `Authorization: Bearer <token>`.

Path Parameters

Name	Type	Default	Description
`tokenSlug` required	string		Natural token identifier in `currency.issuer` form. Example: `USD.rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B`.

Query Parameters

Name	Type	Default	Description
`maxDepth`	integer	`3`

Responses

200

application/json

Successful response

Field	Type	Description
`nodes`	object[]	Accounts reached during the BFS, including the issuer at depth 0. Empty when the token isn't indexed.
`nodes[].address`	string	XRPL classic address of the node. The issuer itself appears at depth 0.
`nodes[].depth`	integer	Shortest-path distance from the issuer in the traversed subgraph (0 = issuer).
`nodes[].totalReceived`	string	Sum of incoming XRP drops from upstream nodes inside the traversed subgraph, as a decimal string of drops.
`nodes[].currentBalance`	object	Latest observed XRP balance in drops, as a decimal string. `null` when the account has not been observed on-ledger yet.
`edges`	object[]	Directed edges between accounts in `nodes`. Unique by `(from, to)` pair; aggregates every XRP movement between the pair.
`edges[].from`	string	Source account (XRPL classic address).
`edges[].to`	string	Destination account (XRPL classic address).
`edges[].amount`	string	Aggregate XRP drops moved from `from` → `to`, as a decimal string of drops.

Example

Json

{
  "nodes": [
    {
      "address": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
      "depth": 0,
      "totalReceived": "0",
      "currentBalance": "15000000000"
    },
    {
      "address": "rExampleEarly1234567890",
      "depth": 1,
      "totalReceived": "5000000000",
      "currentBalance": "4900000000"
    }
  ],
  "edges": [
    {
      "from": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
      "to": "rExampleEarly1234567890",
      "amount": "5000000000"
    }
  ]
}

400

application/json

Invalid input data

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}

401

application/json

Authorization not provided

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}

403

application/json

Insufficient access

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}

404

application/json

Not found

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "NOT_FOUND",
  "message": "Not found",
  "issues": []
}

500

application/json

Internal server error

Field	Type	Description
`message`	string	The error message
`code`	string	The error code
`issues`	object[]	An array of issues that were responsible for the error
`issues[].message`	string

Example

Json

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}