Native Tokens

How to query native tokens (ETH, BTC, SOL, …) and where their coverage is thinner than for contract tokens.

A native token is the coin a chain issues itself — ETH on Ethereum, BTC on Bitcoin, SOL on Solana, TON on TON. Unlike an ERC-20 or SPL token, a native token has no contract address, so there is no real token_address to send.

The API solves this with a per-chain placeholder address. You pass the placeholder as token_address and pair it with the chain you want.

Native-token coverage is genuinely narrower than contract-token coverage. Several endpoints reject native tokens outright, and others serve them from a different data path — in one case with fewer filter and sort options. Read Coverage limitations before assuming parity with an ERC-20 — this is the most common source of confusion in native-token queries.

Placeholder addresses

Chain	chain value	token_address placeholder
Any EVM chain	ethereum, base, arbitrum, …	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
Bitcoin	bitcoin	1111111111111111111114oLvT2
NEAR	near	native-token.near
Solana	solana	So11111111111111111111111111111111111111112
SUI	sui	0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI
TON	ton	0:0000000000000000000000000000000000000000000000000000000000000000
Tron	tron	TXka46PPwttNPWfFDPtt3GUodbPThyufaV
Injective	injective	0x0000000088827d2d103ee2d9a6b781773ae03ffb

Chains not listed above have no native-token placeholder. See Supported Chains for the full chain list.

Pairing the EVM placeholder with a chain

There is one placeholder for all EVM chains. It does not mean "ETH" — it means "whatever this chain's native coin is". The chain field decides which coin you get:

