On-Chain API

On-chain intelligence endpoints sourced from Nansen (smart money, holders) and WhaleAlert (whale transactions, exchange flows).

Base URL

https://api.mangrovedeveloper.ai/api/v1/on-chain

Authentication

All endpoints require a JWT bearer token.

Authorization: Bearer YOUR_JWT_TOKEN

Endpoints

Get smart-money sentiment

GET /api/v1/on-chain/smart-money/sentiment Whether smart-money wallets are accumulating or distributing a given token, with net inflow/outflow figures. Query Parameters:

symbol (string, required): Token symbol. Examples: ETH, UNI.
chain (string, optional): Blockchain. Default: ethereum.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/smart-money/sentiment?symbol=ETH&chain=ethereum"

Response (200 OK):

{
  "success": true,
  "symbol": "ETH",
  "chain": "ethereum",
  "sentiment": "accumulating",
  "smart_money_inflow_usd": 18500000.0,
  "smart_money_outflow_usd": 7200000.0,
  "net_flow_usd": 11300000.0,
  "trend_7d": "increasing",
  "data": {}
}

Screen smart-money tokens

GET /api/v1/on-chain/smart-money/screen Screen for tokens with the highest smart-money activity across one or more chains. Query Parameters:

chains (string, optional): Comma-separated chains. Default: ethereum.
timeframe (string, optional): One of 5m, 1h, 6h, 24h, 7d, 30d. Default: 24h.
limit (integer, optional): Max results. Default: 50.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/smart-money/screen?chains=ethereum,arbitrum&timeframe=24h&limit=10"

Response (200 OK):

{
  "success": true,
  "count": 10,
  "chains": ["ethereum", "arbitrum"],
  "timeframe": "24h",
  "tokens": [
    {
      "symbol": "PEPE",
      "chain": "ethereum",
      "smart_money_score": 92.4,
      "net_flow_usd": 4200000.0,
      "wallet_count": 38
    },
    {
      "symbol": "ARB",
      "chain": "arbitrum",
      "smart_money_score": 87.1,
      "net_flow_usd": 2900000.0,
      "wallet_count": 24
    }
  ]
}

Get token holders

GET /api/v1/on-chain/token-holders/{symbol} Holder distribution for a token, including concentration of the top 10 holders. Path Parameters:

symbol (string, required): Token symbol. Examples: ETH, UNI.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/token-holders/UNI"

Response (200 OK):

{
  "success": true,
  "symbol": "UNI",
  "holder_count": 425000,
  "top_10_holders_pct": 42.7,
  "concentration_score": 0.61,
  "data": {}
}

Get whale transactions

GET /api/v1/on-chain/whale-transactions Recent large-value on-chain transactions, optionally filtered by symbol and minimum USD value. Query Parameters:

symbol (string, optional): Filter by token symbol. Examples: btc, eth.
min_value (integer, optional): Minimum USD value per transaction. Default: 500000.
hours_back (integer, optional): Lookback window in hours. Default: 24.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/whale-transactions?symbol=eth&min_value=1000000&hours_back=24"

Response (200 OK):

{
  "success": true,
  "count": 23,
  "min_value_usd": 1000000.0,
  "transactions": [
    {
      "hash": "0xabc123...",
      "symbol": "ETH",
      "amount": 2400.0,
      "amount_usd": 7200000.0,
      "from": "0xUNKNOWN_WALLET",
      "to": "binance_hot_wallet",
      "timestamp": "2026-05-06T18:41:22Z"
    }
  ]
}

Get exchange flows

GET /api/v1/on-chain/exchange-flows Aggregated inflows/outflows across centralized exchanges, optionally filtered by token. Net positive = exchange inflows (often associated with sell pressure); net negative = outflows (often associated with accumulation/withdrawal). Query Parameters:

symbol (string, optional): Filter by token symbol. Examples: btc, eth. Omit for all currencies.
hours_back (integer, optional): Lookback hours. Default: 24.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/exchange-flows?symbol=btc&hours_back=24"

Response (200 OK):

