Create a TradeOrder for an allow-listed hosted Party.
POST /api/v1/orders/hosted. Create a TradeOrder for an allow-listed hosted Party.
Request
POST /api/v1/orders/hosted
Authentication is required. Supported credentials: a customer API key with trade scope in X-API-Key or a signed-in customer session token in Authorization: Bearer …. Send one credential type only; never both. API-key requests also require the Ed25519 headers described in request signing, and the key must be authorized for the selected Party.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
Idempotency-Key | header | string | Yes | min length: 8; max length: 256; pattern: ^[A-Za-z0-9._:-]+$ | — |
X-Service-Act-As | header | string | No | min length: 3; max length: 512 | Service-principal path only (local and devnet stages; refused by configuration on mainnet). With an OAuth client-credentials bearer token from the validator, names the allow-listed Party the client acts as. Missing: 400 SERVICE_ACT_AS_REQUIRED; not allow-listed: 403 SERVICE_PARTY_NOT_ALLOWED. Ignored for customer session tokens. |
X-API-Timestamp | header | string | No | pattern: ^[0-9]{13}$ | Required with X-API-Key on trade operations: Unix time in milliseconds (13 digits), at most 1 s ahead of the server and no older than the receive window. |
X-API-Recv-Window | header | string | No | pattern: ^[0-9]{1,5}$ | Optional with X-API-Key on trade operations: signature validity window in milliseconds (default 5000, maximum 60000). It is part of the signed string. |
X-API-Signature | header | string | No | pattern: ^[A-Za-z0-9_-]{86}$ | Required with X-API-Key on trade operations: Ed25519 signature, unpadded base64url (86 characters), of the canonical string (see the apiKey security scheme). |
X-Request-Id | header | string | No | min length: 8; max length: 128; pattern: ^[A-Za-z0-9._:-]+$ | Optional client correlation identifier. The server always generates a separate authoritative request ID and retains a valid supplied value only as secondary audit correlation metadata. |
Request body
A body is required.
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
quoteId | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
walletConnectionId | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | — |
Additional fields are not allowed.
Send a signed request
Use the signed POST helper with this exact API path and the body declared above. It serializes and signs the same bytes it sends. Preserve the idempotency key and payload for a retry; create a fresh timestamp and signature.
A raw unsigned API-key request will be rejected. For the distinction between a request signature and a ledger signature, read the order flow.
Responses
201
The order intent after submission.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
commandId | string | Yes | — | — |
clientRef | string | Yes | — | — |
operationId | one or more variants · Schema 1 | Yes | — | — |
partyId | string | Yes | — | — |
status | string | Yes | allowed: "pending", "open", "filled", "rejected", "cancelled", "expired" | — |
orderId | string or null | Yes | — | — |
instrumentId | string | Yes | — | — |
side | string | Yes | allowed: "buy", "sell" | — |
amount | string | Yes | — | — |
limit | string | Yes | — | — |
venue | one or more variants · Schema 2 | Yes | — | — |
reason | string or null | Yes | — | — |
expiresAt | string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | — |
createUpdateId | string or null | Yes | — | — |
closingUpdateId | string or null | Yes | — | — |
closingRecordTime | one or more variants · Schema 3 | Yes | — | — |
settled | one or more variants · Schema 4 | Yes | — | — |
error | one or more variants · Schema 5 | Yes | — | — |
Additional fields are not allowed.
400
Malformed body or missing Idempotency-Key. Also: VALIDATION_FAILED, IDEMPOTENCY_KEY_REQUIRED, AMBIGUOUS_CREDENTIALS, SERVICE_ACT_AS_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
401
Credentials are missing, malformed, expired or revoked. Codes: AUTHENTICATION_REQUIRED, INVALID_AUTHORIZATION_HEADER, INVALID_ACCESS_TOKEN, SESSION_REVOKED, API_KEY_INVALID, API_KEY_REVOKED, API_KEY_SIGNATURE_INVALID, API_KEY_TIMESTAMP_OUT_OF_WINDOW.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
403
Wallet not owned, or the Party is not hosted. Also: ACCOUNT_RESTRICTED, ANONYMOUS_ACCOUNT_NOT_ALLOWED, API_KEY_ROUTE_NOT_ALLOWED, SERVICE_PARTY_NOT_ALLOWED, SERVICE_PRINCIPAL_NOT_ALLOWED, SIGNUP_NOT_INVITED, API_KEY_IP_NOT_ALLOWED, PRODUCT_ACCOUNT_RESTRICTED, API_KEY_SCOPE_REQUIRED, API_KEY_PARTY_NOT_AUTHORIZED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
404
Unknown quote, or no live pool for the token.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
409
Quote/wallet mismatch, reused key, or rejected create. Also: IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_CONFLICT.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
413
The request body exceeds the size limit.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
428
The signed-in account must accept the current product terms first. Codes: PRODUCT_LEGAL_ACCEPTANCE_REQUIRED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
429
The caller exceeded an IP or principal request budget.
| Header | Type | Description |
|---|---|---|
Retry-After | integer | Whole seconds to wait before retrying a rate-limited request. |
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
503
The ledger or database is unavailable. Also: AUTHENTICATION_UNAVAILABLE, AUTHORIZATION_UNAVAILABLE.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
default
Machine-readable API error. The HTTP status identifies the error class.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
Nested schemas
Field links above lead to the complete nested object, array, and variant definitions below. Required fields are scoped to their containing object.
Schema 1
Response 201.operationId
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. format:
uuid; pattern:^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - Variant 2: null.
Schema 2
Response 201.venue
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. allowed:
"curve","amm" - Variant 2: null.
Schema 3
Response 201.closingRecordTime
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. format:
date-time; pattern:^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - Variant 2: null.
Schema 4
Response 201.settled
Type: one or more variants.
At least one of these variants must match:
- Variant 1: object · Schema 6.
- Variant 2: null.
Schema 5
Response 201.error
Type: one or more variants.
At least one of these variants must match:
- Variant 1: object · Schema 7.
- Variant 2: null.
Schema 6
Response 201.settled variant 1
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
venue | string | Yes | allowed: "curve", "amm" | — |
side | string | Yes | allowed: "buy", "sell" | — |
ccIn | string or null | Yes | — | — |
ccOut | string or null | Yes | — | — |
tokenIn | string or null | Yes | — | — |
tokenOut | string or null | Yes | — | — |
feeCc | string | Yes | — | — |
platformFeeCc | string | Yes | — | — |
makerFeeCc | string | Yes | — | — |
referralFeeCc | string | No | — | — |
balanceCidAfter | string | Yes | — | — |
holdingCid | string or null | Yes | — | — |
changeCid | string or null | Yes | — | — |
graduates | boolean | Yes | — | — |
partial | boolean | Yes | — | — |
requestedGrossCc | string or null | Yes | — | — |
unspentCc | string or null | Yes | — | — |
Additional fields are not allowed.
Schema 7
Response 201.error variant 1
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
code | string | Yes | — | — |
message | string | Yes | — | — |
Additional fields are not allowed.
Source contract
This page is generated from the checked-in customer OpenAPI snapshot. Download JSON, download YAML, or compare the live API reference. Snapshot provenance records the retrieval date and checksum.