# Order Book (`flow_orderbook`)

> Best bid and ask, spread, depth and imbalance, with venue-labelled books and resting walls. Orders can be pulled: visible liquidity is evidence, not a promise of execution.

- Category: Order flow & whales
- MCP tool: `flow_orderbook`
- REST: `GET /flow/orderbook/{symbol}`
- MCP App: hosts that support MCP Apps render the result as an interactive view
- x402 price: $0.01 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/flow_orderbook

## What it does

Order-book snapshot for one coin's perpetuals: best bid/ask, spread in bps, top-of-book depth (USD) per side, bid/ask depth imbalance, and the cost vs mid of $10k and $100k market orders against the visible levels. Positive imbalance means more bid depth. Single-venue by nature — an on-chain perp exchange, falling back to a major exchange for coins it doesn't list; the response names the venue that answered and how far its visible book reaches.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "BTC". |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/flow/orderbook/BTC" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flow_orderbook",
    "arguments": {
      "symbol": "BTC"
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/flow/orderbook/BTC", {
  headers: { Authorization: `Bearer ${process.env.F1OW_API_KEY}` },
});
const data = await res.json(); // the tool's result as JSON, typed in the OpenAPI spec
console.log(data);
```

### Python

```python
import os, requests

res = requests.get(
    "https://mcp.f1ow.com/v1/flow/orderbook/BTC",
    headers={"Authorization": f"Bearer {os.environ['F1OW_API_KEY']}"},
)
data = res.json()  # the tool's result as JSON, typed in the OpenAPI spec
print(data)
```

### WebSocket

```jsonc
// wss://mcp.f1ow.com/v1/ws — subprotocol "jsonrpc-2.0", Authorization: Bearer <key>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flow_orderbook",
    "arguments": {
      "symbol": "BTC"
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "flow_orderbook",
    "arguments": {
      "symbol": "BTC"
    },
    "intervalSeconds": 60
  }
}
```

### x402

```bash
# No account: the first call answers 402 with a PAYMENT-REQUIRED challenge;
# an x402 client pays it in USDC on Base and retries.
curl "https://mcp.f1ow.com/x402/v1/flow/orderbook/BTC"
```

## Sample response

Captured 2026-11-13. The JSON is what REST and WebSocket return and the `structuredContent` of an MCP call (trimmed):

```json
{
  "asOfAt": "2026-11-13T08:05:41.8650000+00:00",
  "asOfMs": 1794557141865,
  "askDepthUsd": 8216498.9836,
  "bestAskUsd": 68648,
  "bestBidUsd": 68647,
  "bidDepthUsd": 4404340.68503,
  "fillCosts": [
    {
      "buyBps": 0.0728358643797833,
      "sellBps": 0.0728358643797833,
      "sizeUsd": 10000
    },
    {
      "buyBps": 0.0728358643797833,
      "sellBps": 0.0728358643797833,
      "sizeUsd": 100000
    }
  ],
  "imbalancePct": -30.2052668337543,
  "midPriceUsd": 68647.5,
  "source": "Hyperliquid",
  "spreadBps": 0.145671728759241,
  "symbol": "BTC",
  "visibleAskReachPct": 0.0284059871080489,
  "visibleBidReachPct": -0.0284059871080489,
  "generatedAt": "2026-11-13T08:05:41.8650000+00:00"
}
```

Over MCP the text report a model reads comes with it:

```text
BTC order book (Hyperliquid)
  bid $68647.00 / ask $68648.00 | spread 0.15 bps | mid $68647.50
  depth: bid $4404341 / ask $8216499 | imbalance -30.2%
  $10k market order, cost vs mid: buy 0.1 bps | sell 0.1 bps
  $100k market order, cost vs mid: buy 0.1 bps | sell 0.1 bps
  visible book: 20 bid / 20 ask levels, reaching -0.03% / +0.03% from mid; depth beyond is not visible
```

## Related tools

- [Whale Positions](https://www.f1ow.com/docs/tools/flow_whale_positions) — Live whale accounts: equity, side, notional, entry, leverage, unrealized PnL — and the reported liquidation price of each position.
- [Perp Price Levels](https://www.f1ow.com/docs/tools/flow_levels) — Executed volume profiles, value areas, thin zones, inferred long/short entries, realized liquidation prices and persistent resting walls across venues. Levels graded by traded, inferred or resting evidence, with confluence disclosed — not a price forecast.
- [Whale Context](https://www.f1ow.com/docs/tools/flow_whale_context) — The cohort view: exchange reserve changes, top-trader long/short lean, and the large exchange-linked transfers that tend to arrive before a move does.
- [Market Regime](https://www.f1ow.com/docs/tools/research_regime) — What kind of market you are trading in. Seven forces — trend, volatility, cycle, sentiment, leverage stress, ETF liquidity, rotation — each voting with its own reasoning and its own threshold for changing the call.