Integration guide
Request IDs, retries, amounts, and pagination.
Request sequence
- Read available products with
GET /v1/catalogue. - Request a quote with
POST /v1/get_quote. - Submit its
quote_idtoPOST /v1/acceptbeforeexpires_at. - Read the result using
GET /v1/orders/{order_id}.
A new order has status pending. After review, its status becomes filled or
cancelled. These are terminal states. Quote expiry does not change an accepted
order's status.
Request identifiers
| Identifier | Source | Use |
|---|---|---|
Idempotency-Key | Client-generated UUID | Identify a POST operation and its retries |
quote_id | Quote response | Select the quote to accept |
order_id | Acceptance response | Read an order |
X-Request-ID | Client or API | Trace one HTTP request |
Use distinct operation UUIDs for quote and acceptance requests. Save each UUID
and request body before sending. Retries use the same UUID and body, including
after a timeout or process restart. Record the response and order ID when available.
A changed body with the same UUID returns 409 idempotency_conflict.
Idempotency is scoped to the account and operation. A rotated, valid key for the same account can retry an existing operation. Replay requires current read access. See idempotency and recovery.
Retry handling
| Response | Action |
|---|---|
| HTTP 200 | Save the response; use expires_at for quotes and status for orders |
| Timeout, disconnect, or non-JSON gateway error | Retry the original UUID and body with bounded backoff |
| HTTP 429 | Honor Retry-After when present; otherwise use exponential backoff with jitter |
| HTTP 503 | Retry the original UUID and body within a bounded retry budget |
| HTTP 400 / 415 | Correct the request or headers |
| HTTP 401 / 403 | Check key validity, environment, outbound IP, and permissions |
idempotency_conflict | Check the saved UUID and request body |
quote_already_accepted | Recover the order using the original acceptance UUID |
quote_expired | Request a new quote after resolving any pending acceptance |
insufficient_funds / insufficient_credit | Check available balances or credit |
If an acceptance remains unresolved after the retry budget, retain its UUID and request for support reconciliation rather than submitting a replacement operation. See the error reference for response codes.
Amounts
Quantities, prices, and amounts are decimal strings. Use a decimal library for calculations and preserve strings when serializing JSON.
buy acquires base and pays quote; sell delivers base and receives quote. The
response pay and receive fields are the complete exchange amounts at the
quoted price. Quote amounts are positive;
balance amounts can be signed. Product minimums, quantity steps, and ticks apply.
Pagination and account reads
GET /v1/catalogue: uselimit(1–200; default 50) and the returnednext_after_idas the next request'safter_id.GET /v1/orders: returns up to 50 records, newest first. Passnext_after_idasafter_iduntil it isnull.GET /v1/orders/{order_id}: returns a single order. The compatibilitytrade_idhas the same value asorder_id.GET /v1/balances: returns balances, holds, and available credit. A zero credit limit permits funded orders only.GET /v1/heartbeat: returns API and account-authority connectivity checks. Poll every 15 seconds with a bounded timeout and backoff after failures.
Production access
Complete the ten sandbox scenarios, then request a production key. Confirm approved products, outbound IPs, key expiry, and rate limits with support. Keep sandbox and production keys and operation records separate.
Support
Provide the environment, UTC request time, HTTP status, error code, operation UUID,
quote/order ID, and response X-Request-ID. Exclude bearer keys and Authorization
headers.