{
  "success": true,
  "symbol": "btc",
  "timeframe": "24h",
  "net_flow_usd": -125000000.0,
  "flows": [
    {"exchange": "Binance",  "inflow_usd": 42000000.0, "outflow_usd": 95000000.0, "net_usd": -53000000.0},
    {"exchange": "Coinbase", "inflow_usd": 28000000.0, "outflow_usd": 72000000.0, "net_usd": -44000000.0}
  ]
}

Get whale activity summary

GET /api/v1/on-chain/whale-activity/{symbol} Aggregated whale activity for a single token over a lookback window. Path Parameters:

symbol (string, required): Token symbol. Examples: btc, eth.

Query Parameters:

hours_back (integer, optional): Lookback hours. Default: 24.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/whale-activity/btc?hours_back=24"

Response (200 OK):

{
  "success": true,
  "symbol": "btc",
  "hours_back": 24,
  "summary": {
    "transaction_count": 142,
    "total_volume_usd": 3800000000.0,
    "largest_tx_usd": 215000000.0,
    "to_exchanges_usd": 1200000000.0,
    "from_exchanges_usd": 1450000000.0
  }
}

Smart-money depth endpoints

The next three endpoints expose the full Nansen Pro smart-money surface. All accept the same JSON body shape and forward filters + order_by straight through to the upstream Nansen API, so you get the entire Pro-plan capability (restrict by include_smart_money_labels, set value_usd min/max bounds, sort by any field).

Smart-money historical holdings

POST /api/v1/on-chain/smart-money/historical-holdings Date-stamped snapshots of Smart Money token holdings across chains. Use this to track how aggregate Smart Money positions in a token evolve over time. Body:

{
  "chains": ["ethereum"],
  "date_range": {"from": "2026-05-22", "to": "2026-05-28"},
  "filters": {
    "include_smart_money_labels": ["Fund", "Smart Trader"],
    "value_usd": {"min": 100000}
  },
  "order_by": [{"field": "value_usd", "direction": "DESC"}],
  "page": 1,
  "per_page": 100
}

All fields are optional. Defaults: chains=["ethereum"], trailing 7-day date_range, no filters, no order_by, page=1, per_page=100.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"chains":["ethereum"],"date_range":{"from":"2026-05-22","to":"2026-05-28"},"per_page":5}' \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/smart-money/historical-holdings"

Response (200 OK):

{
  "success": true,
  "chains": ["ethereum"],
  "date_range": {"from": "2026-05-22", "to": "2026-05-28"},
  "filters": {"include_smart_money_labels": ["Fund"]},
  "order_by": [{"field": "value_usd", "direction": "DESC"}],
  "count": 5,
  "holdings": [
    {
      "date": "2026-05-28",
      "chain": "ethereum",
      "token_address": "0x...",
      "token_symbol": "UNI",
      "token_sectors": ["Decentralised Exchanges"],
      "smart_money_labels": ["Fund", "180D Smart Trader"],
      "value_usd": 24500000.0,
      "holders_count": 38
    }
  ]
}

Smart-money DEX trades

POST /api/v1/on-chain/smart-money/dex-trades Live DEX trades by Smart Money wallets across chains. Filter to specific labels (e.g. Fund only) and sort by recency. Body:

{
  "chains": ["ethereum"],
  "filters": {
    "include_smart_money_labels": ["Fund"],
    "side": "buy",
    "min_amount_usd": 10000
  },
  "order_by": [{"field": "block_timestamp", "direction": "DESC"}],
  "page": 1,
  "per_page": 100
}

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"chains":["ethereum"],"filters":{"include_smart_money_labels":["Fund"]},"per_page":5}' \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/smart-money/dex-trades"

Response (200 OK): Returns success, chains, filters, order_by, count, and a trades list. Each trade includes chain, block_timestamp, transaction_hash, trader_address, trader_address_label, token_bought_address, token_sold_address, value_usd, etc.

Smart-money perpetual-futures trades (Hyperliquid)

POST /api/v1/on-chain/smart-money/perp-trades Perpetual-futures trades by Smart Money wallets on Hyperliquid. Hyperliquid-only at the upstream — no chain filter is accepted. Body:

{
  "filters": {
    "side": "Long",
    "token_symbol": "BTC",
    "value_usd": {"min": 50000},
    "only_new_positions": true
  },
  "order_by": [{"field": "block_timestamp", "direction": "DESC"}],
  "page": 1,
  "per_page": 100
}

