Skip to main content
GET
Token - Holders (Multi)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

chain
enum<string>
required

A chain name listed in supported networks Supported blockchain chains

Available options:
sol,
eth,
bsc
tokenAddress
string
required

An address of a token

Query Parameters

walletAddresses
string
required

A list of wallet addresses in string separated by commas (,). Maximum 100 address addresses allowed

Response

200 - application/json

Get Holders Multi

amount
string
required

Token holding amount

Example:

"1000000000000000000"

amountInUsd
string
required

Token holding value in USD

Example:

"1000000000000000000"

percentage
string
required

Percentage of total supply held

Example:

"100"

walletAddress
string
required

Holder wallet address

Example:

"0x1234567890abcdef"

accountAddress
string | null

Solana token account address (ATA) for this holder position. Distinct from walletAddress (the owner). Matches GMGN accountAddress.

accuAmount
string | null

Traceable cumulative DEX buy quantity — buy-side only (GMGN: accu_amount)

accuCost
string | null

Traceable position accumulated cost, USD (GMGN: accu_cost)

addrType
integer<int64> | null

Address type from dexes_dwd.address_labels (1=CEX, 2=MM, 3=VC, 4=KOL …). Matches GMGN addr_type.

addressLabel
string | null

Specific address label (e.g. "Binance Hot Wallet 1"). Matches GMGN name.

amountInNative
string | null

Holder's token position value denominated in the chain's native coin (SOL/BNB/ETH). Computed as price_in_native × amount using real-time Redis price; falls back to OpenSearch post_balance_in_native snapshot when price is unavailable.

avgBuyPriceUsd
string | null

Average buy price in USD per token (all-time)

avgCostUsd
string | null

Average cost per token in USD (current position cost basis)

avgSellPriceUsd
string | null

Average sell price in USD per token (all-time)

buyAmountCur
string | null

Cumulative token quantity bought, all-time (GMGN: buy_amount_cur / history_bought_amount)

buyVolumeNative
string | null

All-time total buy volume in native token

buyVolumeUsd
string | null

All-time total buy volume in USD

createdAt
integer<int64> | null

Unix timestamp (seconds) when this wallet first appeared on-chain (GMGN: created_at).

endHoldingAt
integer<int64> | null

Timestamp when holder fully closed position (ms since epoch)

exchange
string | null

Entity/exchange name (e.g. "Binance"). Matches GMGN exchange.

firstBuyTime
integer<int64> | null

Timestamp of first token purchase (ms since epoch)

historyBoughtCost
string | null

Total DEX buy cost including fees, USD (GMGN: history_bought_cost)

historyBoughtFee
string | null

Total DEX buy fees, USD (GMGN: history_bought_fee)

historySoldFee
string | null

Total DEX sell fees, USD (GMGN: history_sold_fee)

historySoldIncome
string | null

Total DEX sell income, USD (GMGN: history_sold_income)

historyTransferInAmount
string | null

Cumulative transfer-in token qty (GMGN: history_transfer_in_amount)

historyTransferInCost
string | null

Transfer-in USD cost basis (GMGN: history_transfer_in_cost)

historyTransferOutAmount
string | null

Cumulative transfer-out token qty (GMGN: history_transfer_out_amount)

historyTransferOutFee
string | null

Total transfer-out fee in USD all-time (GMGN: historyTransferOutFee).

historyTransferOutIncome
string | null

Transfer-out USD income (GMGN: history_transfer_out_income)

isClosed
boolean | null

Whether the token position is fully closed (balance = 0)

isNew
boolean | null

Whether the wallet is newly created (GMGN: is_new).

isTransferIn
boolean | null

Position acquired purely via transfers, no DEX buy (GMGN: transfer_in)

lastActiveAt
integer<int64> | null

Last active timestamp (ms since epoch)

lastBlock
integer<int64> | null

Last processed block height for this holder position (GMGN: last_block).

lossCount
integer<int64> | null

Number of losing trades (PnL < 0)

makerTokenTags
string[]

Per-token position/behaviour tags derived at query time. Possible values: "top_holder" (rank ≤ 10, first page only), "whale" (holding > $10,000 USD), "diamond_hands" (held > 30 days).

nativeBalance
string | null

Native chain token balance in lamports (SOL) or wei (EVM), as decimal string. Fetched from RPC with a 10-second Redis cache.

netflowAmount
string | null

Net token quantity flow: buys − sells (GMGN: netflow_amount)

netflowAmountUsd
string | null

Net USD flow: buy_usd − sell_usd (from OS netflow_usd)

netflowUsd
string | null

Net USD inflow (buy_volume_usd − sell_volume_usd); positive = net buyer

positionCostUsd
string | null

Current open position cost in USD

realizedPnlRatio
string | null

Realized PnL / total_cost ratio (GMGN: realized_pnl)

realizedProfit
string | null

Realized PnL in USD (all-time)

roi
string | null

Return on investment = total_pnl / total_cost_all (e.g. 0.25 = 25%)

sellAmountCur
string | null

Cumulative token quantity sold, all-time (GMGN: sell_amount_cur / history_sold_amount)

sellAmountPercentage
string | null

Sell quantity / buy quantity, capped 0–1 (GMGN: sell_amount_percentage)

sellVolumeNative
string | null

All-time total sell volume in native token

sellVolumeUsd
string | null

All-time total sell volume in USD

startHoldingAt
integer<int64> | null

Timestamp when holder first acquired the token (ms since epoch)

tags
string[]

Trader classification tags (e.g. "kol", "smart", "sniper")

tokenTransferIn
any

Most recent token transfer-in for this holder on this token (GMGN: token_transfer_in). Contains: amount, amountInUsd, txSignature, from, ts.

tokenTransferOut
any

Most recent token transfer-out for this holder on this token (GMGN: token_transfer_out). Contains: amount, amountInUsd, txSignature, to, ts.

totalBuyCount
integer<int64> | null

All-time total buy trade count

totalCostUsd
string | null

All-time accumulated cost basis in USD (total_cost_all from pnl-sync)

totalProfit
string | null

Total PnL in USD (realized + unrealized)

totalSellCount
integer<int64> | null

All-time total sell trade count

transferInAmount7d
string | null

Inbound transfer volume in native token over last 7 days

transferInCount
integer<int64> | null

Number of token transfer-in events (GMGN: transfer_in_count)

transferOutAmount7d
string | null

Outbound transfer volume in native token over last 7 days

transferOutCount
integer<int64> | null

Number of token transfer-out events (GMGN: transfer_out_count)

unrealizedPnlRatio
string | null

Unrealized PnL / total_cost ratio (GMGN: unrealized_pnl)

unrealizedProfit
string | null

Unrealized PnL in USD (current position)

walletTagV2
string | null

Global rank tag on this token when sorted by balance (e.g. "TOP1", "TOP2"). Only present on the first page of a balance-sorted query (no cursor).

winCount
integer<int64> | null

Number of winning trades (PnL > 0)