// ETH on Ethereum
{"chain": "ethereum", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"}

// BNB on BNB Chain
{"chain": "bnb", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"}

// POL on Polygon
{"chain": "polygon", "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"}

The placeholder itself is valid on any EVM chain — arbitrum, arc, avalanche, base, bitlayer, bnb, chiliz, citrea, ethereum, gravity, hyperevm, iotaevm, katana, linea, mantle, metis, monad, optimism, plasma, polygon, robinhood, sei, sonic, viction.

Passing address validation is not the same as the endpoint supporting that chain, though. Individual endpoints accept narrower chain sets than the list above — TGM Holders, for instance, omits several of them. Treat the placeholder as valid on any EVM chain the endpoint itself supports, and check the endpoint's own chain values in Supported Chains.

Injective is not an EVM chain here. Its placeholder looks like a 40-hex EVM address, but Injective is classified as non-EVM by the API. Use 0x0000000088827d2d103ee2d9a6b781773ae03ffb with chain: "injective". Sending the EVM placeholder 0xeeee… with chain: "injective" is rejected, and sending the Injective placeholder with chain: "ethereum" is rejected too.

Mismatched chain and placeholder

Pairing a placeholder with a chain it doesn't belong to returns HTTP 422 with error code invalid_address_format:

// Request — Solana's placeholder on Ethereum
{"chain": "ethereum", "token_address": "So11111111111111111111111111111111111111112"}

// 422 response — abbreviated to the fields specific to this error
{
  "error": "Invalid address format",
  "code": "invalid_address_format",
  "message": "Address 'So11111111111111111111111111111111111111112' appears to be a solana address format but the chain is set to ethereum. Please verify the address is correct for the ethereum chain."
}

The real response also carries the standard envelope fields (status, request_id, doc_url, and param where applicable). See Error Handling for the full shape.

Copy each placeholder exactly as listed

Send every placeholder byte-for-byte as it appears in the table above. Hex-shaped addresses are lowercased for you, but the base58 and type-string placeholders are compared literally, and what happens when you miscase one is not consistent:

Miscased input	Result
0xEEEE… (EVM), 0x…88827D2D… (Injective)	Accepted. Both are hex addresses and are lowercased before the native-token lookup.
NATIVE-TOKEN.NEAR	Rejected — fails address-format validation.
txka46pp… (Tron)	Rejected — the lowercase form no longer matches the Tron address pattern.
so1111…112 (Solana), 0x…::sui::sui (SUI)	Silently not native. Still a structurally valid address, so validation passes, but it is not recognized as the native token and is treated as an ordinary token address instead.

That last row is the dangerous one: the request succeeds, so nothing tells you the placeholder was wrong. If a Solana or SUI native-token query returns results you did not expect, check the placeholder's casing first.

In short: case-sensitivity tracks the address format, not whether the chain is EVM. That is why Injective, despite being non-EVM, is as forgiving as Ethereum here.

Example: ETH holders

chain is what makes the shared EVM placeholder mean ETH rather than BNB or POL:

curl -s -X POST "https://api.nansen.ai/api/v1/tgm/holders" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -d '{
    "chain": "ethereum",
    "token_address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "label_type": "all_holders",
    "pagination": {"page": 1, "per_page": 10}
  }'

This request lands on the restricted path described in Token God Mode Holders behaves differently for native tokens — native token, all_holders, no entity aggregation, not Bitcoin — so sort by token_amount only, and expect sub-$1 holders in the response.

Coverage limitations

Native tokens are held by tens of millions of addresses and move in every gas payment on the chain, so the analytics that work well for a contract token are often either unavailable or computed differently. Concretely:

Endpoints that reject native tokens

These return HTTP 422 with error code invalid_field_value and a message naming the endpoint. There is no workaround — use a different endpoint.

Endpoint	Native tokens rejected on
POST /api/v1/tgm/flows	All chains
POST /api/v1/tgm/pnl-leaderboard	All chains
POST /api/v1/tgm/historical-pnl-leaderboard	All chains
POST /api/v1/tgm/jup-dca	All chains
POST /api/v1/tgm/transfers	All chains except bitcoin
POST /api/v1/tgm/dex-trades	solana only
POST /api/v1/tgm/historical-dex-trades	solana only
POST /api/v1/tgm/historical-token-flow-summary	solana only
POST /api/v1/tgm/holders	solana only
POST /api/v1/profiler/address/counterparties	solana only
POST /api/v1/profiler/address/counterparties/batch	solana only — checked per address, so one native address rejects the whole batch

Two patterns are worth internalising:

• Per-holder PnL is unavailable for native tokens on every chain. Both PnL leaderboards reject them outright, as does TGM Flows. A native coin is spent as gas in nearly every transaction on its chain, so a per-holder cost basis does not carry the same meaning it does for a traded contract token.

• Solana is blocked on more endpoints than other chains. Native SOL appears in almost every Solana transaction, which makes these queries prohibitively expensive to serve.

Note that this does not mean all flow analytics are off-limits: Flow Intelligence does support native tokens, and only serves them from a different source.

Token God Mode Holders behaves differently for native tokens

POST /api/v1/tgm/holders does support native tokens (except on Solana), but one specific combination is served from a different, purpose-built data path that trades flexibility for the ability to return at all. You are on that path when all of the following hold:

• the token is a native token (or a major stablecoin), and

• label_type is "all_holders", and

• aggregate_by_entity is false, and

• the chain is not bitcoin — Bitcoin always uses the entity-based path instead.

Change any one of those and the endpoint behaves normally. On that path, unsupported options return HTTP 400:

Restriction	Detail
Filters	Only include_smart_money_labels, exclude_smart_money_labels, address, token_amount, total_inflow, total_outflow. Filters such as value_usd, ownership_percentage, and balance-change filters are not available.
address filter	Accepts a single address only, not a list.
Sorting	Only token_amount is sortable (default DESC).

Dust holders are included. Elsewhere this endpoint applies a default minimum of $1 in holdings. On the path described above that default is not applied, so results include holders worth well under $1. Add a token_amount filter if you need a floor.

Flow Intelligence uses a different source

POST /api/v1/tgm/flow-intelligence serves native tokens from an entity-based flow dataset rather than the standard token-transfer dataset. The response shape is the same, but figures are not directly comparable to a contract token's, and segment breakdowns may be coarser. Treat native-token flow figures as directional rather than as an exact match to contract-token methodology.

Two status codes worth recognising

Native tokens cover far more holders and transfers than a typical contract token, so these two responses are worth knowing when you query them:

Status	What the API returns	What it means
512	Query timed out. Please try adjusting the time range or filtering the data.	The query exceeded its time budget. Narrow the date range or add filters, as the message says.
514	Unauthorized. Please try with different parameters or another endpoint.	Despite the wording, this is not an API-key problem — a valid key returns it. It signals that the backend would not serve this particular query. Some Token God Mode analytics on native tokens are a known cause, so try different parameters or another endpoint before treating it as an auth failure.

See Error Handling for the general error model.

The include_native_tokens filter

Some endpoints return a portfolio, flow, or screen across many tokens rather than taking a single token_address. Because native holdings usually dominate those aggregates in USD terms, these endpoints let you include or exclude native tokens explicitly via a filter:

{
  "filters": {
    "include_native_tokens": true
  }
}

Endpoint	Default
POST /api/v1/smart-money/holdings	false — native tokens excluded
POST /api/v1/smart-money/netflow	false — native tokens excluded
POST /api/v1/smart-money/historical-holdings	false — native tokens excluded
POST /api/v1/token-screener	false — native tokens excluded
POST /api/v1beta1/smart-money/historical-token-balances	true — native tokens included

On two of these the flag covers more than the native coin itself:

• Token screener — also admits wrapped-native assets and liquid staking / restaking derivatives (LSTs and LRTs).

• historical-token-balances — also admits LSTs and LRTs.

So on those endpoints, toggling the flag moves a broader set of rows than the native coin alone.

The default is not the same everywhere. Most of these endpoints default to excluding native tokens, but historical-token-balances defaults to including them. If you are comparing results across these endpoints, set include_native_tokens explicitly rather than relying on the default.

This filter exists only on the endpoints listed above. Sending it elsewhere is not reliably an error: most filter models reject unknown keys with HTTP 422, but some accept and silently ignore them, so the request succeeds while the flag does nothing. Don't infer from a 200 that an endpoint honoured include_native_tokens — only rely on it where it is documented.

Quick reference

• Native tokens are addressed by a per-chain placeholder, not a contract address.

• One placeholder covers every EVM chain; chain selects which native coin you mean.

• Copy placeholders exactly; miscasing the Solana or SUI placeholder fails silently rather than erroring.

• PnL leaderboards and TGM Flows reject native tokens on all chains; DEX trades and transfers are blocked on some chains; holders, balances, and Flow Intelligence work with restrictions.

• On multi-token endpoints, set include_native_tokens explicitly rather than relying on the default.