> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/historical-data/orderstatusbyoid.md). # orderStatusByOid Look up the latest status of a single order, identified by `(user, oid)` or `(user, cloid)`. Returns a single snapshot object reflecting the most recent transition for that order, or `null` if the order is not in our index. {% hint style="info" %} **Data available from \~90 days back** for orders with terminal status (`filled`, `triggered`), and from the last 3 days for orders in any other status (`open`, `canceled`, all rejection variants, etc.). Older non-terminal transitions are pruned by TTL. {% endhint %} {% hint style="info" %} Our endpoint covers every wallet uniformly back to the 90-day terminal-retention boundary, regardless of order volume. {% endhint %} ## POST Request
FieldTypeDescription
typestringMust be "orderStatusByOid"
userstringEthereum address (0x-prefixed, 42 characters)
oidintegerOrder ID (unsigned 64-bit integer). Provide exactly one of oid or cloid.
cloidstringClient order ID. Provide exactly one of oid or cloid.
{% tabs %} {% tab title="cURL" %} OID lookup: ```bash curl -X POST https://api.hydromancer.xyz/info \ -H "Authorization: Bearer $HYDROMANCER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "orderStatusByOid", "user": "0x0000000000000000000000000000000000000000", "oid": 123456789 }' ``` CLOID lookup: ```bash curl -X POST https://api.hydromancer.xyz/info \ -H "Authorization: Bearer $HYDROMANCER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "orderStatusByOid", "user": "0x0000000000000000000000000000000000000000", "cloid": "0x000000334e48424f354c36373646384d" }' ``` {% endtab %} {% tab title="Python" %} OID lookup: ```python import requests import os response = requests.post( 'https://api.hydromancer.xyz/info', json={ 'type': 'orderStatusByOid', 'user': '0x0000000000000000000000000000000000000000', 'oid': 123456789 }, headers={ 'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}', 'Content-Type': 'application/json' } ) print(response.json()) ``` CLOID lookup: ```python import requests import os response = requests.post( 'https://api.hydromancer.xyz/info', json={ 'type': 'orderStatusByOid', 'user': '0x0000000000000000000000000000000000000000', 'cloid': '0x000000334e48424f354c36373646384d' }, headers={ 'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}', 'Content-Type': 'application/json' } ) print(response.json()) ``` {% endtab %} {% tab title="Javascript" %} OID lookup: ```javascript import axios from 'axios'; try { const response = await axios.post('https://api.hydromancer.xyz/info', { type: 'orderStatusByOid', user: '0x0000000000000000000000000000000000000000', oid: 123456789 }, { headers: { 'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`, 'Content-Type': 'application/json' } }); console.log(response.data); } catch (error) { console.error('Error:', error.message); } ``` CLOID lookup: ```javascript import axios from 'axios'; try { const response = await axios.post('https://api.hydromancer.xyz/info', { type: 'orderStatusByOid', user: '0x0000000000000000000000000000000000000000', cloid: '0x000000334e48424f354c36373646384d' }, { headers: { 'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`, 'Content-Type': 'application/json' } }); console.log(response.data); } catch (error) { console.error('Error:', error.message); } ``` {% endtab %} {% endtabs %} *** ## Response Fields Returns a **single order-snapshot object**, or JSON `null` when the `(user, oid)` or `(user, cloid)` is not found in our index. The response is **not** an array (unlike most other historical-data endpoints, which return an array). | Field | Type | Description | | ------------------------ | ------- | ----------------------------------------------------------- | | `builder` | string | Builder address if order was placed via builder (optional) | | `builderFee` | int | Builder fee in basis points (optional) | | `txIndex` | int | Transaction index of the latest status transition | | `order` | object | Order details (see Order Object below) | | `status` | string | Latest order status (see status values below) | | `statusTimestamp` | int | Timestamp of the latest status transition in milliseconds | | `order.coin` | string | Asset symbol | | `order.side` | string | `"A"` (sell) or `"B"` (buy) | | `order.limitPx` | string | Limit price | | `order.sz` | string | Remaining order size (0 if fully filled) | | `order.oid` | int | Order ID | | `order.timestamp` | int | Order creation timestamp in milliseconds | | `order.triggerCondition` | string | Trigger condition if applicable | | `order.isTrigger` | boolean | Whether order is a trigger order | | `order.triggerPx` | string | Trigger price | | `order.children` | array | Child orders for take profit/stop loss orders | | `order.isPositionTpsl` | boolean | Whether order is position TP/SL | | `order.reduceOnly` | boolean | Whether order is reduce-only | | `order.orderType` | string | Order type (e.g. `"Limit"`, `"Market"`) | | `order.origSz` | string | Original order size — use `origSz - sz` for cumulative fill | | `order.tif` | string | Time in force, e.g. `"Gtc"`, `"Ioc"`, `"Alo"` (optional) | | `order.cloid` | string | Client order ID (optional) |
Response — hit (order found) ```json { "builder": "0x...", "builderFee": 100, "txIndex": 1243, "order": { "coin": "BTC", "side": "B", "limitPx": "45000.00", "sz": "0.0", "oid": 123456789, "timestamp": 1234567890123, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.00", "children": [], "isPositionTpsl": false, "reduceOnly": false, "orderType": "Limit", "origSz": "0.5", "tif": "Gtc", "cloid": "0x000000334e48424f354c36373646384d" }, "status": "filled", "statusTimestamp": 1234567890456 } ```
Response — miss (order not found) ```json null ```
Status values **Active:** * `open` — Order is resting on the orderbook * `triggered` — Stop/trigger order was triggered * `scheduledCancel` — Order is scheduled for cancellation **Filled:** * `filled` — Order completely filled **Canceled:** * `canceled` — Canceled by user * `marginCanceled` — Insufficient margin * `liquidatedCanceled` — Position was liquidated * `delistedCanceled` — Asset was delisted * `reduceOnlyCanceled` — Reduce-only order canceled (no position) * `selfTradeCanceled` — Would have resulted in self-trade * `siblingFilledCanceled` — Sibling TP/SL order filled * `vaultWithdrawalCanceled` — Vault withdrawal triggered cancellation * `openInterestCapCanceled` — Open interest cap reached **Rejected:** * `badAloPxRejected` — ALO price would cross the book * `iocCancelRejected` — IOC order couldn't fill * `reduceOnlyRejected` — Reduce-only order rejected * `oracleRejected` — Oracle price check failed * `perpMarginRejected` — Insufficient perp margin * `perpMaxPositionRejected` — Max position size exceeded * `openInterestIncreaseRejected` — Open interest increase rejected * `positionFlipAtOpenInterestCapRejected` — Position flip at OI cap rejected * `positionIncreaseAtOpenInterestCapRejected` — Position increase at OI cap rejected * `tooAggressiveAtOpenInterestCapRejected` — Too aggressive at OI cap * `minTradeNtlRejected` — Below minimum trade notional * `insufficientSpotBalanceRejected` — Insufficient spot balance
*** ## Errors | HTTP | Body | Cause | | ---- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | | 400 | `{"error":"Missing field: user"}` | `user` field absent from request | | 400 | `{"error":"Invalid Ethereum address: ..."}` | `user` is not a valid 0x-prefixed 42-char address | | 400 | ``{"error":"Missing required field: provide either `oid` (u64) or `cloid` (string)"}`` | Neither `oid` nor `cloid` was provided | | 400 | ``{"error":"Provide exactly one of `oid` or `cloid`, not both"}`` | Both `oid` and `cloid` were provided | A successful lookup that finds nothing returns HTTP 200 with body `null` — **not** a 404. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hydromancer.xyz/readme/rest-api/historical-data/orderstatusbyoid.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.