# GET /token/whales: $0.02 per call

Whale and exchange flows for a token on Base, Ethereum, Arbitrum, Optimism or Polygon, from its latest ~250 transfers: large transfers, deposits/withdrawals per exchange (Binance, Coinbase, OKX...), fund and market-maker flows, DEX buys vs sells, top accumulating and distributing wallets, and plain signals. Pass ?address=...&chain=ethereum&minUsd=10000.

- **Price:** $0.02 in USDC, the same on Base, Solana, Polygon, Arbitrum. Failed calls are never charged.
- **Free trial:** yes, 20 free calls a day from Claude, Cursor or any MCP client ([set-up](/mcp/setup)).
- **Answers cached for:** 1 min
- **Data sources:** Blockscout (free); DexScreener (free); GeckoTerminal (free, fallback); DefiLlama prices (free, fallback)
- **Lane:** Crypto & on-chain ([OpenAPI](/openapi/crypto.json))
- **Live health:** [status page](/status)

## Free sample

See an answer for the demo input first, free (no payment, 10 a minute): [https://aayatai.com/sample/token-whales](/sample/token-whales). It is a stored real answer when we have one, otherwise an example marked `"kind": "illustrative"`.

```bash
curl "https://aayatai.com/sample/token-whales"
```

## 1. See the price (free)

Call it without paying: you get `402 Payment Required` and a `PAYMENT-REQUIRED` header with the exact price and where to pay.

```bash
curl -i "https://aayatai.com/token/whales?address=0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed&chain=base&minUsd=10000"
```

## 2. Pay and call (TypeScript)

```bash
npm install @x402/fetch @x402/evm viem
```

```ts
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// A wallet used only by your agent, holding a little USDC on Base.
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://aayatai.com/token/whales?address=0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed&chain=base&minUsd=10000");
console.log(await res.json());
```

## 3. Or as an MCP tool

```ts
// MCP server: https://aayatai.com/mcp (Streamable HTTP). With the x402 MCP client (see /start):
const result = await client.callTool("token-whales", {"address":"0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed","chain":"base","minUsd":10000});
```

## Inputs

- `address` **(required)** (string): Token contract address (0x...).
- `chain` (string; one of `base`, `ethereum`, `arbitrum`, `optimism`, `polygon`; default `base`): Blockchain: base, ethereum, arbitrum, optimism, polygon.
- `minUsd` (number; default `10000`): Smallest transfer (USD) counted as a whale move.

Bad inputs are rejected with HTTP 400 before any payment is asked for.

## Example answer

```json
{
  "address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "chain": "ethereum",
  "symbol": "PEPE",
  "priceUsd": 0.0000042,
  "window": {
    "transfers": 250,
    "from": "2026-09-28T03:40:00Z",
    "to": "2026-09-28T04:00:11Z",
    "minutes": 20.2
  },
  "exchangeFlowsUsd": {
    "deposits": 52592,
    "withdrawals": 0,
    "net": -52592
  },
  "byExchange": [
    {
      "exchange": "Binance",
      "depositsUsd": 52592,
      "withdrawalsUsd": 0,
      "netUsd": -52592
    }
  ],
  "dexFlowsUsd": {
    "buys": 500,
    "sells": 39993
  },
  "fundFlowsUsd": {
    "received": 79825,
    "sent": 0
  },
  "topAccumulators": [
    {
      "address": "0xf8191D98ae98d2f7aBDFB63A9b0b812b93C873AA",
      "label": "Wintermute 4",
      "kind": "fund",
      "netUsd": 79825
    }
  ],
  "topDistributors": [
    {
      "address": "0x8CEfE1bB988f8a574E69156a35e65685cDaa7080",
      "label": null,
      "kind": "wallet",
      "netUsd": -173661
    }
  ],
  "largeTransfers": [
    {
      "tx": "0x1bcb...",
      "time": "2026-09-28T03:59:35Z",
      "from": "0x8CEf...",
      "fromLabel": null,
      "to": "0x24F6...",
      "toLabel": null,
      "amount": 41456469482.32,
      "valueUsd": 173661,
      "type": "transfer"
    }
  ],
  "signals": [
    {
      "direction": "bearish",
      "code": "exchange_inflow",
      "message": "Net $52,592 moved onto exchanges (often ahead of selling)."
    }
  ],
  "bias": "bearish",
  "note": "",
  "source": "Blockscout (labels incl. Open Labels Initiative), DexScreener",
  "checkedAt": "2026-09-28T12:00:00.000Z"
}
```

## Related

- [GET /token/price](/services/token-price) ($0.005): Live price of any token on Base, Solana, Ethereum, BNB, Arbitrum, Polygon, Optimism or Avalanche from DEX data: USD price, total liquidity, 24h volume, buys/sel
- [GET /token/safety](/services/token-safety) ($0.02): Rug-pull and scam check for any token on Base, Solana, Ethereum, BNB, Arbitrum, Polygon, Optimism or Avalanche.
- [GET /token/report/cached](/services/token-report-cached) ($0.05): Full token report, cached tier (answers up to 15 minutes old, half price): safety (honeypot, taxes, owner powers), holders (concentration, exchange/fund/locked 
- [GET /token/report](/services/token-report) ($0.10): Full token report, live: safety (honeypot, taxes, owner powers), holders (concentration, exchange/fund/locked share), liquidity (depth, locks, pools), price act
- [GET /token/report/deep](/services/token-report-deep) ($0.25): Deep token report: everything in /token/report (safety (honeypot, taxes, owner powers), holders (concentration, exchange/fund/locked share), liquidity (depth, l
- [GET /token/new](/services/token-new) ($0.01): New token launches with real liquidity: tokens whose first DEX pool opened in the last hour (up to 24h) with at least $10k liquidity (adjustable), newest first,
- [GET /wallet](/services/wallet) ($0.01): Wallet profile on Base, Ethereum or Solana: native balance, token holdings with USD values (top 25), total portfolio value, whether it is a contract, ENS name, 
- [GET /wallet/deep](/services/wallet-deep) ($0.03): Deep wallet report on Base, Ethereum or Solana: everything in /wallet (balances, tokens, USD value) plus recent transactions and token transfers, in/out directi

New here? [Getting started in 60 seconds](/start). All services: [Aayat AI](/).