> ## 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. # Every listed pair and its live state > What is tradeable, and the limits that apply to it. Use it to build a market list, or to check leverage bounds and remaining capacity before sending an order. **`id` is the `pairIndex`** an order intent signs — this endpoint is where you get it. Do not derive it by counting rows in a table. Two names per pair, deliberately. `from`/`to` are the subgraph's spelling, which for nine renamed instruments is the legacy one (`SPX`, `CL`, `HG`); `symbol` is what the price and depth endpoints expect (`US500-USD`, `WTI-USD`, `XCU-USD`). Join on `symbol`. This is the on-chain view. For the bid/mid/ask a trade would price against use `GET /v1/prices`; for what a given size actually costs use `GET /v1/depth/{pair}/quote`. ### Reading a pair ```json { "from": "BTC", "to": "USD", "maxLeverage": 100, "minLeverage": 1, "lastTradePrice": 78502.04, "longOIInUnits": 0.783, "maxOIInUsd": 6000000, "totalOpenTrades": "182" } ``` **Open interest and its cap are on different scales.** `longOIInUnits` and `shortOIInUnits` are quantities of the base asset; `maxOIInUsd` is a USD ceiling. To compare them, multiply the unit figures by `lastTradePrice` first — here 0.783 BTC is about $61k against a $6M cap. `maxLeverage` is the limit that actually applies to this pair: most pairs inherit their group's, and the few that are capped lower override it. `minLeverage` comes from the group. `from`/`to` are the subgraph's spelling, which for renamed assets is the legacy one — `SPX`, where every other endpoint says `US500`. Rate limit: 60 requests per 10 seconds per IP. This budget is **shared across `/v1/pairs`, `/v1/trades`, `/v1/limits` and `GET /v1/orders`**, not counted per path. Read `x-ratelimit-*` for the live budget rather than assuming this figure. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/pairs 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/pairs: get: tags: - Markets summary: Every listed pair and its live state description: >- What is tradeable, and the limits that apply to it. Use it to build a market list, or to check leverage bounds and remaining capacity before sending an order. **`id` is the `pairIndex`** an order intent signs — this endpoint is where you get it. Do not derive it by counting rows in a table. Two names per pair, deliberately. `from`/`to` are the subgraph's spelling, which for nine renamed instruments is the legacy one (`SPX`, `CL`, `HG`); `symbol` is what the price and depth endpoints expect (`US500-USD`, `WTI-USD`, `XCU-USD`). Join on `symbol`. This is the on-chain view. For the bid/mid/ask a trade would price against use `GET /v1/prices`; for what a given size actually costs use `GET /v1/depth/{pair}/quote`. ### Reading a pair ```json { "from": "BTC", "to": "USD", "maxLeverage": 100, "minLeverage": 1, "lastTradePrice": 78502.04, "longOIInUnits": 0.783, "maxOIInUsd": 6000000, "totalOpenTrades": "182" } ``` **Open interest and its cap are on different scales.** `longOIInUnits` and `shortOIInUnits` are quantities of the base asset; `maxOIInUsd` is a USD ceiling. To compare them, multiply the unit figures by `lastTradePrice` first — here 0.783 BTC is about $61k against a $6M cap. `maxLeverage` is the limit that actually applies to this pair: most pairs inherit their group's, and the few that are capped lower override it. `minLeverage` comes from the group. `from`/`to` are the subgraph's spelling, which for renamed assets is the legacy one — `SPX`, where every other endpoint says `US500`. Rate limit: 60 requests per 10 seconds per IP. This budget is **shared across `/v1/pairs`, `/v1/trades`, `/v1/limits` and `GET /v1/orders`**, not counted per path. Read `x-ratelimit-*` for the live budget rather than assuming this figure. parameters: - schema: type: string enum: - '42161' - '421614' default: '42161' description: >- Chain to read from: 42161 (Arbitrum One) or 421614 (Arbitrum Sepolia) required: false description: >- Chain to read from: 42161 (Arbitrum One) or 421614 (Arbitrum Sepolia) name: chainId in: query - schema: type: integer minimum: 1 maximum: 1000 default: 100 description: Maximum rows to return (1-1000) required: false description: Maximum rows to return (1-1000) name: first in: query - schema: type: - integer - 'null' minimum: 0 maximum: 5000 default: 0 description: Rows to skip, for paging (0-5000; use `since` to page deeper) required: false description: Rows to skip, for paging (0-5000; use `since` to page deeper) name: skip in: query responses: '200': description: Listed pairs 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: chainId: type: integer first: type: integer skip: type: integer count: type: integer pairs: type: array items: $ref: '#/components/schemas/ListedPair' required: - chainId - first - skip - count - pairs example: chainId: 42161 first: 100 skip: 0 count: 1 pairs: - id: '0' from: BTC to: USD symbol: BTC-USD feed: >- 0x7404e3d104ea7841c3d9e6fd20adfe99b4ad586bc08d8f3bd3afef894cf184de group: id: '0' name: crypto maxLeverage: 100 minLeverage: 1 lastTradePrice: 78502.04 longOIInUnits: 0.783 shortOIInUnits: 1 maxOIInUsd: 6000000 volumeInUsd: 8470145463 totalOpenTrades: '182' totalOpenLimitOrders: '7' usageFeeP: '0' utilizationThresholdP: '0' curRollover: '0' lastFundingRate: '379925661' lastFundingTime: '1788165893' lastRolloverTime: '1788170405' '400': description: >- Validation failed — an invalid parameter value: unsupported chainId, out-of-range paging, or a malformed trader address on the endpoints that take one 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' example: error: Bad Request message: Validation failed issues: [] '429': description: Rate limit exceeded 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. retry-after: schema: type: string description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Too Many Requests message: Rate limit exceeded. Try again in 7s. '502': description: >- The Ostium subgraph was unreachable, timed out, or rejected the query 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' example: error: Bad Gateway message: Failed to reach the Ostium subgraph. components: schemas: ListedPair: type: object properties: id: type: string description: The `pairIndex` to sign into an order intent example: '0' from: type: string description: Base asset, in the subgraph's spelling example: BTC to: type: string description: Quote asset example: USD symbol: type: string description: The pair as the price and depth endpoints name it example: BTC-USD feed: type: string description: Oracle feed id group: type: object properties: id: type: string name: type: string required: - id - name description: Asset class, e.g. crypto, forex, indices maxLeverage: type: - number - 'null' description: Highest leverage this pair allows, override resolved example: 100 minLeverage: type: - number - 'null' description: Lowest leverage this pair allows example: 1 lastTradePrice: type: - number - 'null' description: Price of the last trade on this pair example: 78502.04 longOIInUnits: type: - number - 'null' description: Open long interest, in units of the base asset example: 0.783 shortOIInUnits: type: - number - 'null' description: Open short interest, in units of the base asset example: 1 maxOIInUsd: type: - number - 'null' description: Open-interest ceiling, in USD — not units example: 6000000 volumeInUsd: type: - number - 'null' description: Cumulative traded volume, in USD example: 8470145463 totalOpenTrades: type: string description: Positions currently open on this pair example: '182' totalOpenLimitOrders: type: string description: Resting orders on this pair example: '7' usageFeeP: type: string description: Raw subgraph value — precision undocumented example: '0' utilizationThresholdP: type: string description: Raw subgraph value — precision undocumented example: '0' curRollover: type: string description: Raw subgraph value — precision undocumented example: '0' lastFundingRate: type: string description: Raw subgraph value — precision undocumented lastFundingTime: type: string description: Unix seconds lastRolloverTime: type: string description: Unix seconds required: - id - from - to - symbol - feed - group - maxLeverage - minLeverage - lastTradePrice - longOIInUnits - shortOIInUnits - maxOIInUsd - volumeInUsd - totalOpenTrades - totalOpenLimitOrders - usageFeeP - utilizationThresholdP - curRollover - lastFundingRate - lastFundingTime - lastRolloverTime 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 ````