DOCUMENTATIONv2

POST

Decentralized Trading

Create dex order

/api/v2/orders

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

PURPOSE + BUSINESS CONTEXT

Validate and submit an owner-scoped order instruction to the selected venue under current market, risk, authorization, idempotency, and operational-admission controls.

WHEN THIS CALL IS USEFUL

Call this only when trading is separately enabled for the exact owner, venue, and market; current market, risk, collateral, restriction, and operational-freeze gates must all admit the instruction.

OUTCOME · Create or advance

What changes

If every independent trading gate admits the request, the service may create a retained order command and return accepted order state. HTTP 202 does not prove matching, a fill, position change, settlement, publication, or finality.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance dex order.
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.
Supply the required market (body), side (body), external_reference (body) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the current market status, owner-specific restrictions, risk posture, and applicable trading freeze before relying on this result.
Supply exactly one of quantity or notional_amount, satisfy every order-type-specific price or trailing field, preserve decimal strings exactly, and use a caller-stable external_reference.

WHAT TO DO NEXT

Re-read the returned order by its canonical identifier and venue, treating HTTP 202 only as command acceptance.
After timeout or ambiguity, reconcile by the same idempotency key and canonical body before retrying, then track matching, fills, positions, and settlement separately.

AGENT GUIDANCE

Use dex order only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required market (body), side (body), external_reference (body) exactly as defined by the live contract.
Distinguish market data, owner-specific restrictions, order admission, matching, fills, positions, collateral, cancellation, settlement, and finality; no one state implies another.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.
HTTP 202 means the instruction was accepted for processing only. Reconcile the order before inferring matching, fills, position effects, settlement, or finality; the current operational trading freeze remains authoritative.

CURRENT ORDER AUTHORITY

The stable V2 contract does not imply NXG authority. Legacy Python remains the authoritative order path while NXG is observational; shadow evidence cannot enable ingress, publishing, allowlists, or unsuspend a market. The source-ready successor path reserves collateral in Core before submission, retains ambiguous in-doubt holds for an idempotent retry, atomically swaps replacement reservations, and commits fill settlement with terminal release. These controls are not a production or authority claim. Promotion requires separate market-scoped authority and traffic approvals after collateral, settlement, reconciliation, rollback, and emergency re-suspension evidence passes.

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:write scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLElaunch-treasury-v1-001

venuebodyOptional

dex | securities | virtualAuthoritative venue; defaults to dex. Internal pool UUIDs cannot be supplied.

marketbodyRequired

canonical market identifierMarket to enter; combo children must use the same market.

sidebodyRequired

BUY | SELLOrder side.

order_typebodyOptional

time_in_forcebodyOptional

GTC | IOC | FOK | BOCExecution duration; defaults to GTC. FOK is all-or-none immediately; BOC is post-only.

quantitybodyOptional

positive decimal string · max 64 charactersBase-asset quantity. Exactly one of quantity or notional_amount is required.

notional_amountbodyOptional

positive decimal string · max 64 charactersQuote notional; supported by market-style order types.

limit_pricebodyOptional

positive decimal string · max 64 charactersRequired by limit-style orders.

trigger_pricebodyOptional

positive decimal string · max 64 charactersCanonical trigger for stop, trailing, and take-profit order types.

tip_quantitybodyOptional

positive decimal string · max 64 charactersRequired for ICEBERG orders.

trailing_amountbodyOptional

positive decimal string · max 64 charactersAbsolute trailing distance; mutually exclusive with trailing_percent.

trailing_percentbodyOptional

positive decimal string · max 64 charactersPercentage trailing distance; mutually exclusive with trailing_amount.

expiry_timestampbodyOptional

13-digit future Unix millisecondsExact durable deadline; seconds, ISO strings, past values, and other lengths are rejected.

reporting_identifierbodyOptional

string · max 255Sub-client or regulatory attribution; it never changes the authenticated owner.

external_referencebodyRequired

string · 1–255Caller-stable business reference.

client_referencebodyOptional

string · max 32Optional client display reference.

leveragebodyOptional

integer · 1–20Risk leverage; defaults to 1.

aggregation_metabodyOptional

objectOpaque attribution metadata; it grants no authority.

reduce_onlybodyOptional

booleanRestricts execution to reducing an existing position.

combosbodyOptional

order[] · max 16Child orders inherit parent market, venue, attribution, and derived references; nesting is forbidden.

REQUEST

JSON body example

