Endpoints

Holders

Holders classificados de um token escaneado, com PnL, horário de entrada e origem dos fundos, página por página.

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

Retorna os holders analisados de um token, ordenados pelo ranking, com a classe que o XCA atribuiu a cada carteira. O token precisa ter sido escaneado; caso contrário, você recebe 404.

Parâmetros#

chainpathobrigatório

ID da rede. Por enquanto, apenas solana."solana"

addresspathobrigatório

Endereço do mint do token.string

pagequery

Número da página, começando em 1.integer ≥ 1padrão: 1

pageSizequery

Holders por página.10 | 25 | 50 | 100padrão: 100

classquery

Retorna apenas os holders desta classe.ALL | HolderClasspadrão: ALL

Requisição#

curl -s "https://app.xca.fun/api/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?class=SMART_MONEY&pageSize=25" \
  -H "Authorization: Bearer $XCA_API_KEY"

Testar

Chave de APIObter chave de APIFica só nesta aba do navegador e é enviada apenas para a API do XCA.

chainpathaddresspathpagequerypageSizequeryclassquery

Cole sua chave de API para enviar uma requisição real.

Resposta#

rows

Holders desta página.HolderRow[]

rank

Posição por saldo; 1 é o maior.number

address

Endereço da carteira.string | null

sharePct

Participação no supply.number

valueUsd

Valor da posição, em USD.number | null

class

Classe que o XCA atribuiu à carteira.HolderClass | "HIDDEN"

flags

Características extras da carteira.string[]

entryAt

Horário da primeira compra.string | null

entryBlock

Blocos entre o lançamento e a primeira compra (snipers têm números baixos).number | null

pnl30dUsd

PnL realizado e não realizado em 30 dias, em USD.number | null

pnl30dPct

PnL em 30 dias, em porcentagem.number | null

winRate

Proporção de trades lucrativos, de 0 a 1.number | null

avgHoldSec

Tempo médio de hold, em segundos.number | null

trades30d

Trades em 30 dias.number | null

fundedBy

Carteira que enviou os primeiros fundos para esta.string | null

clusterId

Cluster ao qual a carteira pertence.string | null

profiled

Existe um perfil de carteira completo.boolean

total

Holders visíveis que correspondem ao filtro.number

lockedCount

Holders ocultos pelo limite do seu plano.number

page

Página atual.number

pageSize

Holders por página.number

visibleLimit

Quantos top holders o seu plano exibe; -1 significa todos.number

Exemplo de resposta#

{
  "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
}

Códigos de status#

200Sucesso

400validation — Um parâmetro ou o corpo da requisição é inválido; veja error.issues.

401unauthorized — A chave de API está ausente, malformada ou revogada.

402planRequired — O seu plano não inclui acesso à API ou a este recurso.

404notFound — O token ainda não foi escaneado ou a carteira ainda não foi perfilada.

429rateLimited — Requisições demais por minuto, ou a cota mensal se esgotou.

Classes de holders#

`SMART_MONEY`	Trader lucrativo nos últimos 30 dias, com win rate alto.
`REGULAR`	Nada digno de nota.
`DEV`	O criador do token.
`DEV_BUNDLE`	Comprou junto com o criador ou recebeu fundos dele.
`SNIPER`	Comprou nos primeiros blocos após o lançamento.
`FRESH`	Carteira criada muito recentemente.
`POOL`	Pool de liquidez, vault ou bonding curve.
`CEX`	Carteira de exchange centralizada.
`BURN`	Endereço de queima.

Bom saber#

O seu plano limita quantos top holders ficam visíveis; total conta apenas os visíveis, e lockedCount informa quantos outros existem.
Filtrar por SNIPER, DEV_BUNDLE, SMART_MONEY ou FRESH exige o recurso correspondente no seu plano; caso contrário, você recebe 402.
Uma classe que o seu plano não pode ver é retornada como HIDDEN.
Os campos de PnL dependem do nível de PnL do plano: o básico traz pnl30dUsd e winRate, e o detalhado adiciona pnl30dPct, avgHoldSec e trades30d.