> 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.