DOCUMENTATIONv2

POST

Markets and execution

Close position

/api/v2/positions/{market_id}/closures

AUTHENTICATIONBearer token · trading:writeAUTHORITATIVE OWNERmatching-engineCONTRACT AUTHORITYGenerated Rust OpenAPISTATUSSource ready · production listed

PURPOSE + BUSINESS CONTEXT

Submit a reduce-only market command whose side is derived from the live owner-scoped position.

WHEN THIS CALL IS USEFUL

Call this when a market-data, trading, risk, or reconciliation client needs to apply the documented position transition after re-reading the current authoritative state so it can understand market, order, trade, position, or collateral state without confusing a read model with execution authority.

OUTCOME · Create or advance

What changes

Creates or advances only the position resource described by this contract after authorization, validation, policy, and idempotency gates pass.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance position.
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_id (path), 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.

WHAT TO DO NEXT

Re-read position using the canonical identifier returned by this operation.
Reconcile an ambiguous response with the same idempotency key before attempting another mutation.
Re-read the relevant market and owner-specific state before any later order or position decision, and preserve the current trading freeze.

AGENT GUIDANCE

Use position 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_id (path), 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.

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

market_idpathRequired

uppercase hyphen-separated identifier · 3–64 charactersCanonical base, quote, and optional instrument identifier. Lowercase, underscore, repeated-hyphen, and slash aliases are rejected.EXAMPLEBTC-USD-PERP

venuebodyOptional

dex | securities | virtualVenue containing the position; defaults to dex.

quantitybodyOptional

positive decimal stringQuantity to close; omitted closes the complete live position.

reporting_identifierbodyOptional

string · max 255Optional sub-client or regulatory attribution.

external_referencebodyRequired

string · 1–255Caller-stable business reference.

REQUEST

JSON body example

{
  "venue": "securities",
  "quantity": "0.25",
  "reporting_identifier": "sub-client-7",
  "external_reference": "close-20260814-001"
}

RESPONSES

Status and payload examples

202Reduce-only closure command accepted.Accepted for processing · JSON RESPONSE+

{
  "order_id": "order-close-1234",
  "market_id": "BTC-USD-PERP",
  "status": "ACCEPTED",
  "side": "SELL",
  "quantity": "0.25",
  "reduce_only": true
}

INTEGRATION DECISION

CALLER ACTION: Persist the returned tracking identifier or receipt, then re-read position using the canonical identifier returned by this operation.
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.

404The owner-scoped order, trade, position, or market does not exist in the selected venue.Resource not visible · JSON RESPONSE+

{
  "code": "order_not_found",
  "message": "The owner-scoped order, trade, position, or market does not exist in the selected venue."
}

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

409Core could not reserve the replacement or closure requirement before submission; the existing order remains unchanged.State reconciliation required · JSON RESPONSE+

{
  "code": "insufficient_collateral",
  "message": "Core could not reserve the replacement or closure requirement before submission; the existing order remains unchanged."
}

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 or authoritative lifecycle state conflicts with the request.State reconciliation required · JSON RESPONSE+

{
  "code": "order_conflict",
  "message": "The idempotency key or authoritative lifecycle state conflicts with the request."
}

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 mutation or authoritative matching implementation rejected the request.Request must change · JSON RESPONSE+

{
  "code": "order_rejected",
  "message": "The canonical mutation or authoritative matching implementation rejected the request."
}

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

Core derives BUY or SELL from the live signed position. Clients cannot supply side, and the generated command is always reduce-only.
The request cannot close more than the live position. Omitted quantity requests a complete close.
HTTP 202 is not execution or settlement finality; reconcile the resulting order, trades, position, and balances.

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 ↗