Valid filters.action values: Buy - Add Long, Sell - Reduce Long, Sell - Add Short, Buy - Reduce Short. Valid filters.type values: Market, Limit. Valid order_by.field values: block_timestamp, token_amount, price_usd, value_usd.

Python (via SDK)

result = client.on_chain.get_smart_money_perp_trades(
    filters={"side": "Long", "token_symbol": "BTC"},
    order_by=[{"field": "block_timestamp", "direction": "DESC"}],
    per_page=5,
)

Response (200 OK): success, venue="hyperliquid", filters, order_by, count, and a trades list.

Token-scoped depth endpoints

For when you want the full picture on a single token instead of broad smart-money reads. Both endpoints resolve symbol to an on-chain contract address via CoinGecko, so pass either the CoinGecko ID (uniswap) or a ticker.

Token DEX trades

POST /api/v1/on-chain/token/{symbol}/dex-trades DEX trades for a single token across all participants in a date window. Path: {symbol} — CoinGecko ID preferred (uniswap), or a ticker (UNI). Body:

{
  "chain": "ethereum",
  "date_range": {"from": "2026-05-22", "to": "2026-05-28"},
  "filters": {"action": "BUY", "min_amount_usd": 10000},
  "order_by": [{"field": "block_timestamp", "direction": "DESC"}],
  "page": 1,
  "per_page": 100
}

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"chain":"ethereum","date_range":{"from":"2026-05-22","to":"2026-05-28"},"per_page":5}' \
  "https://api.mangrovedeveloper.ai/api/v1/on-chain/token/uniswap/dex-trades"

Response (200 OK): success, symbol, chain, contract_address, date_range, filters, order_by, count, and a trades list.

Token flows

POST /api/v1/on-chain/token/{symbol}/flows Per-wallet-category flow aggregation (smart-money, whales, exchanges, fresh wallets, public figures) for a single token in a date window. Note: Nansen does not support stablecoins on this endpoint. Calls with stablecoin symbols return 404 RESOURCE_NOT_FOUND. Body: same shape as /token/{symbol}/dex-trades above.

Python (via SDK)

result = client.on_chain.get_token_flows(
    "uniswap",
    chain="ethereum",
    date_from="2026-05-22",
    date_to="2026-05-28",
    per_page=5,
)
for f in result.flows or []:
    print(f["date"], f["price_usd"], f["holders_count"],
          "in/out:", f["total_inflows_count"], "/", f["total_outflows_count"])

Response (200 OK): success, symbol, chain, contract_address, date_range, filters, order_by, count, and a flows list. Each row includes date, price_usd, token_amount, value_usd, holders_count, total_inflows_count, total_outflows_count, plus per-category aggregations.

Error Codes

Code	HTTP Status	Description
`MISSING_FIELD`	400	Required parameter missing (e.g. `symbol` on smart-money sentiment)
`INVALID_FIELD`	400	Invalid value for a constrained field (e.g. unsupported `timeframe` on flow-intelligence)
`AUTH_REQUIRED`	401	Missing or invalid bearer token
`RESOURCE_NOT_FOUND`	404	Token symbol not tracked by upstream provider, or stablecoin on `/token/{symbol}/flows`
`INTERNAL_ERROR`	500	Upstream provider (Nansen / WhaleAlert) error

​On-Chain API

​Base URL

​Authentication

​Endpoints

​Get smart-money sentiment

​Screen smart-money tokens

​Get token holders

​Get whale transactions

​Get exchange flows

​Get whale activity summary

​Smart-money depth endpoints

​Smart-money historical holdings

​Smart-money DEX trades

​Smart-money perpetual-futures trades (Hyperliquid)

​Token-scoped depth endpoints

​Token DEX trades

​Token flows

​Error Codes

On-Chain API

Base URL

Authentication

Endpoints

Get smart-money sentiment

Screen smart-money tokens

Get token holders

Get whale transactions

Get exchange flows

Get whale activity summary

Smart-money depth endpoints

Smart-money historical holdings

Smart-money DEX trades

Smart-money perpetual-futures trades (Hyperliquid)

Token-scoped depth endpoints

Token DEX trades

Token flows

Error Codes