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> with an active subscription, 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.

Each market in GET /deepstate/v1/markets carries a status:

Status	Meaning
`live`	Trading normally, price feed confirmed
`price_decode_pending`	Book is live but its price key isn't decoded yet; don't build a valuation on its price fields
`legacy`	The book's token was superseded (resting orders remain, no new liquidity expected)
`registered`	Book exists on-chain but has no orders yet and no reward hook; exclude it from anything that walks book state until it flips to `live`

A market also carries has_rewarder and, when true, reward_token, the token its maker-rewards hook pays out. reward_token differs by market and can change over time (see the DGP-3 note below), so check it per market rather than assuming one token protocol-wide.

DGP-3 migration (2026-09-22)

Deepstate governance proposal DGP-3 executed at block 69224687, replacing the STATE and DEEP tokens with a single token, 2DEEP (0x62177377c361bf76F12612aA153a9b405bef9FF2, 18 decimals):

Legacy DEEP redeems 1:1 into 2DEEP, permanently.
Legacy STATE redeems into 2DEEP at a fixed rate (state_to_2deep, about 3.0155 2DEEP per STATE).
The DEEP/USDG book is now legacy: its resting orders are still real, but the book has no reward hook and no new liquidity is expected. A new 2DEEP/USDG book exists with status registered (no orders yet).
NVDA/USDG's maker-rewards hook was replaced by Rewarder V3, which pays out 2DEEP instead of DEEP (100M 2DEEP released over 365 days, scaled by the book's spread) and is documented as rewarder_epoch: v3 below.
The STATE vault is retired (GET /v1/vault/history reports status: "retired" and retired_at_block).
2DEEP's market price comes from the Uniswap v4 USDG/2DEEP pool.

Two routes track this directly: GET /v1/token/2deep for 2DEEP's own supply and float, and GET /v1/migration for redemption progress.

