# Arkham Token Top Flow by ID

> Arkham Token Top Flow by ID is a paid API for AI agents from api.arkm.com, paid per call via x402, $2/call, status unknown (last checked 2026-09-14).

Returns the top inflow and outflow addresses for a specific token, ranked by USD volume, with Arkham entity and label metadata.

## Facts

- Endpoint: POST https://api.arkm.com/x402/token/top-flow/by-id
- Price: $2/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/arkham-token-top-flow-by-id-cd300e8a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_sp_MJiDJY9ayD8TsbGQli

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 arkham-token-top-flow-by-id-cd300e8a -d '<json body>'
```

Example prompt: Pull the top flow addresses for Morpho (by Arkham token ID) on Ethereum — show me which wallets or entities are sending and receiving the most in USD.

## When to prefer this

Use this endpoint when you need to identify the most active wallet addresses or entities moving a specific token, ranked by USD volume, with rich Arkham entity labels attached. Prefer this over generic on-chain explorers when you need pre-resolved entity metadata (DeFi protocol names, Twitter handles, entity type classifications) rather than raw addresses. Best suited for token-level flow analysis where you want to quickly surface whales, protocols, or institutional participants.

## Known failure modes

- Invalid or unknown token ID returns empty array or 404
- Missing or invalid x402 payment header results in 402 Payment Required
- Insufficient USDC balance causes payment failure and no data returned
- Token with no recorded flows returns empty result set
- Rate limiting if too many requests are submitted in rapid succession

## How this service works

Get Arkham top token flow by pricing ID. $2.00 per call.

## Output

Returns a ranked list of addresses with their total inflow and outflow values in both USD and native token units, along with chain, contract status, Arkham label (name), and full Arkham entity metadata (entity type, name, Twitter, website, LinkedIn, Crunchbase) where available.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "id": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "The CoinGecko pricing ID of the token."
  },
  "limit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Maximum number of addresses to return per flow direction. Default: 50. Max: 100."
  },
  "chains": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Chains to filter by, as a single comma-separated string, e.g. 'ethereum,bsc' (not a JSON array). If omitted, returns al…"
  },
  "timeLast": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "number"
    },
    {
     "type": "boolean"
    },
    {
     "type": "array",
     "items": {
      "anyOf": [
       {
        "type": "string"
       },
       {
        "type": "number"
       },
       {
        "type": "boolean"
       }
      ]
     }
    }
   ],
   "description": "Time range filter using relative durations."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": [
  {
   "inUSD": 12979047524.19118,
   "outUSD": 12971777421.73696,
   "address": {
    "chain": "ethereum",
    "address": "0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb",
    "contract": true,
    "arkhamLabel": {
     "name": "Morpho Blue",
     "address": "0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb",
     "chainType": "evm"
    },
    "arkhamEntity": {
     "id": "morpho",
     "name": "Morpho",
     "note": "",
     "type": "lending-decentralized",
     "service": null,
     "twitter": "https://twitter.com/MorphoLabs",
     "website": "https://morpho.org",
     "linkedin": "https://www.linkedin.com/company/morpho-labs",
     "crunchbase": "https://www.crunchbase.com/organization/morpho-labs"
    },
    "isUserAddress": false
   },
   "inValue": 12979047525.96132,
   "outValue": 12971777423.62608
  },
  {
   "inUSD": 4866908061.438353,
   "outUSD": 4866351186.855593,
   "address": {
    "chain": "base",
    "address": "0x61040E143A77F165Ba44543AF4A079F2C809D14b",
    "contract": true,
    "arkhamLabel": {
     "name": "Proxy (EIP-1967 Transparent)",
     "address": "0x61040E143A77F165Ba44543AF4A079F2C809D14b",
     "chainType": "evm"
    },
    "isUserAddress": false
   },
   "inValue": 4866908062.542056,
   "outValue": 4866351187.380329
  }
 ]
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/arkham-token-top-flow-by-id-cd300e8a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.arkm.com](https://www.zero.xyz/host/api.arkm.com/llms.txt)