Skip to main content
GET
Get Token Holder Positions
Batch Support Available: This endpoint supports batch queries via POST method for fetching multiple token holder positions in a single request (up to 10 tokens). Jump to Batch Query section

Query Details

This endpoint requires both the blockchain and address parameters. You can refine results by filtering with walletAddresses (for specific traders) or label (for trader type categories). The force parameter allows bypassing cached data to fetch the most recent results. Combine these parameters as needed to tailor your query.

Query Parameters

  • blockchain (required) — Blockchain identifier (e.g., ethereum, evm:1, solana).
  • address (required) — Token contract address or mint address.
  • label (optional) — Filter by trader type: sniper | insider | bundler | proTrader | smartTrader | freshTrader | dev | liquidityPool | locker.
  • walletAddresses (optional) — One or multiple wallet addresses (comma-separated or array).
  • limit (optional, default: 100, max: 1000) — Maximum number of positions returned.
  • offset (optional, default: 0) — Number of positions to skip for pagination.
  • force (optional, default: false) — Whether to bypass cache and fetch fresh data.

Step-by-Step Tutorial and Video Walkthrough

  • Check out the guide: Here

Usage Examples

  • Query by Token Address with Blockchain
  • Query by Token Address with Specific Wallets (comma-separated)
  • Query by Token Address with Label (bundler)
  • Query with Pagination (Infinite Scroll)

Query Response Fields

walletMetadata object

platform object

fundingInfo object

POST Method - Batch Query

Retrieve holder positions for multiple tokens in a single request for improved efficiency (up to 10 tokens).

Request Body

Body Parameters

The request body is an array of query objects (max 10), where each object contains:
  • blockchain (optional) — Blockchain identifier (e.g., ethereum, evm:1, solana).
  • address (optional) — Token contract address or mint address.
  • label (optional) — Filter by trader type: sniper | insider | bundler | proTrader | smartTrader | freshTrader | dev | liquidityPool | locker.
  • walletAddresses (optional) — One or multiple wallet addresses (comma-separated or array).
  • limit (optional, default: 100) — Maximum number of positions returned.
  • offset (optional, default: 0) — Offset for pagination.
  • useSwapRecipient (optional, default: true) — Use swap recipient mode for accurate Account Abstraction tracking.
  • includeFees (optional, default: false) — Include total fees paid (gas + platform + MEV) and deduct from PnL.

Usage Examples

Response Format

Query Parameters

chainId
string

Blockchain chain ID (e.g., "evm:56", "solana:solana")

address
string

Token contract address

label
enum<string>

Filter by wallet label (e.g. sniper, bundler, insider)

Available options:
sniper,
insider,
bundler,
proTrader,
smartTrader,
freshTrader,
freshTrader30d,
dev,
liquidityPool,
locker
limit
number | null

Maximum number of results (default: 100)

offset
number | null

Offset for pagination

walletAddresses

Comma-separated wallet addresses to filter

includeFees
required

Include total fees paid (gas + platform + MEV) and deduct from PnL

Response

200 - application/json

Token Holder response

data
object[]
required
totalCount
number
required