# PreFlight Top Token Holders

> PreFlight Top Token Holders is a paid API for AI agents from meryol-agenticmarket-x402.hf.space, paid per call via x402, $0.003/call, status unknown (last checked 2026-09-13).

Returns the top N token holders for a given token on an EVM chain, including balance percentages, contract labels, and concentration metrics.

## Facts

- Endpoint: GET https://meryol-agenticmarket-x402.hf.space/holders/top/%7Bchain%7D/%7Btoken%7D
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/preflight-top-token-holders-3487f55a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Aev2zsSWIZaO-yJ8mDuvj

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability preflight-top-token-holders-3487f55a
```

Example prompt: Before I buy this token, can you pull the top 10 holders of 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 on Base and tell me what percentage of supply they control — and flag any that are known contracts like routers or exchanges?

## When to prefer this

Use this endpoint when you need to assess token holder concentration risk before executing a trade or signing a transaction on an EVM chain (Ethereum, Base, Arbitrum, Optimism). It is purpose-built for autonomous agent pre-trade checks and distinguishes known protocol contracts from real whale wallets, making it more useful than a raw blockchain query for risk assessment.

## Known failure modes

- Unsupported chain returns an error or empty response
- Invalid token contract address returns no holders
- Token with no on-chain holder data returns empty holders array
- Rate limiting or payment failure (x402) blocks the call
- Hugging Face Space cold start causes timeout

## How this service works

Pre-trade & pre-sign checks for autonomous agents: everything an agent verifies BEFORE signing a transaction — token due diligence, calldata red-flag decoding, oracle freshness, holder concentration, bridge routing with executable calldata, cross-venue perp funding, gas and price sanity checks. EVM chains: Ethereum, Base, Arbitrum, Optimism.

## Output

A JSON object listing the top N holders of the specified token on the given chain, each with their address, balance percentage, whether they are a contract, and a label (e.g. 'uniswap_v4_router') if recognized. Also returns aggregate concentration percentages — total top-N concentration and concentration excluding known protocol addresses — plus the token symbol and any warning notes.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "properties": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "chain": "base",
  "notes": [],
  "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "top_n": 10,
  "symbol": "USDC",
  "holders": [
   {
    "address": "0xabc...",
    "balance_pct": 8.1,
    "is_contract": true,
    "discount_label": "uniswap_v4_router"
   }
  ],
  "top_n_concentration_pct": 41.2,
  "top_n_concentration_ex_known_pct": 18.4
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/preflight-top-token-holders-3487f55a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from meryol-agenticmarket-x402.hf.space](https://www.zero.xyz/host/meryol-agenticmarket-x402.hf.space/llms.txt)