{
  "venue": "securities",
  "market": "BTC-USD-PERP",
  "side": "BUY",
  "order_type": "LIMIT",
  "time_in_force": "BOC",
  "quantity": "0.25",
  "limit_price": "42000.10",
  "expiry_timestamp": "4102444800000",
  "external_reference": "desk-order-20260814-001",
  "reporting_identifier": "sub-client-7",
  "leverage": 2,
  "reduce_only": false
}

RESPONSES

Status and payload examples

202Core and the current authoritative matching implementation accepted the order command.Accepted for processing · JSON RESPONSE+

{
  "order_id": "order-1234",
  "market_sequence": 184222,
  "status": "accepted"
}

INTEGRATION DECISION

CALLER ACTION: Persist the returned tracking identifier or receipt, then re-read the returned order by its canonical identifier and venue, treating HTTP 202 only as command acceptance.
RETRY SAFETY: Acceptance is not completion. Do not submit a duplicate while work is pending. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Poll or re-read authoritative state until it reaches a terminal result; preserve the last receipt while status is pending. 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.

202An identical idempotent retry returns the original acceptance as a duplicate.Accepted for processing · JSON RESPONSE+

{
  "order_id": "order-1234",
  "market_sequence": 184222,
  "status": "duplicate"
}

INTEGRATION DECISION

CALLER ACTION: Persist the returned tracking identifier or receipt, then re-read the returned order by its canonical identifier and venue, treating HTTP 202 only as command acceptance.
RETRY SAFETY: Acceptance is not completion. Do not submit a duplicate while work is pending. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Poll or re-read authoritative state until it reaches a terminal result; preserve the last receipt while status is pending. 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.

400The JSON body or Idempotency-Key header is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_json",
  "message": "The JSON body or Idempotency-Key header is malformed."
}

INTEGRATION DECISIONinvalid_json

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. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
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.

401The bearer credential is missing, expired, or invalid.Authentication required · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is missing, expired, or invalid."
}

INTEGRATION DECISIONinvalid_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. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. 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.

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

{
  "code": "insufficient_scope",
  "message": "The credential lacks trading:write 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.

409Core could not reserve the conservative collateral requirement before submission; no order command was sent.State reconciliation required · JSON RESPONSE+

{
  "code": "insufficient_collateral",
  "message": "Core could not reserve the conservative collateral requirement before submission; no order command was sent."
}

INTEGRATION DECISIONinsufficient_collateral

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
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.

409The idempotency key, external reference, or authoritative order state conflicts.State reconciliation required · JSON RESPONSE+

{
  "code": "order_conflict",
  "message": "The idempotency key, external reference, or authoritative order state conflicts."
}

INTEGRATION DECISIONorder_conflict

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
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 canonical order contract or authoritative matcher rejected the order.Request must change · JSON RESPONSE+

{
  "code": "order_rejected",
  "message": "The canonical order contract or authoritative matcher rejected the order."
}

INTEGRATION DECISIONorder_rejected

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. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
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.

503Core or the current authoritative matching implementation is unavailable.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "matching_unavailable",
  "message": "Core or the current authoritative matching implementation is unavailable."
}

INTEGRATION DECISIONmatching_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions. Use bounded backoff with jitter.
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

HTTP 202 is command acceptance, not execution, collateral settlement, or trade finality. Read the order, trades, positions, and balances projections for subsequent state.
The Rust gateway authenticates the bearer, requires exact trading:write authority, validates exact non-exponential decimal strings, and signs the normalized command to Core with nonce and replay protection.
Market tick and step precision are authoritative downstream constraints. Values are never rounded into compliance; off-grid or sub-market-unit values are rejected.
FOK produces no trade and no book mutation unless the complete quantity is immediately executable. BOC expires without trading when it would cross; only a non-marketable limit may rest.
Core derives profile, workspace vault, and client identity from signed internal context. Public callers cannot provide those identifiers or a liquidity-pool UUID.
Matching authority is selected per market behind the stable V2 contract. An engine migration, catalog presence, or successful read does not itself enable order ingress or unsuspend a market.
Reuse the same Idempotency-Key and byte-equivalent canonical intent for retries; a different logical order requires a new key and external_reference.

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.

POST/api/v1/dex/create_orderDEX: Create DEX Order

POST/api/v1/exchange/create_orderMTF: Create MTF Market Order

POST/api/v1/virtex/create_orderVIRTUAL: Create Virtual Market Order

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 ↗