> ## 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. # Limit/stop orders for a wallet > Orders the wallet has placed that have not filled or been cancelled — its resting book. **Nothing here has executed.** These are not positions: when one fills it becomes a position in `GET /v1/trades` and a fill in `GET /v1/orders`, and leaves this list. ### Reading a resting order ```json { "limitType": "STOP", "isBuy": false, "openPrice": 1.16064, "collateral": 302.77, "leverage": 50, "pair": { "id": "2", "from": "EUR", "to": "USD" } } ``` A short on EUR-USD waiting to trigger at 1.16064, which will open with 302.77 USDC at 50x. | `limitType` | Triggers | | --- | --- | | `LIMIT` | When price reaches `openPrice` from the favourable side | | `STOP` | When price breaks through `openPrice` | `stopLossPrice` and `takeProfitPrice` are the exits that will be attached to the position once it opens, and are `0` when unset. 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/limits 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/limits: get: tags: - Portfolio summary: Limit/stop orders for a wallet description: >- Orders the wallet has placed that have not filled or been cancelled — its resting book. **Nothing here has executed.** These are not positions: when one fills it becomes a position in `GET /v1/trades` and a fill in `GET /v1/orders`, and leaves this list. ### Reading a resting order ```json { "limitType": "STOP", "isBuy": false, "openPrice": 1.16064, "collateral": 302.77, "leverage": 50, "pair": { "id": "2", "from": "EUR", "to": "USD" } } ``` A short on EUR-USD waiting to trigger at 1.16064, which will open with 302.77 USDC at 50x. | `limitType` | Triggers | | --- | --- | | `LIMIT` | When price reaches `openPrice` from the favourable side | | `STOP` | When price breaks through `openPrice` | `stopLossPrice` and `takeProfitPrice` are the exits that will be attached to the position once it opens, and are `0` when unset. 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 responses: '200': description: Resting 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 first: type: integer skip: type: integer count: type: integer limits: type: array items: $ref: '#/components/schemas/RestingOrder' required: - trader - chainId - first - skip - count - limits example: trader: '0x609dfb78434525c766f439d61c205dff48c9a264' chainId: 42161 first: 100 skip: 0 count: 1 limits: - id: 0x609dfb78434525c766f439d61c205dff48c9a264_2_0 trader: '0x609dfb78434525c766f439d61c205dff48c9a264' isActive: true isBuy: false isDayTrade: false limitType: STOP openPrice: 1.16064 stopLossPrice: 0 takeProfitPrice: 0 collateral: 302.77119 notionalInUsd: 1513.85595 notionalInUnits: 1304.3 leverage: 50 orderId: '2189730' initiatedAt: '1788164716' updatedAt: '1788164716' pair: id: '2' from: EUR 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: RestingOrder: type: object properties: id: type: string description: Subgraph row id trader: type: string description: Owning wallet, lowercase isActive: type: boolean description: Always true on this endpoint isBuy: type: boolean description: Opens long when true, short when false isDayTrade: type: boolean limitType: type: string description: '`LIMIT` or `STOP`' example: STOP openPrice: type: - number - 'null' description: Trigger price example: 1.16064 stopLossPrice: type: - number - 'null' description: Stop loss to attach once it fills, 0 when unset example: 0 takeProfitPrice: type: - number - 'null' description: Take profit to attach once it fills, 0 when unset example: 0 collateral: type: - number - 'null' description: Margin it will post, in USDC example: 302.77119 notionalInUsd: type: - number - 'null' description: Size it will open, in USD example: 1513.85595 notionalInUnits: type: - number - 'null' description: The same size in units of the base asset example: 1304.3 leverage: type: - number - 'null' description: Multiple of collateral example: 50 orderId: type: string description: On-chain order id example: '2189730' uniqueId: type: string description: Subgraph uniqueness key block: type: string description: Block it was placed in executionStarted: type: string description: Non-zero once execution is in flight example: '0' initiatedAt: type: string description: When it was placed, unix seconds example: '1788164716' updatedAt: type: string description: Last modification, unix seconds example: '1788164716' pair: $ref: '#/components/schemas/PairRef' required: - id - trader - isActive - isBuy - isDayTrade - limitType - openPrice - stopLossPrice - takeProfitPrice - collateral - notionalInUsd - notionalInUnits - leverage - orderId - uniqueId - block - executionStarted - initiatedAt - updatedAt - 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. ````