> ## Documentation Index
> Fetch the complete documentation index at: https://darknyx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Read the current live status and filled quantity of an order owned by the authenticated account.
# Get Order
**TL;DR**
`GET /orders/{order_id}` returns the current state of one order owned by the
authenticated API account: its status, filled quantity, and remaining size. For
live updates without polling, subscribe to the
[Orders Channel](../websocket/orders-channel.mdx) instead.
Auth: `Authorization: Bearer `.
## Path parameters
| Parameter | Type | Description |
| ---------- | ------ | --------------------------- |
| `order_id` | string | The 16-byte order id (hex). |
## Example
```bash theme={null}
curl -s "$GATEWAY/orders/$ORDER_ID" \
-H "Authorization: Bearer $TOKEN" | jq .
```
## Response
```json theme={null}
{
"order_id": "aa00000000000000000000000000000001",
"symbol": "SOL-USDC",
"side": "bid",
"order_type": "limit",
"status": "pending",
"amount": 10000000,
"filled_quantity": 0,
"price_limit": 150000000,
"expiry_slot": 309490000,
"arrival_slot": 309482113
}
```
## Field reference
| Field | Type | Description |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order_id` | string | The order id. |
| `symbol` | string | The isolated market book this order belongs to. |
| `side` | string | `"bid"` or `"ask"`. |
| `order_type` | string | `"limit"`, `"ioc"`, or `"fok"`. |
| `status` | string | Usually `pending` or `pending_settlement` for a live tracked order. Terminal lifecycle is delivered on the orders stream and may already have aged out of this read. |
| `amount` | integer | The order's original size, in base units. |
| `filled_quantity` | integer | How much has filled so far. |
| `price_limit` | integer | The worst acceptable price (quote units per base). |
| `expiry_slot` | integer | The slot the order auto-expires at. |
| `arrival_slot` | integer | The slot the engine stamped on arrival. |
## Streaming alternative
Polling `GET /orders/{order_id}` is fine for a one-off check or to reconcile after
a missed event. For a trading client that needs to react to fills, subscribe to
the [Orders Channel](../websocket/orders-channel.mdx): the engine pushes a lifecycle
event (partial fill, full fill, expiry) the moment an order's state changes,
without a request per check.
## Errors
| Condition | Status |
| ------------------------------------------------ | ------ |
| Malformed `order_id` hex | `400` |
| Missing or invalid bearer token | `401` |
| No owned order with that id is currently tracked | `404` |
An order owned by another account returns the same `404` code and body as an
unknown id. This prevents callers from probing whether another account has a
particular order.
**Terminal orders age out**
The book tracks resting and recently-terminal orders. A long-since-filled,
expired, or cancelled order may no longer be queryable here; recover fill details
from your seed plus finalized chain (see [Fills Channel](../websocket/fills-channel.mdx)).
## OpenAPI
````yaml api-reference/openapi/darknyx-public.yaml GET /orders/{order_id}
openapi: 3.1.0
info:
title: Darknyx TEE API
version: 4.1.0
description: |
Public + authenticated REST and WebSocket API for the Darknyx dark pool
TEE matching layer. One attested endpoint may expose several independently
routed spot markets. Pairs with the v2 on-chain custody program
(vault, program ID `C63vKvysCzX55PKraas4Wc22ijqjGJQdPC1mrzCFVWZx`).
contact:
name: Darknyx engineering
license:
name: PolyForm Perimeter License 1.0.1
url: https://polyformproject.org/licenses/perimeter/1.0.1
servers:
- url: https://api.darknyx.example.com
description: Mainnet placeholder; use the origin published with a deployment.
- url: https://api.devnet.darknyx.example.com
description: Devnet placeholder; use the origin published with a deployment.
security: []
tags:
- name: auth
description: OAuth2 client-credentials and bearer-token lifecycle.
- name: attestation
description: |
Darknyx engine and transport attestation plus the deployment gateway's
separate evidence bundle. Programmatic clients verify the certificate on
their actual connection with `/transport-attestation` before any
credential or sensitive write. `/evidences/*` describes surrounding
ingress infrastructure and is not a substitute for the engine check.
- name: info
description: |
Application/instance metadata, boot-session id, and settlement signers.
Verify measured identity through `/attestation`, not self-reported fields.
- name: instruments
description: Public market metadata.
- name: orders
description: Place / cancel / modify / inspect orders.
- name: system
description: Public engine liveness + server time (GTT slot conversion).
- name: account
description: Per-account open orders and preferences. Balances remain client-derived.
- name: tree
description: >-
Convenience Merkle-tree mirror; clients can verify the same state on
Solana.
- name: transparency
description: Public solvency snapshot + engine identity + aggregate stats.
- name: settlement
description: Batch settlement status (TEE → L1 tx_signature lookup).
paths:
/orders/{order_id}:
get:
tags:
- orders
summary: Current status of a live order.
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Order detail.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'401':
description: >-
Missing / invalid / expired / revoked bearer token, or a token
invalidated by the operator.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: The account is suspended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Unknown order or an order owned by another account. Both cases use
the same response so this endpoint is not an order-existence oracle.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- BearerAuth: []
components:
schemas:
Order:
type: object
description: The `GET /orders/{order_id}` status body.
required:
- order_id
- symbol
- side
- order_type
- status
- amount
- filled_quantity
- price_limit
- expiry_slot
- arrival_slot
properties:
order_id:
type: string
description: 16-byte order id, hex (the one supplied at placement).
symbol:
type: string
description: Canonical instrument symbol selecting the isolated market book.
side:
type: string
enum:
- bid
- ask
order_type:
type: string
enum:
- limit
- ioc
- fok
status:
type: string
enum:
- empty
- pending
- pending_settlement
- expired
- cancelled
description: |
`pending` (resting), `pending_settlement` (reserved while the TEE
reconciles Tx D), `expired`, `cancelled`, or `empty` (slot
reclaimed). Definitive failures leave the order lookup surface and
emit terminal `settlement_failed` on the authenticated orders
channel with a reason and lock expiry slot.
amount:
type: integer
format: uint64
description: Original order size, base units.
filled_quantity:
type: integer
format: uint64
description: Cumulative filled quantity.
price_limit:
type: integer
format: uint64
expiry_slot:
type: integer
format: uint64
arrival_slot:
type: integer
format: uint64
description: Slot stamped on arrival; frozen for the order's life.
Error:
type: object
description: |
The error envelope. Every non-2xx response renders as this shape, with
the mapped HTTP status. Success responses are NOT enveloped (their typed
body is returned directly). Every response — success and error — carries
an `x-request-id` header for correlation with server logs.
required:
- code
- message
properties:
code:
type: integer
description: |
Stable numeric error code. Ranges: 1000–1099 request validation,
1100–1199 auth, 1200–1299 conflict, 1300–1399 not found, 1400–1499
rate limit, 5000+ server. See the Error Codes reference.
One exception to the ranges: `1402` is returned with HTTP 503, not
429. It signals that credential verification is momentarily at
capacity and was refused rather than queued. Branch on the numeric
code rather than inferring the status from its range.
example: 1102
message:
type: string
example: trading_key_signature does not verify against the canonical body
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
Short-lived (≤ 1h) bearer token from POST /auth/token.
Expiry is EXACT — there is no grace period past `expires_in`, on REST
or on the streaming transport. Refresh on a margin.
A structurally valid, unexpired token is still refused when it has been
revoked (401), when the operator has invalidated the tokens the account
was holding (401), or when the account is suspended (403). Suspension
also blocks issuing a new one, so re-authenticating does not clear it.
````