> ## Documentation Index > Fetch the complete documentation index at: https://docs.ostium.com/llms.txt > Use this file to discover all available pages before exploring further. # Price for a given trade size > Ostium has no central-limit order book. The price a trade actually gets comes from the **dynamic price-impact model**: quotes widen as net directional volume pushes past a per-pair threshold, and that volume decays over time. This prices a given size against the live model — the same one behind the trading UI's depth chart — so you can show a fill price before submitting. `sizeUsd` is **USD notional**, not collateral and not a quantity of the asset. There is no `direction` input: the model reads buy volume for a long and sell volume for a short, so the two sides can diverge after a large one-sided trade, and `availableNotionalUsd` differs between them at all times. Both are always returned. Either pair spelling is accepted (`US500-USD` or the legacy `SPX-USD`); the response always echoes the public one. A plain GET: read-only, idempotent, and safe to cache for a second or two. **A price is returned even when the size cannot fill.** The impact curve stays defined beyond the open-interest cap, so compare `sizeUsd` against that side's `availableNotionalUsd` before presenting a quote as executable. When a pair has no dynamic impact configured, or the size stays under the pair's volume threshold, `price` is exactly the top of book — the spread is the only cost. Rate limit: 100 requests per 10 seconds per IP. Read `x-ratelimit-*` for the live budget rather than assuming this figure. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/depth/{pair}/quote openapi: 3.1.0 info: title: Ostium Builder API version: 1.0.0 description: > REST API for the Ostium Builder SDK and integrating partners: live prices, depth, OHLC, and market hours. ## Authentication **None required today.** ## Quick start 1. **Snapshot** — `GET /v1/prices` (or `GET /v1/prices/{pair}`) for an initial board. 2. **Stream** — connect to `WS /v1/prices/stream` for live ticks — see the **Price Stream** section. 3. **Candles** — `POST /v1/ohlc` for historical OHLC. 4. **Sessions** — `GET /v1/market-hours` for calendars (cache it; use tick flags for “open right now”). The pair list is under **Markets**. 5. **Depth** — `GET /v1/depth/{pair}/quote` for the price a given size actually gets. 6. **Status** — `GET /v1/status` to check the price feed is live before relying on quotes. Typed clients: use `@ostium/builder-sdk`, or generate one from this document with any OpenAPI 3.1 client generator. ## Rate limits Applied per IP. Most limits are per route; where a group of endpoints shares one budget the endpoint's own description says so. Every rate-limited response carries `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset`; 429s add `retry-after`. **Read the headers** — do not hard-code the documented figures. ## Errors Two envelopes: - **Framework** — `{ "error": "", "message": "..." }` (optional `issues` / `details`). - **Upstream proxy** — `{ "error": "" }` from OHLC failures. `error` means different things across the two shapes — do not switch on it alone until a future major version unifies them. Every response carries `x-request-id`. Quote it when reporting a problem. ## Hosts - Production: `https://builder.prod.bedrock.ostium.io` servers: - url: https://builder.prod.bedrock.ostium.io description: Production security: [] tags: - name: Prices description: Live prices and historical candles - name: Price Stream description: >- Live prices over a WebSocket. This section is the contract — everything below is what the server actually sends. ### Connecting ``` wss://builder.prod.bedrock.ostium.io/v1/prices/stream?pairs=BTC-USD,ETH-USD ``` `?pairs=` is optional; omit it to receive every asset. No authentication, though the handshake is capped — see **Limits**. Browser clients are subject to an origin allowlist; a rejected upgrade is closed with a bare `403`. ### Server messages One snapshot on connect, carrying the `seq` baseline for every asset: ```json { "type": "snapshot", "seq": { "BTC-USD": 41 }, "data": [{ "pair": "BTC-USD", "bid": 1, "mid": 1, "ask": 1 }] } ``` Then one frame per tick: ```json { "type": "tick", "seq": 42, "data": { "pair": "BTC-USD", "bid": 1, "mid": 1, "ask": 1 } } ``` `data` is byte-identical to a row from `GET /v1/prices` — `seq` sits on the frame, not inside it, so the tick payload stays the same shape as REST. | `type` | Sent when | | --- | --- | | `snapshot` | Once, on connect | | `tick` | A price updates | | `gap` | Ticks were dropped for you — precedes the next frame you receive | | `ack` | Your `subscribe`/`unsubscribe` was applied | | `error` | Your message was rejected; the filter is unchanged | ### Client messages ```json { "type": "subscribe", "pairs": ["EUR-USD"] } { "type": "unsubscribe", "pairs": ["EUR-USD"] } ``` Every message gets exactly one reply — an `ack` carrying `pairCount` (the number of assets you now receive; `null` is all of them, `0` is none), or an `error` carrying a `code` of `malformed`, `unknown_type`, `invalid_pairs`, `no_filter` or `rate_limited`. ```json { "type": "ack", "for": "subscribe", "pairCount": 2 } { "type": "error", "code": "no_filter", "message": "..." } ``` Filters only widen. `subscribe` on an unfiltered connection is a no-op acked with `"pairCount": null` — to narrow, reconnect with `?pairs=`. `unsubscribe` needs a filtered connection and is rejected with `no_filter` otherwise. Unsubscribing your last asset leaves you receiving nothing (`"pairCount": 0`), which `subscribe` recovers without reconnecting. ### Detecting loss Delivery is best effort, but loss is **detectable**. If more than 1 MB is buffered for a slow client, ticks are dropped rather than queued — and you are told: ```json { "type": "gap", "dropped": 17 } ``` `seq` is a per-asset counter, so a jump between consecutive `tick` frames for one asset means you missed that many. Baseline each asset from the `snapshot`, then compare. Two limits on what `seq` can tell you. It is **per connection** — process-wide, not global, so it does not survive a reconnect and is not comparable across replicas. And there is **no replay**: the stream tells you that you fell behind, not what you missed, so recover by re-reading `GET /v1/prices`. Assets with no trading schedule are omitted entirely, from the snapshot and from ticks. A missing asset is not a signal that its market is closed. ### Limits Per pod, so the effective ceiling scales with replica count. Read the headers on a rejected upgrade rather than hard-coding these. | Limit | Default | Rejected with | | --- | --- | --- | | Connections per IP | 20 | `429` | | Connections in total | 500 | `503` | | Upgrades per IP per minute | 60 | `429` | | Client messages per socket per minute | 120 | `error`, `code: "rate_limited"` | Rejected upgrades carry `Retry-After`. ### Heartbeat The server pings every 30 seconds and terminates a connection that has not ponged since the previous ping. Browsers pong automatically; other clients need a library that does. On shutdown the server closes with `1001 going away` after draining. x-traitTag: true - name: Liquidity description: >- What a given trade size actually costs, priced against the live impact model - name: Markets description: >- What is listed and when it trades. ### Pairs Every pair on Ostium. Use `id` wherever a request takes a `pairIndex`, and the symbol wherever one takes a `pair`. Do not infer the id from a row's position — read the column. A pair marked `not yet` in **Tradeable** is listed on chain but has no open-interest ceiling, so it cannot be traded and `GET /v1/depth/{pair}` answers `503` for it (the `/quote` sub-resource still prices it, with `availableNotionalUsd: 0`). It is shown rather than hidden so the ids either side of it stay right. Note `GET /v1/pairs` returns the subgraph's own spelling in `from`/`to`, which for renamed assets is the legacy one — `SPX` where this table says `US500`. The table uses the symbol the price and depth endpoints expect. | id | Pair | Tradeable | | -- | ---- | --------- | | 0 | `BTC-USD` | yes | | 1 | `ETH-USD` | yes | | 2 | `EUR-USD` | yes | | 3 | `GBP-USD` | yes | | 4 | `USD-JPY` | yes | | 5 | `XAU-USD` | yes | | 6 | `XCU-USD` | yes | | 7 | `WTI-USD` | yes | | 8 | `XAG-USD` | yes | | 9 | `SOL-USD` | yes | | 10 | `US500-USD` | yes | | 11 | `US30-USD` | yes | | 12 | `US100-USD` | yes | | 13 | `JP225-JPY` | yes | | 14 | `UK100-GBP` | yes | | 15 | `GER40-EUR` | yes | | 16 | `USD-CAD` | yes | | 17 | `USD-MXN` | yes | | 18 | `NVDA-USD` | yes | | 19 | `GOOG-USD` | yes | | 20 | `AMZN-USD` | yes | | 21 | `META-USD` | yes | | 22 | `TSLA-USD` | yes | | 23 | `AAPL-USD` | yes | | 24 | `MSFT-USD` | yes | | 25 | `USD-CHF` | yes | | 26 | `AUD-USD` | yes | | 27 | `NZD-USD` | yes | | 28 | `XPD-USD` | yes | | 29 | `XPT-USD` | yes | | 30 | `HK50-HKD` | yes | | 31 | `COIN-USD` | yes | | 32 | `HOOD-USD` | yes | | 33 | `MSTR-USD` | yes | | 34 | `CRCL-USD` | yes | | 35 | `BMNR-USD` | yes | | 36 | `SBET-USD` | yes | | 37 | `GLXY-USD` | yes | | 38 | `BNB-USD` | yes | | 39 | `XRP-USD` | yes | | 40 | `TRX-USD` | yes | | 41 | `HYPE-USD` | yes | | 42 | `LINK-USD` | yes | | 43 | `ADA-USD` | yes | | 44 | `PLTR-USD` | yes | | 45 | `AMD-USD` | yes | | 46 | `NFLX-USD` | yes | | 47 | `ORCL-USD` | yes | | 48 | `RIVN-USD` | yes | | 49 | `COST-USD` | yes | | 50 | `XOM-USD` | yes | | 51 | `CVX-USD` | yes | | 52 | `URA-USD` | yes | | 53 | `USD-KRW` | not yet | | 54 | `KR2550-USD` | yes | | 55 | `BRENT-USD` | yes | | 56 | `GEV-USD` | yes | | 57 | `SHEL-USD` | yes | | 58 | `UNG-USD` | yes | | 59 | `XLE-USD` | yes | | 60 | `ARM-USD` | yes | | 61 | `ASML-USD` | yes | | 62 | `AVGO-USD` | yes | | 63 | `CAT-USD` | yes | | 64 | `INTC-USD` | yes | | 65 | `SMCI-USD` | yes | | 66 | `TSM-USD` | yes | | 67 | `MU-USD` | yes | | 68 | `SNDK-USD` | yes | | 69 | `HYG-USD` | yes | | 70 | `TLT-USD` | yes | | 71 | `MP-USD` | yes | | 72 | `DRAM-USD` | yes | | 73 | `REMX-USD` | yes | | 74 | `BB-USD` | yes | | 75 | `CRWV-USD` | yes | | 76 | `DELL-USD` | yes | | 77 | `MRNA-USD` | yes | | 78 | `MRVL-USD` | yes | | 79 | `NBIS-USD` | yes | | 80 | `LLY-USD` | yes | | 81 | `SKHY-USD` | yes | | 82 | `SPCX-USD` | yes | - name: Portfolio description: A wallet's open positions, resting orders and executed history - name: Orders description: >- Partner-signed intents executed as a single transaction — the position opens or closes and fills, or the whole call reverts. Onboarding lives here too: it is the one-time step every order depends on. - name: Status description: Whether the API is answering usefully right now paths: /v1/depth/{pair}/quote: get: tags: - Liquidity summary: Price for a given trade size description: >- Ostium has no central-limit order book. The price a trade actually gets comes from the **dynamic price-impact model**: quotes widen as net directional volume pushes past a per-pair threshold, and that volume decays over time. This prices a given size against the live model — the same one behind the trading UI's depth chart — so you can show a fill price before submitting. `sizeUsd` is **USD notional**, not collateral and not a quantity of the asset. There is no `direction` input: the model reads buy volume for a long and sell volume for a short, so the two sides can diverge after a large one-sided trade, and `availableNotionalUsd` differs between them at all times. Both are always returned. Either pair spelling is accepted (`US500-USD` or the legacy `SPX-USD`); the response always echoes the public one. A plain GET: read-only, idempotent, and safe to cache for a second or two. **A price is returned even when the size cannot fill.** The impact curve stays defined beyond the open-interest cap, so compare `sizeUsd` against that side's `availableNotionalUsd` before presenting a quote as executable. When a pair has no dynamic impact configured, or the size stays under the pair's volume threshold, `price` is exactly the top of book — the spread is the only cost. Rate limit: 100 requests per 10 seconds per IP. Read `x-ratelimit-*` for the live budget rather than assuming this figure. parameters: - schema: type: string pattern: ^[A-Z0-9]+-[A-Z0-9]+$ description: Trading pair as BASE-QUOTE, e.g. BTC-USD or FTSE-GBP required: true description: Trading pair as BASE-QUOTE, e.g. BTC-USD or FTSE-GBP name: pair in: path - schema: type: number exclusiveMinimum: 0 minimum: 0.000001 maximum: 1000000000000 description: Trade size as USD notional (not asset units) required: true description: Trade size as USD notional (not asset units) name: sizeUsd in: query responses: '200': description: Quote for both sides headers: x-request-id: schema: type: string description: >- Always present, and always generated by the service — a value sent on the request is ignored. Use it to correlate a response with your own logs, and quote it when reporting a problem. x-ratelimit-limit: schema: type: string description: Requests allowed per window. x-ratelimit-remaining: schema: type: string description: Requests left in the current window. x-ratelimit-reset: schema: type: string description: Seconds until the window resets. content: application/json: schema: type: object properties: pair: type: string sizeUsd: type: number mid: type: number description: Unimpacted mid from the live feed bid: $ref: '#/components/schemas/DepthQuoteSide' ask: $ref: '#/components/schemas/DepthQuoteSide' topOfBook: $ref: '#/components/schemas/TopOfBook' priceTimestampMs: type: integer description: >- Feed timestamp of the price this quote was derived from, in milliseconds — not the time the quote was served. required: - pair - sizeUsd - mid - bid - ask - topOfBook - priceTimestampMs example: pair: ADA-USD sizeUsd: 50000 mid: 0.18299 bid: price: 0.182888 impactBps: 5.6 availableNotionalUsd: 99851 ask: price: 0.183092 impactBps: 5.6 availableNotionalUsd: 99952 topOfBook: bid: 0.18291 ask: 0.18306 priceTimestampMs: 1787198161000 '400': description: Validation failed (bad pair format, missing or non-positive sizeUsd) headers: x-request-id: schema: type: string description: >- Always present, and always generated by the service — a value sent on the request is ignored. Use it to correlate a response with your own logs, and quote it when reporting a problem. x-ratelimit-limit: schema: type: string description: Requests allowed per window. x-ratelimit-remaining: schema: type: string description: Requests left in the current window. x-ratelimit-reset: schema: type: string description: Seconds until the window resets. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The pair is not priced right now, or is not a listed market headers: x-request-id: schema: type: string description: >- Always present, and always generated by the service — a value sent on the request is ignored. Use it to correlate a response with your own logs, and quote it when reporting a problem. x-ratelimit-limit: schema: type: string description: Requests allowed per window. x-ratelimit-remaining: schema: type: string description: Requests left in the current window. x-ratelimit-reset: schema: type: string description: Seconds until the window resets. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Temporarily unable to price the pair — no usable live quote, or the market parameters behind the model are unavailable. Retry rather than fail. headers: x-request-id: schema: type: string description: >- Always present, and always generated by the service — a value sent on the request is ignored. Use it to correlate a response with your own logs, and quote it when reporting a problem. x-ratelimit-limit: schema: type: string description: Requests allowed per window. x-ratelimit-remaining: schema: type: string description: Requests left in the current window. x-ratelimit-reset: schema: type: string description: Seconds until the window resets. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: DepthQuoteSide: type: object properties: price: type: number description: >- Volume-weighted average fill price for the whole size, after impact — the quantity the trading UI labels "Avg Price". Not the marginal price at that depth. example: 0.183092 impactBps: type: number description: >- Impact in basis points (1% = 100bps). The model derives the impacted price from mid, so this is also exactly how far `price` sits from `mid`. example: 5.6 availableNotionalUsd: type: number description: >- Remaining open-interest capacity on this side, in USD notional. A taker buy opens a long, so `ask` is bounded by the long side and `bid` by the short side — the two differ, and neither is the raw cap. A `sizeUsd` past this is still priced, but no such trade could open: compare the two before treating a quote as executable. example: 99952 required: - price - impactBps - availableNotionalUsd description: >- One side of the book, named by the price a taker gets: `ask` is a taker buy — opening a long, or closing a short; `bid` is a taker sell — opening a short, or closing a long. TopOfBook: type: object properties: bid: type: number example: 0.18291 ask: type: number example: 0.18306 required: - bid - ask ErrorResponse: type: object properties: error: type: string description: HTTP status name, e.g. "Bad Request" example: Bad Request message: type: string description: Human-readable detail example: Validation failed issues: type: array items: {} description: Raw zod issue array — present on validation failures only details: description: Optional structured detail from the thrower required: - error - message ````