xcaDocs
Endpoints

Holders

Classified holders of a scanned token with PnL, entry time and funding source, page by page.

GET/api/v1/tokens/{chain}/{address}/holders

Returns the analyzed holders of a token sorted by rank, with the class XCA assigned to each wallet. The token must have been scanned; otherwise you get 404.

Parameters#

chainpathrequired
Chain id. Only solana for now."solana"
addresspathrequired
Token mint address.string
pagequery
Page number, starting at 1.integer ≥ 1default: 1
pageSizequery
Holders per page.10 | 25 | 50 | 100default: 100
classquery
Return only holders of this class.ALL | HolderClassdefault: ALL

Request#

curl -s "https://app.xca.fun/api/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?class=SMART_MONEY&pageSize=25" \
  -H "Authorization: Bearer $XCA_API_KEY"
Try it
Paste your API key to send a real request.

Response#

rows
Holders on this page.HolderRow[]
rank
Position by balance, 1 is the largest.number
address
Wallet address.string | null
sharePct
Share of the supply held.number
valueUsd
Value of the holding, USD.number | null
class
Class XCA assigned to the wallet.HolderClass | "HIDDEN"
flags
Extra traits of the wallet.string[]
entryAt
Time of the first buy.string | null
entryBlock
Blocks between launch and the first buy (snipers have small numbers).number | null
pnl30dUsd
Realized and unrealized PnL over 30 days, USD.number | null
pnl30dPct
PnL over 30 days, percent.number | null
winRate
Share of profitable trades, 0 to 1.number | null
avgHoldSec
Average holding time, seconds.number | null
trades30d
Trades over 30 days.number | null
fundedBy
Wallet that first funded this one.string | null
clusterId
Cluster the wallet belongs to.string | null
profiled
A full wallet profile exists.boolean
total
Visible holders matching the filter.number
lockedCount
Holders hidden by your plan's limit.number
page
Current page.number
pageSize
Holders per page.number
visibleLimit
How many top holders your plan shows; -1 means all.number

Example response#

{
  "rows": [
    {
      "rank": 4,
      "address": "5Hr7wZg7oBpVhH5nngRqzr5W7ZFUfCsfEhbziZJak7fr",
      "sharePct": 1.92,
      "valueUsd": 3641200,
      "class": "SMART_MONEY",
      "flags": [
        "smart"
      ],
      "entryAt": "2023-01-04T18:22:10.000Z",
      "entryBlock": null,
      "pnl30dUsd": 48210.7,
      "pnl30dPct": 31.4,
      "winRate": 0.64,
      "avgHoldSec": 1209600,
      "trades30d": 37,
      "fundedBy": "FWznbcNXWQuHTawe9RxvQ2LdCENssh12dsznf4RiouN5",
      "clusterId": null,
      "profiled": true
    }
  ],
  "total": 7,
  "lockedCount": 0,
  "page": 1,
  "pageSize": 25,
  "visibleLimit": -1
}

Status codes#

200Success
400validation — A parameter or the body is invalid; see error.issues.
401unauthorized — The API key is missing, malformed or revoked.
402planRequired — Your plan doesn't include API access or this feature.
404notFound — The token wasn't scanned or the wallet wasn't profiled yet.
429rateLimited — Too many requests per minute, or the monthly quota is used up.

Holder classes#

SMART_MONEYProfitable trader over 30 days with a high win rate.
REGULARNothing notable.
DEVThe token creator.
DEV_BUNDLEBought together with the creator or was funded by the creator.
SNIPERBought within the first blocks after launch.
FRESHWallet created very recently.
POOLLiquidity pool, vault or bonding curve.
CEXCentralized exchange wallet.
BURNBurn address.

Good to know#

  • Your plan caps how many top holders are visible; total counts only the visible ones and lockedCount says how many more exist.
  • Filtering by SNIPER, DEV_BUNDLE, SMART_MONEY or FRESH requires the matching feature in your plan, otherwise you get 402.
  • A class your plan can't see comes back as HIDDEN.
  • PnL fields depend on the plan's PnL level: basic gives pnl30dUsd and winRate, detailed adds pnl30dPct, avgHoldSec and trades30d.