Deepstate Market Data

Deepstate is an on-chain central limit order book protocol on Robinhood Chain (chain id 4663). OneSource serves its market data, order books, trades, candles, stats, maker analytics, gas cost-to-quote, and depth history, as a separate route family on the same host as the rest of the API.

Base URL: https://api.onesource.io/deepstate/v1/...
OpenAPI spec: /deepstate/openapi.yaml (free, no auth)
Network: Robinhood Chain only. These routes take no network parameter.

Path convention

A OneSource route's first path segment names its data family and the second names that family's own version, so /deepstate/v1/* versions independently of /api/chain/* (the original chain-RPC family, which keeps its own conventions under a different first segment).

Authenticating and paying

The same three access paths as the rest of the API work here: Authorization: Bearer <api key> on a developer plan or above, or pay per call with x402 (USDC on Base) or MPP (Tempo). See Getting Started to pick one.

import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { registerExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch('https://api.onesource.io/deepstate/v1/markets');
const { markets } = await res.json();

See x402 on Base for the full client setup, including AgentCash and the MCP server, or MPP on Tempo for the Tempo equivalent.

Pricing

Routes	Price per call
`/deepstate/v1/markets`, `/book/{book}`, `/trades/{book}`, `/candles/{book}`, `/stats/{book}`	$0.005
`/deepstate/v1/analytics/*` (`makers`, `cost-to-quote`, `depth-history`)	$0.02
`/deepstate/v1/health`, `/deepstate/openapi.yaml`	Free

Response shape

Deepstate routes return the payload directly, with no {data, error, meta} envelope: a successful call's body is the result. A failure is { "error": "<code>", "message": "<detail>" }. See Errors below.

Cache-Control varies by route: most are public, max-age=5, /deepstate/v1/markets is public, max-age=300 (it's static, compiled-in configuration), and /deepstate/v1/book/{book} is no-store, since a snapshot names the exact block it was read at and is never meant to be cached.

Identifying a book

Pass the canonical uppercase slug (NVDA-USDG, DEEP-USDG) or the 32-byte hex book id. A lowercase slug is accepted and normalized. Call GET /deepstate/v1/markets first for the current list.

book/trades/candles/stats take book as a path segment (/deepstate/v1/book/NVDA-USDG); the analytics routes take it as a required query parameter (?book=NVDA-USDG), since each is denominated in that one book's own unit and can't be summed across books.

Endpoints

Full parameter, schema, and status-code detail lives in the OpenAPI spec. The eight routes below are the curated surface; a few other routes exist on the same spec but aren't part of this reference.

`GET /deepstate/v1/markets`

The configured Deepstate markets, with token layout and pool/router addresses. Static configuration, safe to cache client-side. Call this first; every other route below takes a book identifier from its response.

curl https://api.onesource.io/deepstate/v1/markets \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "markets": [
    {
      "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
      "book_slug": "NVDA-USDG",
      "book_label": "NVDA/USDG",
      "base_token": { "address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC", "symbol": "NVDA", "decimals": 18 },
      "quote_token": { "address": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", "symbol": "USDG", "decimals": 6 },
      "status": "live"
    }
  ]
}

`GET /deepstate/v1/book/{book}`

Order-book snapshot: bids descending, asks ascending, with each price level's resting size. Reflects the last completed on-chain state read rather than every intervening block; block_number names the exact height it was read at.

Parameter	In	Description
`book`	path	Book slug or id (required)
`depth`	query	Max price levels per side, 1-500, default 50

curl "https://api.onesource.io/deepstate/v1/book/NVDA-USDG?depth=50" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "block_number": 52685677,
  "finality": "head",
  "bids": [{ "price_raw": "216.48219249", "size_raw": "3263516552", "side": "bid", "maker": "0x884a..." }],
  "asks": [{ "price_raw": "220.47924566", "size_raw": "32945180000", "side": "ask", "maker": "0x7C3e..." }],
  "summary": { "best_bid_raw": "216.48219249", "best_ask_raw": "220.47924566", "mid_raw": "218.48071908", "spread_bps": 182.9476 }
}

`GET /deepstate/v1/trades/{book}`

Trade tape, newest first: each fill's price, size, side, and the block it happened in.

Parameter	In	Description
`book`	path	Book slug or id (required)
`limit`	query	Max trades returned, 1-500, default 100
`before`	query	Return trades strictly below this block number, for paging backward

curl "https://api.onesource.io/deepstate/v1/trades/NVDA-USDG?limit=100" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "trades": [
    {
      "block_number": 52685331,
      "transaction_hash": "0xa1c3...",
      "side": "bid",
      "attribution": "exact",
      "price_raw": "216.47999901",
      "base_amount_raw": "7381992258086111446",
      "quote_amount_raw": "1598069869"
    }
  ],
  "next_before": 52685331
}

A trade's attribution marks how confidently it was priced: exact fills carry a measured fee split, unpriced fills omit price_raw and the amount fields entirely rather than publish a wrong number.

`GET /deepstate/v1/candles/{book}`

OHLCV candles. Open/high/low/close are real trade prices, not recomputed; volumes are exact sums.

Parameter	In	Description
`book`	path	Book slug or id (required)
`tf`	query	Timeframe: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w` (required)
`from` / `to`	query	Inclusive/exclusive window bounds, RFC 3339 or unix seconds

curl "https://api.onesource.io/deepstate/v1/candles/NVDA-USDG?tf=1h" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "tf": "1h",
  "candles": [
    {
      "t": "2026-09-02T14:00:00Z",
      "open_raw": "216.43128523",
      "high_raw": "220.47999716",
      "low_raw": "215.70112004",
      "close_raw": "216.47999901",
      "volume_quote_raw": "412330119842",
      "trades": 14,
      "open_bucket": false
    }
  ]
}

`GET /deepstate/v1/stats/{book}`

Rolling 24h / 7d / 30d volume and price change, plus the latest traded price.

Parameter	In	Description
`book`	path	Book slug or id (required)

curl https://api.onesource.io/deepstate/v1/stats/NVDA-USDG \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "last_price_raw": "216.48219249",
  "windows": {
    "24h": { "volume_quote_raw": "500000000000", "trades": 24, "change_pct": -1.82, "high_raw": "220.47999716", "low_raw": "215.70112004" },
    "7d": { "volume_quote_raw": "19800000000000", "trades": 171, "change_pct": 2.41 }
  }
}

`GET /deepstate/v1/analytics/makers`

Per-maker analytics over a time window: time spent at the top of book, current resting notional, fill count and fill rate, and DEEP rewards earned. Rows are keyed by maker (resting-order owner) address.

Parameter	In	Description
`book`	query	Book slug or id (required)
`from` / `to`	query	Inclusive/exclusive window bounds, RFC 3339 or unix seconds
`limit`	query	Max rows returned, 1-500, default 50

curl "https://api.onesource.io/deepstate/v1/analytics/makers?book=NVDA-USDG" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "rewards_available": true,
  "rows": [
    {
      "maker": "0x6cf19308C22FC82ea620Fa0B3E94948d20f27B96",
      "time_at_top_bid_seconds": 41820,
      "notional_rested_raw": "82441000000",
      "fill_count": 194,
      "fill_rate": 0.86,
      "deep_earned_raw": "1811294000000000000000"
    }
  ]
}

rewards_available is false on a book with no reward hook (DEEP/USDG today); deep_earned_raw is omitted from every row on such a book rather than reported as zero.

`GET /deepstate/v1/analytics/cost-to-quote`

Gas spent resting and cancelling orders, bucketed over time: total fee, median fee, and how much of the fee is L2-to-L1 data cost.

Parameter	In	Description
`book`	query	Book slug or id (required)
`from` / `to`	query	Inclusive/exclusive window bounds, RFC 3339 or unix seconds
`res`	query	Bucket width: `1h` or `1d`, default `1d`

curl "https://api.onesource.io/deepstate/v1/analytics/cost-to-quote?book=NVDA-USDG&res=1d" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "resolution": "1h",
  "buckets": [
    { "bucket": "2026-09-02T14:00:00Z", "tx_count": 402, "rests": 219, "cancels": 198, "total_fee_raw": "48973600000000000", "l1_share_pct": 18.75 }
  ],
  "totals": { "tx_count": 790, "rests": 427, "cancels": 385, "total_fee_raw": "100178400000000000" }
}

`GET /deepstate/v1/analytics/depth-history`

A depth heatmap: resting order size by price level over time, bucketed and optionally restricted to one side.

Parameter	In	Description
`book`	query	Book slug or id (required)
`side`	query	Restrict to `bid` or `ask`. Default both
`from` / `to`	query	Inclusive/exclusive window bounds, RFC 3339 or unix seconds
`res`	query	Bucket width: `1h` or `1d`, default `1d`

curl "https://api.onesource.io/deepstate/v1/analytics/depth-history?book=NVDA-USDG&res=1h" \
  -H "Authorization: Bearer $ONESOURCE_API_KEY"

{
  "book_id": "0xdf941c235503a5d2e67aee5dea00f2965f99421c0d034bd77f924c05c66bf399",
  "book_label": "NVDA/USDG",
  "resolution": "1h",
  "size_token": { "address": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", "symbol": "USDG", "decimals": 6 },
  "points": [
    { "bucket": "2026-09-02T15:00:00Z", "side": "bid", "price_raw": "216.480000000000000000", "size_raw": "5213000000", "order_count": 4, "denominated_order_count": 4 },
    { "bucket": "2026-09-02T15:00:00Z", "side": "ask", "price_raw": "220.480000000000000000", "order_count": 3, "denominated_order_count": 0 }
  ],
  "coverage": { "order_count": 253, "denominated_order_count": 129 }
}

Each level's size_raw is denominated in the book's size_token (token0, which is not always the quote token). It's omitted, never reported as zero, when every resting order at that level can't be attributed a size; coverage reports the split across the whole response so a caller can tell how complete the heatmap is.

Errors

Deepstate errors are a single flat shape: { "error": "<code>", "message": "<detail>" }. An anonymous call to a paid route gets the same 402 payment challenge as any other paid endpoint (see x402 on Base or MPP on Tempo); a Bearer call with an invalid or missing key gets the same gateway auth errors described in Error codes → Gateway errors. Deepstate does not use the {data, error, meta} envelope that /api/chain/* routes do.

MCP tools

@one-source/mcp exposes these eight Deepstate tools, all category deepstate. Unlike the chain tools, none take a network parameter: Deepstate data is always Robinhood Chain.

Tool	Endpoint	What it returns
`1s_ds_markets`	`GET /deepstate/v1/markets`	The configured Deepstate markets, with token layout and pool/router addresses
`1s_ds_book`	`GET /deepstate/v1/book/{book}`	Order-book snapshot: bids descending, asks ascending
`1s_ds_trades`	`GET /deepstate/v1/trades/{book}`	Trade tape, newest first
`1s_ds_candles`	`GET /deepstate/v1/candles/{book}`	OHLCV candles
`1s_ds_stats`	`GET /deepstate/v1/stats/{book}`	Rolling 24h/7d/30d volume and price change
`1s_ds_makers`	`GET /deepstate/v1/analytics/makers`	Per-maker time-at-top, resting notional, fills, and DEEP rewards earned
`1s_ds_cost_to_quote`	`GET /deepstate/v1/analytics/cost-to-quote`	Gas spent resting and cancelling orders
`1s_ds_depth_history`	`GET /deepstate/v1/analytics/depth-history`	Depth heatmap: resting size by price level over time

They're priced and authenticated like their REST counterparts (see Pricing above). See MCP tool reference for the full tool catalog alongside the chain tools.

Getting Started: pick an access path
MCP tool reference: every tool the MCP server exposes
Error codes: the chain routes' error shapes (Deepstate's is simpler; see Errors above)

Path convention​

Authenticating and paying​

Pricing​

Response shape​

Identifying a book​

Endpoints​

GET /deepstate/v1/markets​

GET /deepstate/v1/book/{book}​

GET /deepstate/v1/trades/{book}​

GET /deepstate/v1/candles/{book}​

GET /deepstate/v1/stats/{book}​

GET /deepstate/v1/analytics/makers​

GET /deepstate/v1/analytics/cost-to-quote​

GET /deepstate/v1/analytics/depth-history​

Errors​

MCP tools​

Next​