> ## 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. # Order history for a wallet > Everything that has already happened, newest first: fills of every kind and the orders that were cancelled. Pending orders are excluded — they have not happened yet. ### Narrowing the log | Want | Send | | --- | --- | | Fills only | `isCancelled=false` | | Cancellations only | `isCancelled=true` | | Both | omit `isCancelled` | | One kind of event | `orderAction=Open` | | The last 7 days | `since=` | `orderAction` is one of `Open`, `Close`, `TakeProfit`, `StopLoss`, `Liquidation`, `RemoveCollateral`, `CloseDayTrade`. Bounding by `since` rather than paging by `skip` is the better way through a long history — it is indexed on execution time. ### Reading a fill ```json { "orderAction": "Liquidation", "price": 4511.41, "collateral": 9.4, "leverage": 50, "closePercent": 100, "profitPercent": -73.93, "totalProfitPercent": -100, "amountSentToTrader": 0, "liquidationFee": 2.327023, "pair": { "id": "5", "from": "XAU", "to": "USD" } } ``` A liquidated XAU-USD position: the whole position closed, the trader got nothing back, and 2.33 USDC went to the liquidator. | Field | Means | | --- | --- | | `closePercent` | How much of the position this fill closed — `50` is half, `100` is all | | `profitPercent` | PnL on this fill, as a percentage | | `totalProfitPercent` | PnL on the position as a whole; a liquidation reads `-100` | | `amountSentToTrader` | USDC actually returned to the wallet | | `priceImpactP` | How far the fill moved from mid, as a percentage | Those four are populated on closing fills; on an `Open` they are `0`. Fee fields (`fundingFee`, `rolloverFee`, `closeFee`, `liquidationFee`, `devFee`, `vaultFee`, `oracleFee`) are USDC amounts settled by this fill. 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/orders 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/orders: get: tags: - Portfolio summary: Order history for a wallet description: >- Everything that has already happened, newest first: fills of every kind and the orders that were cancelled. Pending orders are excluded — they have not happened yet. ### Narrowing the log | Want | Send | | --- | --- | | Fills only | `isCancelled=false` | | Cancellations only | `isCancelled=true` | | Both | omit `isCancelled` | | One kind of event | `orderAction=Open` | | The last 7 days | `since=` | `orderAction` is one of `Open`, `Close`, `TakeProfit`, `StopLoss`, `Liquidation`, `RemoveCollateral`, `CloseDayTrade`. Bounding by `since` rather than paging by `skip` is the better way through a long history — it is indexed on execution time. ### Reading a fill ```json { "orderAction": "Liquidation", "price": 4511.41, "collateral": 9.4, "leverage": 50, "closePercent": 100, "profitPercent": -73.93, "totalProfitPercent": -100, "amountSentToTrader": 0, "liquidationFee": 2.327023, "pair": { "id": "5", "from": "XAU", "to": "USD" } } ``` A liquidated XAU-USD position: the whole position closed, the trader got nothing back, and 2.33 USDC went to the liquidator. | Field | Means | | --- | --- | | `closePercent` | How much of the position this fill closed — `50` is half, `100` is all | | `profitPercent` | PnL on this fill, as a percentage | | `totalProfitPercent` | PnL on the position as a whole; a liquidation reads `-100` | | `amountSentToTrader` | USDC actually returned to the wallet | | `priceImpactP` | How far the fill moved from mid, as a percentage | Those four are populated on closing fills; on an `Open` they are `0`. Fee fields (`fundingFee`, `rolloverFee`, `closeFee`, `liquidationFee`, `devFee`, `vaultFee`, `oracleFee`) are USDC amounts settled by this fill. 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 pattern: ^0x[a-fA-F0-9]{40}$ description: Trader wallet address (0x-prefixed, 40 hex characters) required: true description: Trader wallet address (0x-prefixed, 40 hex characters) name: trader in: query - 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 - schema: type: - integer - 'null' minimum: 0 default: 0 description: Only orders executed at or after this Unix timestamp in seconds required: false description: Only orders executed at or after this Unix timestamp in seconds name: since in: query - schema: type: string pattern: ^[A-Za-z]{1,32}$ description: >- Filter by action: Open, Close, TakeProfit, StopLoss, Liquidation, RemoveCollateral required: false description: >- Filter by action: Open, Close, TakeProfit, StopLoss, Liquidation, RemoveCollateral name: orderAction in: query - schema: type: string enum: - 'true' - 'false' description: Filter to cancelled orders only, or to fills only. Omit for both required: false description: Filter to cancelled orders only, or to fills only. Omit for both name: isCancelled in: query responses: '200': description: Executed and cancelled orders 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: trader: type: string chainId: type: integer since: type: integer first: type: integer skip: type: integer orderAction: type: string isCancelled: type: boolean count: type: integer orders: type: array items: $ref: '#/components/schemas/OrderFill' required: - trader - chainId - since - first - skip - count - orders example: trader: '0x98279066957a9eaf627d33983409a548cf3e2207' chainId: 421614 since: 0 first: 100 skip: 0 count: 1 orders: - id: '151106' trader: '0x98279066957a9eaf627d33983409a548cf3e2207' tradeID: '150888' orderType: Limit orderAction: Liquidation isPending: false isCancelled: false isBuy: true price: 4511.405815742312 priceAfterImpact: 4511.405815742312 priceImpactP: 0.004830506038704215 collateral: 9.4 notionalInUsd: 470 notionalInUnits: 0.10264007472684976 leverage: 50 closePercent: 100 profitPercent: -73.925212 totalProfitPercent: -100 amountSentToTrader: 0 rolloverFee: 0.124008 liquidationFee: 2.327023 builderFee: 0 executedAt: '1787933300' executedTx: >- 0x7557adb054fb04cbb71833ad344bd7f2e2937ea9ab44b53bce21c885a7af1147 pair: id: '5' from: XAU to: USD '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: OrderFill: type: object properties: id: type: string description: Subgraph row id trader: type: string description: Owning wallet, lowercase tradeID: type: string description: Trade slot this fill belongs to limitID: type: string description: Resting order it came from, 0 for a market order example: '0' isBuy: type: boolean isPending: type: boolean description: Always false on this endpoint isCancelled: type: boolean description: True for a cancellation rather than a fill isDayTrade: type: boolean orderType: type: string description: '`Market`, `Limit` or `REMOVE_COLLATERAL`' example: Market orderAction: type: string description: >- `Open`, `Close`, `TakeProfit`, `StopLoss`, `Liquidation`, `RemoveCollateral`, `CloseDayTrade` example: Open cancelReason: type: string description: Why it was cancelled; empty on a fill example: '' price: type: - number - 'null' description: Fill price example: 4511.41 priceAfterImpact: type: - number - 'null' description: Fill price once impact is applied example: 4511.41 priceImpactP: type: - number - 'null' description: How far the fill moved from mid, as a percentage example: 0.00483 collateral: type: - number - 'null' description: Margin involved, in USDC example: 9.4 notionalInUsd: type: - number - 'null' description: Size in USD example: 470 notionalInUnits: type: - number - 'null' description: Size in units of the base asset example: 0.10264 leverage: type: - number - 'null' description: Multiple of collateral example: 50 closePercent: type: - number - 'null' description: Portion of the position closed — 50 is half, 100 is all example: 100 profitPercent: type: - number - 'null' description: PnL on this fill, as a percentage example: -73.93 totalProfitPercent: type: - number - 'null' description: PnL on the position; a liquidation reads -100 example: -100 amountSentToTrader: type: - number - 'null' description: USDC returned to the wallet example: 0 fundingFee: type: - number - 'null' description: Funding settled by this fill, in USDC example: 0 rolloverFee: type: - number - 'null' description: Rollover settled by this fill, in USDC example: 0.124008 closeFee: type: - number - 'null' description: Closing fee, in USDC example: 0 liquidationFee: type: - number - 'null' description: Paid to the liquidator, in USDC example: 2.327023 devFee: type: - number - 'null' description: Protocol fee, in USDC example: 0 vaultFee: type: - number - 'null' description: Vault fee, in USDC example: 0 oracleFee: type: - number - 'null' description: Oracle fee, in USDC example: 0 builder: type: string description: Builder code builderFee: type: - number - 'null' description: Fee attributed to that builder, in USDC example: 0 initiatedAt: type: string description: When it was submitted, unix seconds initiatedTx: type: string description: Submitting transaction initiatedBlock: type: string description: Submitting block executedAt: type: string description: When it settled, unix seconds example: '1787933300' executedTx: type: string description: Settling transaction executedBlock: type: string description: Settling block pair: $ref: '#/components/schemas/PairRef' required: - id - trader - tradeID - limitID - isBuy - isPending - isCancelled - isDayTrade - orderType - orderAction - cancelReason - price - priceAfterImpact - priceImpactP - collateral - notionalInUsd - notionalInUnits - leverage - closePercent - profitPercent - totalProfitPercent - amountSentToTrader - fundingFee - rolloverFee - closeFee - liquidationFee - devFee - vaultFee - oracleFee - builder - builderFee - initiatedAt - initiatedTx - initiatedBlock - executedAt - executedTx - executedBlock - pair 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 PairRef: type: object properties: id: type: string example: '0' from: type: string example: BTC to: type: string example: USD required: - id - from - to description: >- The subgraph's own spelling, which for renamed assets is the legacy one (`SPX`, not `US500`). Every other endpoint speaks the current symbol. ````