DOCUMENTATIONv2

GET

Decentralized Trading

Get all dex orders

/api/v2/orders

AUTHENTICATIONBearer token · trading:readAUTHORITATIVE OWNERmatching-and-trading-read-model · matching-engineCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

List the authenticated owner's orders within one authoritative venue, with optional market and lifecycle filters plus opaque cursor pagination for monitoring and reconciliation.

WHEN THIS CALL IS USEFUL

Call this to monitor or reconcile the authenticated owner's order lifecycle by venue, market, and open or closed state, advancing only with the opaque cursor returned by the preceding page.

OUTCOME · Discover

What changes

Read-only projection; it grants no mutation, settlement, traffic, or authority change.

WHY IT MATTERS

Gives people and agents a contract-backed way to discover all dex orders.
Separates decision-support and reconciliation data from the controls that admit, match, publish, or settle an order.

ISOLATION + AUTHORITY

The authenticated owner, market, order, position, matching, risk, publisher, and settlement boundaries remain distinct. Documentation, contract visibility, and read access grant no execution authority; possession of a write scope still cannot bypass market status, risk, admission, allowlist, suspension, matching, publisher, or settlement gates. Current trading, matching, prediction, ingress, publisher, allowlist, suspension, market-status, and traffic controls remain frozen unless separately approved through their controlling process.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Resolve the current market status, owner-specific restrictions, risk posture, and applicable trading freeze before relying on this result.

WHAT TO DO NEXT

Follow a returned order's canonical identifier to its detail contract and reconcile status, quantities, prices, fills, and timestamps within the same venue.
Correlate fills, trades, positions, balances, and settlement through their authoritative contracts; an order state alone does not prove those later stages.

AGENT GUIDANCE

Use all dex orders only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Use the live OpenAPI schema as the authority for the exact request shape and response model.
Distinguish market data, owner-specific restrictions, order admission, matching, fills, positions, collateral, cancellation, settlement, and finality; no one state implies another.
Use response links and canonical identifiers instead of constructing internal service URLs or scraping the website.
Keep owner scope, venue, market filter, lifecycle filter, and cursor together; do not merge pages or venues into an inferred authoritative order state.

MARKET-SCOPED AVAILABILITY

Production OpenAPI presence proves that the public route is deployed; it does not unsuspend a market, admit order traffic, or select a matching engine. Catalog and read access can remain available while order entry is disabled. Matching authority, collateral reservation, settlement, and market lifecycle are independently fail-closed behind this stable contract.

MACHINE CONTRACT

The exact deployed parameters, schemas, responses, security requirements, and Hybrid-Chain agent metadata are authoritative at this operation's production OpenAPI JSON Pointer. The readable tables below add integration guidance; the deployed OpenAPI controls if guidance and the machine contract ever differ.

Open the authoritative production contract ↗

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the trading:read scope.EXAMPLEBearer hc_live_…

venuequeryOptional

dex | securities | virtualAuthoritative venue catalog. Defaults to dex.EXAMPLEdex

market_idqueryOptional

canonical market identifierOptional exact market filter.EXAMPLEBTC-USD-PERP

statequeryOptional

open | closed | allLifecycle group; defaults to open.EXAMPLEopen

limitqueryOptional

integer · 1–200Maximum owner-scoped orders; defaults to 50.EXAMPLE50

cursorqueryOptional

opaque order cursornext_cursor from the preceding page.

RESPONSES

Status and payload examples

200Owner- and venue-scoped order page.Read completed · JSON RESPONSE+

