> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime data

> Prices, balances, transactions, DeFi positions, holdings PnL, tokens, and assets, without SQL.

Realtime tools wrap Allium's [Realtime APIs](/api/developer/overview) as MCP tool calls. Most take a chain plus a token or wallet address and return current or recent state for it.

<Tip>
  Call `get_realtime_supported_chains` **once per session** before any other realtime tool, and cache the result. It returns a map of endpoint path to supported chain names, and it's the one realtime tool that costs no Developer Units. Passing an unsupported chain returns an empty result or an error.
</Tip>

## Available tools

### Discovery

| Tool | Description |
| :- | :- |
| `get_realtime_supported_chains` | Which chains each realtime endpoint supports. Call once, cache it |

### Prices

| Tool | Description |
| :- | :- |
| `get_realtime_token_latest_price` | Latest price for one or many token/chain pairs |
| `get_realtime_token_price_history` | Price history at a chosen time granularity |
| `get_realtime_token_price_stats` | Volume, high/low, price and volume change |
| `get_realtime_token_price_at_timestamp` | Price of a token at a specific timestamp |

### Wallets

| Tool | Description |
| :- | :- |
| `get_realtime_wallet_latest_token_balances` | Latest fungible token balances across chains |
| `get_realtime_wallet_historical_token_balances` | Paginated historical balances over a time range |
| `get_realtime_wallet_transactions` | Rich transaction activity: activities, asset transfers, labels |
| `get_realtime_wallet_positions` | DeFi positions across protocols and chains |

### Holdings & PnL

| Tool | Description |
| :- | :- |
| `get_realtime_holdings_history` | Historical aggregated USD holdings for one or more addresses |
| `get_realtime_holdings_pnl` | PnL for a wallet |
| `get_realtime_holdings_pnl_history` | Historical PnL for a wallet |
| `get_realtime_holdings_pnl_by_token` | PnL for a wallet, broken down to one token |
| `get_realtime_holdings_pnl_by_token_history` | Historical PnL for a wallet and token |

### Tokens & assets

| Tool | Description |
| :- | :- |
| `list_realtime_chain_tokens` | List tokens, optionally sorted by a field |
| `search_realtime_chain_tokens` | Search tokens by query string |
| `get_realtime_tokens_by_chain_address` | Token details for given chain/address pairs |
| `list_realtime_crosschain_assets` | List assets |
| `get_realtime_crosschain_assets` | Get assets by ID, slug, or chain and address |

<Info>
  Hyperliquid trading data has its own tools. See [Hyperliquid](/ai/mcp/tools-reference/hyperliquid).
</Info>

## Every tool names its own docs

Each realtime tool's description ends with a `browse_docs` path pointing at the REST endpoint's full documentation: supported chains, edge cases, pagination, and response shape.

```json theme={null}
{
  "name": "browse_docs",
  "arguments": { "path": "api/developer/prices/token-latest-price.md" }
}
```

That's the authoritative reference for parameters. The examples below show the shape of a call, not the full field list.

| Tool | Docs path |
| :- | :- |
| `get_realtime_token_latest_price` | `api/developer/prices/token-latest-price.md` |
| `get_realtime_token_price_history` | `api/developer/prices/token-price-history.md` |
| `get_realtime_token_price_stats` | `api/developer/prices/token-price-stats.md` |
| `get_realtime_token_price_at_timestamp` | `api/developer/prices/token-price-at-timestamp.md` |
| `get_realtime_wallet_latest_token_balances` | `api/developer/wallets/latest-token-balances.md` |
| `get_realtime_wallet_historical_token_balances` | `api/developer/wallets/historical-token-balances.md` |
| `get_realtime_wallet_transactions` | `api/developer/wallets/transactions.md` |
| `get_realtime_wallet_positions` | `api/developer/defi-positions/get-positions.md` |
| `get_realtime_holdings_history` | `api/developer/holdings/holdings-history.md` |
| `get_realtime_holdings_pnl` | `api/developer/holdings/holdings-pnl.md` |
| `get_realtime_holdings_pnl_history` | `api/developer/holdings/holdings-pnl-history.md` |
| `get_realtime_holdings_pnl_by_token` | `api/developer/holdings/holdings-pnl-by-token.md` |
| `get_realtime_holdings_pnl_by_token_history` | `api/developer/holdings/holdings-pnl-by-token-history.md` |
| `list_realtime_chain_tokens` | `api/developer/tokens/list-tokens.md` |
| `search_realtime_chain_tokens` | `api/developer/tokens/search-tokens.md` |
| `get_realtime_tokens_by_chain_address` | `api/developer/tokens/get-tokens-by-chain-address.md` |
| `list_realtime_crosschain_assets` | `api/developer/assets/list-assets.md` |
| `get_realtime_crosschain_assets` | `api/developer/assets/get-assets.md` |

## Batching

Most realtime tools take a list of targets in one call. The field that holds the list is named differently per tool:

| Batch field | Tools |
| :- | :- |
| `payloads` | `get_realtime_token_latest_price`, `get_realtime_tokens_by_chain_address` |
| `addresses` | price history, price stats, price at timestamp, latest and historical balances, transactions, holdings history, all four PnL tools |
| `payload` | `get_realtime_wallet_positions` |
| `requests` | `get_realtime_crosschain_assets` |

## Tool usage

### Latest prices

Pass one entry or many in `payloads`.

