Get outcome token holders

GET /api/v1/market-data/holders

Get outcome token holders

get

Returns a paginated list of all token holders for one or more outcomes of a given market, excluding the treasury address. For finalised markets, this also includes positions held at the time of resolution. market plus exactly one of token_id / token_ids are required.

Query parameters

marketstringRequired

Market contract address

token_idstringOptional

Outcome token ID (mutually exclusive with token_ids)

token_idsstringOptional

Comma-separated outcome token IDs (max 50, mutually exclusive with token_id)

orderstringOptional

Sort field: quantity (default), realized_pnl, unrealized_pnl

ascendingbooleanOptional

Sort direction (default false = descending)

limitintegerOptional

Page size (default 20, max 100)

offsetintegerOptional

Pagination offset

Responses

200

OK

application/json

400

Bad Request

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get/api/v1/market-data/holders

HTTPcURLJavaScriptPython

GET /api/v1/market-data/holders?market=text HTTP/1.1
Host: rest.ft.42.space/
Accept: */*

{
  "data": [
    {
      "amount": 1,
      "avgPrice": 1,
      "costBasis": 1,
      "currentPrice": 1,
      "heldQuantity": 1,
      "mintedQuantity": 1,
      "outcomeName": "text",
      "outcomeSymbol": "text",
      "outcomeTranslations": {
        "ANY_ADDITIONAL_PROPERTY": {
          "name": "text"
        }
      },
      "payout": 1,
      "realizedPnl": 1,
      "tokenId": "text",
      "unrealizedPnl": 1,
      "userAddress": "text"
    }
  ],
  "pagination": {
    "hasMore": true,
    "totalResults": 1
  }
}

Get per-outcome holder summary

get

Returns, for every outcome of a market, the number of unique holders and total cost basis over live positions (treasury excluded), ordered by outcome index. Unknown markets yield an empty array.

Query parameters

marketstringRequired

Market contract address

Responses

200

OK

application/json

outcomeNamestringOptional

outcomeSymbolstringOptional

tokenIdstringOptional

totalCostBasisnumberOptional

uniqueHoldersintegerOptional

400

Bad Request

application/json

500

Internal Server Error

application/json

get/api/v1/market-data/holders/summary

HTTPcURLJavaScriptPython

GET /api/v1/market-data/holders/summary?market=text HTTP/1.1
Host: rest.ft.42.space/
Accept: */*

[
  {
    "outcomeName": "text",
    "outcomeSymbol": "text",
    "tokenId": "text",
    "totalCostBasis": 1,
    "uniqueHolders": 1
  }
]

Get per-outcome trader counts

get

Returns, for every outcome of a market, the number of distinct traders (users with at least one mint or redeem in the ledger, treasury excluded), ordered by outcome index. Optionally restricted to specific token IDs. Unknown markets yield an empty array.

Query parameters

marketstringRequired

Market contract address

token_idsstringOptional

Comma-separated outcome token IDs (max 50)

Responses

200

OK

application/json

tokenIdstringOptional

tradersintegerOptional

400

Bad Request

application/json

500

Internal Server Error

application/json

get/api/v1/market-data/traders

HTTPcURLJavaScriptPython

GET /api/v1/market-data/traders?market=text HTTP/1.1
Host: rest.ft.42.space/
Accept: */*

[
  {
    "tokenId": "text",
    "traders": 1
  }
]