{
  "items": [
    {
      "order_id": "order-1234",
      "venue": "securities",
      "market_id": "BTC-USD-PERP",
      "side": "BUY",
      "order_type": "LIMIT",
      "status": "PARTIAL",
      "quantity": "2",
      "remaining_quantity": "1.25",
      "filled_quantity": "0.75",
      "limit_price": "42000.1",
      "trigger_price": null,
      "leverage": "3",
      "time_in_force": "GTC",
      "client_reference": "client-7",
      "created_at": "2026-08-14T00:00:00Z",
      "updated_at": "2026-08-14T00:01:00Z",
      "cancelled_at": null,
      "cancel_reason": null,
      "fills": []
    }
  ],
  "venue": "securities",
  "state": "open",
  "limit": 50,
  "next_cursor": null
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then follow a returned order's canonical identifier to its detail contract and reconcile status, quantities, prices, fills, and timestamps within the same venue.
RETRY SAFETY: For another page, send the returned opaque cursor unchanged with the same filters. Restart without a cursor when a new snapshot is required.
STATE RECONCILIATION: Use returned identifiers and versions as the comparison point for later reads. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.

401Authorization: Bearer is required, or the supplied credential is invalid.Authentication required · JSON RESPONSE+

{
  "code": "missing_credentials",
  "message": "Authorization: Bearer is required, or the supplied credential is invalid."
}

INTEGRATION DECISIONmissing_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. Do not replay an expired signature.
STATE RECONCILIATION: Authentication failed before an authoritative read was returned for market-scoped catalog, order, trade, position, collateral, and settlement projections while Python remains authoritative.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

403The credential lacks trading:read authority.Authority or policy denied · JSON RESPONSE+

{
  "code": "insufficient_scope",
  "message": "The credential lacks trading:read authority."
}

INTEGRATION DECISIONinsufficient_scope

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for market-scoped catalog, order, trade, position, collateral, and settlement projections while Python remains authoritative.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

404The requested canonical market does not exist on the selected venue.Resource not visible · JSON RESPONSE+

{
  "code": "market_not_found",
  "message": "The requested canonical market does not exist on the selected venue."
}

INTEGRATION DECISIONmarket_not_found

CALLER ACTION: Verify the canonical identifier and authenticated owner boundary. A 404 may intentionally conceal a resource outside the caller's authority.
RETRY SAFETY: Do not retry the unchanged identifier repeatedly. Refresh the relevant collection or lookup before choosing another identifier.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

422The path identifier or venue value is not canonical.Request must change · JSON RESPONSE+

{
  "code": "invalid_market_id",
  "message": "The path identifier or venue value is not canonical."
}

INTEGRATION DECISIONinvalid_market_id

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. A corrected read may be sent as a new attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

503The authoritative venue catalog is unavailable or has not been configured.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "market_data_unavailable",
  "message": "The authoritative venue catalog is unavailable or has not been configured."
}

INTEGRATION DECISIONmarket_data_unavailable

CALLER ACTION: Treat the failure as transient and preserve the last known good representation without presenting it as fresh.
RETRY SAFETY: Retry with bounded exponential backoff and jitter; stop after the integration's failure budget is exhausted.
STATE RECONCILIATION: Re-read market status, owner-scoped order or position state, Core collateral reservation, and settlement receipt; never treat shadow NXG evidence as authority.
ESCALATE WHEN: Escalate any ambiguous order or settlement outcome while preserving suspension and Python authority; never enable ingress, publishing, allowlists, markets, or traffic as recovery.

OPERATIONAL NOTES

Security and lifecycle guarantees

The gateway derives the workspace vault from the authenticated principal. Clients cannot select or enumerate an arbitrary vault.
open includes NEW, OPEN, and PARTIAL. closed includes all terminal states; all provides the bounded V1 order-history business case.
List items omit fills to avoid oversized N+1 payloads; use the exact order endpoint for execution evidence.
Internal engine identifiers, counterparty data, margin blocks, and raw matching objects are excluded. Responses use Cache-Control: no-store.

UPGRADING FROM V1

Legacy calls replaced by this operation

If you maintain an older integration, use this map to find the V2 replacement. Do not translate the old request field-for-field: rebuild it from the V2 parameters and schemas above because identity, authorization, replay protection, and response semantics may have changed.

GET/api/v1/dex/ordersDEX: Get all DEX Orders

GET/api/v1/exchange/ordersMTF: Get all MTF Orders

GET/api/v1/virtex/ordersVIRTUAL: Get all Virtual Orders

DOCUMENTATION STATUS

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-09-11T06:35:11.572Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation ↗Return to the V2 directory ↗