```json theme={null}
{
  "name": "get_realtime_token_latest_price",
  "arguments": {
    "payloads": [
      { "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "chain": "ethereum" },
      { "token_address": "So11111111111111111111111111111111111111112", "chain": "solana" }
    ],
    "with_liquidity_info": true
  }
}
```

`with_liquidity_info: true` adds `total_liquidity_usd`. See [token liquidity filtering](/api/developer/data-tips#token-liquidity-filtering) for when that matters.

### Price history

```json theme={null}
{
  "name": "get_realtime_token_price_history",
  "arguments": {
    "addresses": [
      { "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "chain": "ethereum" }
    ],
    "start_timestamp": "2026-01-01T00:00:00Z",
    "end_timestamp": "2026-01-31T23:59:59Z",
    "time_granularity": "1h"
  }
}
```

Paginate with the `cursor` parameter.

### Wallet balances

```json theme={null}
{
  "name": "get_realtime_wallet_latest_token_balances",
  "arguments": {
    "addresses": [
      { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum" },
      { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "base" }
    ]
  }
}
```

Cover several chains by listing one entry per chain.

### Transactions

```json theme={null}
{
  "name": "get_realtime_wallet_transactions",
  "arguments": {
    "addresses": [
      { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum" }
    ],
    "limit": 100
  }
}
```

The response carries decoded activities, asset transfers, and address labels.

### DeFi positions

```json theme={null}
{
  "name": "get_realtime_wallet_positions",
  "arguments": {
    "payload": [
      { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum" }
    ],
    "limit": 100
  }
}
```

### Holdings and PnL

`get_realtime_holdings_history` gives aggregated USD holdings over time. The PnL tools split along two axes: current versus historical, and whole-wallet versus per-token.

```json theme={null}
{
  "name": "get_realtime_holdings_pnl",
  "arguments": {
    "addresses": [
      { "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "chain": "ethereum" }
    ],
    "min_liquidity": 10000
  }
}
```

The `_history` variants take `start_timestamp`, `end_timestamp`, and `granularity` alongside `addresses`. Of the holdings tools, only `get_realtime_holdings_history` paginates.

## SQL or realtime?

<CardGroup cols={2}>
  <Card title="Use realtime tools" icon="bolt">
    Get current state or recent history for a named wallet or token. Responses come back in single-digit seconds.
  </Card>

  <Card title="Use SQL" icon="database">
    Aggregate across many addresses, read full history, join across verticals, or build anything you want to chart. See [SQL & queries](/ai/mcp/tools-reference/sql-and-queries).
  </Card>
</CardGroup>

<Note>
  All realtime tools except `get_realtime_supported_chains` consume Developer Units, between 20 and 60 per call, multiplied by the number of batched inputs. See [Billing & limits](/ai/mcp/tools-reference/billing-and-limits).
</Note>

## Renamed tools

<Warning>
  These tools were renamed in September 2026. The old `realtime_*` names no longer run: calling them will return an error.
</Warning>

| Old name | New name |
| :- | :- |
| `realtime_get_supported_chains` | `get_realtime_supported_chains` |
| `realtime_token_latest_price` | `get_realtime_token_latest_price` |
| `realtime_token_price_history` | `get_realtime_token_price_history` |
| `realtime_token_price_stats` | `get_realtime_token_price_stats` |
| `realtime_token_price_at_timestamp` | `get_realtime_token_price_at_timestamp` |
| `realtime_latest_token_balances` | `get_realtime_wallet_latest_token_balances` |
| `realtime_historical_token_balances` | `get_realtime_wallet_historical_token_balances` |
| `realtime_get_positions` | `get_realtime_wallet_positions` |
| `realtime_transactions` | `get_realtime_wallet_transactions` |
| `realtime_list_tokens` | `list_realtime_chain_tokens` |
| `realtime_search_tokens` | `search_realtime_chain_tokens` |
| `realtime_get_tokens_by_chain_address` | `get_realtime_tokens_by_chain_address` |
| `realtime_holdings_history` | `get_realtime_holdings_history` |
| `realtime_holdings_pnl` | `get_realtime_holdings_pnl` |
| `realtime_holdings_pnl_history` | `get_realtime_holdings_pnl_history` |
| `realtime_holdings_pnl_by_token` | `get_realtime_holdings_pnl_by_token` |
| `realtime_holdings_pnl_by_token_history` | `get_realtime_holdings_pnl_by_token_history` |
| `realtime_info` | `get_realtime_hyperliquid_info` |
| `realtime_fills` | `get_realtime_hyperliquid_fills` |
| `realtime_order_history` | `get_realtime_hyperliquid_order_history` |
| `realtime_order_status` | `get_realtime_hyperliquid_order_status` |
| `realtime_orderbook_snapshot` | `get_realtime_hyperliquid_orderbook_snapshot` |
| `realtime_list_assets` | `list_realtime_crosschain_assets` |
| `realtime_get_assets` | `get_realtime_crosschain_assets` |

## Related resources

<CardGroup cols={2}>
  <Card title="Realtime APIs" icon="bolt" href="/api/developer/overview">
    The REST endpoints behind these tools
  </Card>

  <Card title="Prices API" icon="dollar-sign" href="/api/developer/prices/overview">
    Full prices reference
  </Card>

  <Card title="Wallets API" icon="wallet" href="/api/developer/wallets/overview">
    Full wallets reference
  </Card>

  <Card title="Hyperliquid tools" icon="chart-candlestick" href="/ai/mcp/tools-reference/hyperliquid">
    Perps info, fills, orders, orderbooks
  </Card>
</CardGroup>