Skip to Content
ELK Developers

Integration guide

Request IDs, retries, amounts, and pagination.

Download .md

Request sequence

  1. Read available products with GET /v1/catalogue.
  2. Request a quote with POST /v1/get_quote.
  3. Submit its quote_id to POST /v1/accept before expires_at.
  4. 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

IdentifierSourceUse
Idempotency-KeyClient-generated UUIDIdentify a POST operation and its retries
quote_idQuote responseSelect the quote to accept
order_idAcceptance responseRead an order
X-Request-IDClient or APITrace 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

ResponseAction
HTTP 200Save the response; use expires_at for quotes and status for orders
Timeout, disconnect, or non-JSON gateway errorRetry the original UUID and body with bounded backoff
HTTP 429Honor Retry-After when present; otherwise use exponential backoff with jitter
HTTP 503Retry the original UUID and body within a bounded retry budget
HTTP 400 / 415Correct the request or headers
HTTP 401 / 403Check key validity, environment, outbound IP, and permissions
idempotency_conflictCheck the saved UUID and request body
quote_already_acceptedRecover the order using the original acceptance UUID
quote_expiredRequest a new quote after resolving any pending acceptance
insufficient_funds / insufficient_creditCheck 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: use limit (1–200; default 50) and the returned next_after_id as the next request's after_id.
  • GET /v1/orders: returns up to 50 records, newest first. Pass next_after_id as after_id until it is null.
  • GET /v1/orders/{order_id}: returns a single order. The compatibility trade_id has the same value as order_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.

On this page