xca문서
엔드포인트

홀더

스캔된 토큰의 홀더를 유형별로 분류해 손익, 진입 시점, 자금 출처와 함께 페이지 단위로 제공해요.

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

분석된 토큰 홀더를 순위순으로 정렬해 XCA가 각 지갑에 부여한 유형과 함께 반환해요. 토큰이 스캔된 적이 있어야 하며, 그렇지 않으면 404 오류가 반환돼요.

파라미터#

chainpath필수
체인 ID. 현재는 solana만 지원해요."solana"
addresspath필수
토큰 민트 주소.string
pagequery
페이지 번호. 1부터 시작해요.integer ≥ 1기본값: 1
pageSizequery
페이지당 홀더 수.10 | 25 | 50 | 100기본값: 100
classquery
이 유형의 홀더만 반환해요.ALL | HolderClass기본값: ALL

요청#

curl -s "https://app.xca.fun/api/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?class=SMART_MONEY&pageSize=25" \
  -H "Authorization: Bearer $XCA_API_KEY"
직접 실행
실제 요청을 보내려면 API 키를 붙여넣으세요.

응답#

rows
이 페이지의 홀더.HolderRow[]
rank
잔액 기준 순위. 1위가 가장 많이 보유한 홀더예요.number
address
지갑 주소.string | null
sharePct
보유한 공급량 비중.number
valueUsd
보유 물량의 가치(USD).number | null
class
XCA가 지갑에 부여한 유형.HolderClass | "HIDDEN"
flags
지갑의 추가 특성.string[]
entryAt
첫 매수 시각.string | null
entryBlock
거래 시작부터 첫 매수까지의 블록 수(스나이퍼는 값이 작아요).number | null
pnl30dUsd
최근 30일 실현 및 미실현 손익(USD).number | null
pnl30dPct
최근 30일 손익(%).number | null
winRate
수익 거래 비율(0~1).number | null
avgHoldSec
평균 보유 시간(초).number | null
trades30d
최근 30일 거래 횟수.number | null
fundedBy
이 지갑에 처음 자금을 보낸 지갑.string | null
clusterId
지갑이 속한 클러스터.string | null
profiled
전체 지갑 프로필이 있어요.boolean
total
필터 조건에 맞는 홀더 중 볼 수 있는 홀더 수.number
lockedCount
플랜 한도 때문에 숨겨진 홀더 수.number
page
현재 페이지.number
pageSize
페이지당 홀더 수.number
visibleLimit
플랜에서 보여 주는 상위 홀더 수. -1이면 전체를 보여 줘요.number

응답 예시#

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

상태 코드#

200성공
400validation — 파라미터나 요청 본문이 유효하지 않아요. error.issues 값을 확인하세요.
401unauthorized — API 키가 없거나, 형식이 잘못됐거나, 폐기됐어요.
402planRequired — 플랜에 API 접근 권한이나 이 기능이 포함되어 있지 않아요.
404notFound — 토큰이 아직 스캔되지 않았거나 지갑 프로필이 아직 없어요.
429rateLimited — 분당 요청이 너무 많거나 월간 할당량을 모두 사용했어요.

홀더 유형#

SMART_MONEY최근 30일 동안 수익을 냈고 승률이 높은 트레이더예요.
REGULAR특이 사항이 없는 지갑이에요.
DEV토큰 생성자예요.
DEV_BUNDLE생성자와 함께 매수했거나 생성자에게서 자금을 받은 지갑이에요.
SNIPER거래 시작 직후 처음 몇 블록 안에 매수한 지갑이에요.
FRESH아주 최근에 만들어진 지갑이에요.
POOL유동성 풀, 볼트 또는 본딩 커브예요.
CEX중앙화 거래소 지갑이에요.
BURN소각 주소예요.

참고 사항#

  • 볼 수 있는 상위 홀더 수는 플랜에 따라 제한돼요. total 값은 볼 수 있는 홀더만 세고, lockedCount 값은 그 밖에 몇 명이 더 있는지 알려 줘요.
  • SNIPER, DEV_BUNDLE, SMART_MONEY, FRESH 유형으로 필터링하려면 플랜에 해당 기능이 포함되어 있어야 하며, 그렇지 않으면 402 오류가 반환돼요.
  • 플랜에서 볼 수 없는 유형은 HIDDEN으로 반환돼요.
  • 손익 필드는 플랜의 손익 등급에 따라 달라요. 기본 등급은 pnl30dUsd, winRate 필드를 제공하고, 상세 등급은 여기에 pnl30dPct, avgHoldSec, trades30d 필드를 더해요.