The reward and governance routes on the OpenAPI spec (/v1/rewards/*, /v1/governance/*) carry two fields to watch when a window spans the cutover:

rewarder_epoch: v1 (pre-DGP-3, paid DEEP), v3 (DGP-3 onward, pays 2DEEP), or mixed for a window straddling the cutover. reward_token is always present (falling back to the market's current token, 2DEEP, on a mixed read); reward_tokens lists both denominations when the read actually spans the cutover.
governor: v1 or v2, naming which Governor contract executed a given proposal, independent of parameters.governor, which always describes the currently deployed Governor (V2, voting on 2DEEP, as of DGP-3).

See the OpenAPI spec for the full schema of both routes.

Endpoints

Full parameter, schema, and status-code detail lives in the OpenAPI spec. The ten 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 },
      "has_rewarder": true,
      "reward_token": { "address": "0x62177377c361bf76F12612aA153a9b405bef9FF2", "symbol": "2DEEP", "decimals": 18 },
      "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 maker 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, since DGP-3); deep_earned_raw is omitted from every row on such a book rather than reported as zero. Despite its name, deep_earned_raw is denominated in whatever token the book's reward_token currently is, 2DEEP for NVDA/USDG since DGP-3, not necessarily DEEP; check GET /deepstate/v1/markets for the market's current reward_token before formatting it.

`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.

`GET /deepstate/v1/token/2deep`

2DEEP's supply, float, and migration figures, read live from chain rather than from an indexed snapshot. float_raw is total_supply_raw − rewarder_balance_raw − endowment_locked_raw: the NVDA/USDG reward pool and the team's multi-year grant are both accounted for in total_supply_raw but neither is spendable today. price_usdg/price_usdg_raw come from the Uniswap v4 2DEEP/USDG pool and are omitted, not null, until that pool has its first trade; price_source names the pool either way, so a caller can tell "no price yet" from "wrong pool".

legacy_deep_total_supply_raw is old DEEP's current total supply, not what is left to redeem: about 793M of it (unissued_legacy_rewarder_raw) is stranded forever in the retired Rewarder V1 contract and was never going to be traded in by anyone. For the actual redeemable figure, use GET /v1/migration's remaining_deep_redeemable_raw below.

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

{
  "token": { "address": "0x62177377c361bf76F12612aA153a9b405bef9FF2", "symbol": "2DEEP", "decimals": 18 },
  "as_of_block": 70869077,
  "finality": "head",
  "total_supply_raw": "394783654228296379381065133",
  "supply_cap_raw": "3000000000000000000000000000",
  "float_raw": "163284044836851443119333362",
  "rewarder_balance_raw": "98249089661542150686844051",
  "endowment_locked_raw": "133250519729902785574887720",
  "migration_liability_raw": "206689100066582620020137004",
  "issued_deep_liability_raw": "68227180426607635915937407",
  "initial_endowment_raw": "88581042885678265722915858",
  "unissued_legacy_rewarder_raw": "793310900933417380045066419",
  "state_to_2deep_wad": "3015535497731148791",
  "state_to_2deep": 3.0155354977311486,
  "legacy_deep_total_supply_raw": "833197789107693136084037755",
  "legacy_state_total_supply_raw": "45916196225894870554169371",
  "price_usdg_raw": "0.001129324479477382",
  "price_usdg": 0.001129324479477382,
  "price_source": "uniswap_v4:0x2d420ffa43f657344796377daf5b7f5b558892df6cc31a788f271c0cd9077611"
}

`GET /deepstate/v1/migration`

DEEP/STATE-to-2DEEP trade-in progress since DGP-3 executed: redeemed totals and counts for each legacy token, the STATE-to-2DEEP ratio, and what's left outstanding. Backed by prod.robinhood.deepstate_events, the same indexed event stream GET /v1/governance/delegates and GET /v1/rewards/leaderboard read.

Parameter	In	Description
`from`	query	Inclusive lower bound, RFC 3339 or unix seconds. Defaults to the DGP-3 execution timestamp; there's no trade-in activity before it
`to`	query	Exclusive upper bound, RFC 3339 or unix seconds. Defaults to now

from/to bound the whole response, not just daily: the totals, the redemption counts, and the daily series are all computed over that same window.

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

{
  "ratio": "3015535497731148791",
  "executed_at_block": 69224687,
  "executed_at": "2026-09-22T00:23:44Z",
  "deep_redeemed_raw": "18468042479697253554365749",
  "deep_redemptions": 22,
  "state_redeemed_raw": "33505118097276757585354227",
  "state_redemptions": 20,
  "twodeep_minted_for_state_raw": "101035872978012388120835794",
  "remaining_deep_redeemable_raw": "21418845694578502484605587",
  "remaining_state_redeemable_raw": "12411078128618112968815144",
  "from": "2026-09-22T00:23:44Z",
  "truncated": false,
  "daily": [
    {
      "day": "2026-09-22",
      "deep_redeemed_raw": "18137409339286248572655232",
      "state_redeemed_raw": "32081526580564103543727113"
    },
    {
      "day": "2026-09-23",
      "deep_redeemed_raw": "330633140411004981710517",
      "state_redeemed_raw": "1423591516712654041627114"
    }
  ]
}

The counts above are a live capture while the events index is still being backfilled after DGP-3, so they read lower than the chain's actual redemption count at the same moment; treat them as illustrative of shape, not as a final tally. That gap is inherent to reading from an indexed event stream rather than the chain itself: totals can lag or undercount while a backfill is in progress, independent of the truncated flag below.

remaining_deep_redeemable_raw / remaining_state_redeemable_raw are what's left to trade in: old DEEP stranded, unreachable, in the previous reward contract is excluded from the remaining figure since it was never going to be redeemed. These two fields are always computed from all-time totals, even when from/to narrow the rest of the response to a shorter window.

truncated is true when the window held more redemption events than one read caps at; when it is, every total and count in the response (not just daily) is a floor rather than an exact figure. A 501 response means the underlying event stream hasn't shipped yet (not_ready: "prod.robinhood.deepstate_events").

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 maker rewards earned (token varies by market; see `1s_ds_markets`)
`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​

DGP-3 migration (2026-09-22)​

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​

GET /deepstate/v1/token/2deep​

GET /deepstate/v1/migration​

Errors​

MCP tools​

Next​