Skip to Content
ELK Developers

API reference

Headers, permissions, responses, and errors.

Download .md

Contract version: 0.1.0. The OpenAPI 3.1 specification is the machine-readable wire contract. These endpoints issue customer-specific Spot quotes and book accepted quotes.

Environments and onboarding

EnvironmentBase URLPurpose
Sandboxhttps://api.elkcrypto.com/sandboxSynthetic accounts, fixed USDT/USD prices, test bookings only
Productionhttps://api.elkcrypto.com, once support confirms activationApproved accounts and deployment-configured indicative pricing

Obtain an environment-specific API key, expiry, approved egress IPs and product limits from support. GET /v1/catalogue lists eligible products and pricing availability. It accepts optional limit (1–200, default 50) and exclusive UUID after_id; unknown or repeated query parameters reject. No body or idempotency key is required. Use next_after_id until null. Complete sandbox certification before requesting production credentials. Use a separate key for each environment.

Transport and authentication

  • Use HTTPS with certificate and hostname verification enabled. Follow any connection instructions supplied with your sandbox access details.
  • Requests with an Origin header are rejected. Send requests from your server.
  • Send Authorization: Bearer <your-api-key>. The opaque key is not a JWT and requires no signature calculation. The server derives the account and counterparty from it; never send account IDs in customer requests.
  • Your actual egress IP (including NAT) must be on the key's allowlist. Do not send Forwarded or X-Forwarded-For yourself. Ask support to approve changed IPs.
  • Keys expire and can be revoked. Support issues and rotates keys through a separate process. Keep secrets out of URLs, logs, screenshots and reports.
  • Quote and acceptance requests use POST with JSON and no query parameters. JSON fields are case-sensitive; duplicate or unknown fields are rejected. Compressed request bodies are not supported. Do not send Content-Encoding.

Headers

HeaderRequiredValue
AuthorizationYesBearer <key>
Content-TypePOST onlyapplication/json (also accepts application/json; charset=utf-8)
Idempotency-KeyPOST onlyClient-generated canonical 36-character UUID; one per new operation
X-Request-IDNoTracing UUID; server generates one if absent

Duplicate semantic headers and malformed UUID metadata are rejected. Save X-Request-ID from the response for support; it is not an idempotency key. Native API responses are JSON with Cache-Control: no-store and X-Request-ID. An ingress proxy may return HTML or an empty body on its own failures, so always check HTTP status and content type before parsing JSON.

Sandbox progress

GET https://api.elkcrypto.com/sandbox/v1/sandbox/progress returns the authenticated key's automatic certification status: checklist_version, key_id, account_id, passed_checks, missing_checks, completed, first_observed_at, completed_at, expires_at_ms and revoked_at_ms. Times are UTC timestamps (or null before an observation/completion); key expiry and revocation are epoch milliseconds.

Use the same bearer authentication and approved source IP. Send no body or query parameters; no Idempotency-Key or Content-Type is needed. No other key's progress can be requested. This endpoint is absent in production (HTTP 404). See the sandbox guide for the ten scenarios and examples.

Amounts, direction and time

  • symbol is uppercase BASE/QUOTE, e.g. USDT/USD.
  • buy means you acquire base and pay quote; sell means you deliver base and receive quote. quantity is base units. price is quote units per base.
  • All amounts are positive decimal strings, never JSON numbers. Use decimal arithmetic, not binary floating point. Maximum: 20 integer digits, 18 fractional digits and 39 characters overall. No signs, exponent notation, whitespace or integer leading zeros. Product quantity steps, minimums and ticks also apply.
  • Equivalent decimals normalize ("1000.0" equals "1000"). Response amounts have no trailing fractional zeros. Unsupported precision/range is rejected, not silently rounded.
  • pay and receive are the complete, final exchange amounts at the quoted price. Use them directly without adding charges or making deductions.
  • Timestamps are UTC ISO 8601 with exactly milliseconds, e.g. 2026-10-13T12:00:00.000Z. Expiry is exclusive; equality is expired. The server's database clock is authoritative, including time spent waiting for locks.

GET /v1/heartbeat

Check API and current account-authority reachability using the same bearer key and approved source IP. Requires an active enrolled account, ViewQuotes, and current KYC for linked desk clients. Send no body, query parameters or Content-Encoding; neither Content-Type nor Idempotency-Key is needed.

A successful response contains status: "ok", a UTC millisecond as_of timestamp, and checks: {"api":"ok","account_authority":"ok"}. Responses are not cached. Invalid/expired/revoked keys return 401; denied account/IP/read access returns 403; unavailable authority returns 503.

Poll every 15 seconds with a bounded timeout. Use backoff and jitter after failures.

GET /v1/balances

Read current balances, holds and available credit. Use your bearer key and approved source IP; send no body, account/client ID or query parameters. Neither Content-Type nor Idempotency-Key is needed. Requires an active linked API account, current desk KYC and ViewQuotes.

{
  "schema_version": 2,
  "source": "desk_journal",
  "as_of": "2026-10-30T12:00:00.000Z",
  "balances": [
    {"asset": "BTC", "balance": "0.5", "on_hold": "0.1", "available": "0.4"},
    {"asset": "USD", "balance": "20", "on_hold": "20", "available": "0"}
  ],
  "credit": {
    "currency": "USD",
    "basis": "asset_deficits_v1",
    "limit": "100",
    "outstanding": "0",
    "on_hold": "5",
    "available": "95"
  }
}

Balances are signed decimal strings. Negative amounts represent amounts owed. USD is included even when its balance is zero.

Available credit is limit − outstanding − on_hold. An unset/zero limit permits funded orders only: no borrowing, not unlimited credit. Existing negative asset positions consume credit, using fresh desk USD marks for crypto. Other positive assets are not automatically pledged as collateral. Pending orders reserve their pay-asset funds first, then credit for any shortfall; asset on_hold is the funded portion, while credit on_hold is the borrowing portion (plus any funded hold no longer backed by the current balance). Crypto credit holds are revalued with desk marks. available can be negative following market moves, ledger changes or a reduced credit limit; new orders are blocked while over limit.

Legacy schema version 1 omits hold fields and uses desk_total_owed for credit. as_of is the observation timestamp. Unavailable balance data returns 503 service_unavailable; unlinked accounts or missing read permission return 403.

POST /v1/get_quote

Request a new quote or replay the original successful result.

{
  "symbol": "USDT/USD",
  "market": "OTC-SPOT",
  "side": "buy",
  "quantity": "1000"
}
FieldRequiredMeaning
symbolYesEligible uppercase pair; distinct base and quote
marketNoEligible uppercase market; omission and null are equivalent. Required if the pair is ambiguous (market_required)
sideYesbuy or sell, from your perspective
quantityYesExact decimal string, gross base units

A fresh request needs an active enrolled account, allowed IP, ViewQuotes, SubmitRfq, market permission, and product/all-underlying eligibility. The server resolves identity, economics and expiry. Do not send your own price or expiry. Production prices depend on availability and approved client markups; they are not the sandbox's fixed prices.

HTTP 200 response — illustrative sandbox buy:

{
  "quote_id": "22222222-2222-4222-8222-222222222222",
  "symbol": "USDT/USD",
  "market": "OTC-SPOT",
  "side": "buy",
  "price": "1.001",
  "pay": {"asset": "USD", "amount": "1001"},
  "receive": {"asset": "USDT", "amount": "1000"},
  "issued_at": "2026-10-13T12:00:00.000Z",
  "expires_at": "2026-10-13T12:00:30.000Z"
}

quote_id is a server-generated UUIDv4 associated with your account. Use expires_at to check expiry. Replays return the original price and expiry.

POST /v1/accept

Accept a quote using quote_id. Use an acceptance operation UUID distinct from the quote-request UUID.

{"quote_id": "22222222-2222-4222-8222-222222222222"}

quote_id is the only allowed field. The server uses the original immutable terms; it does not accept a replacement price, amount, counterparty or expiry.

A new acceptance requires current read eligibility, AcceptTrade, and sufficient funds or credit for the pay amount. Each quote can be accepted once. Retrying the original acceptance returns the same order.

Insufficient capacity returns HTTP 409 with insufficient_funds (funded-only client) or insufficient_credit, plus a clear human-readable message. No booking is created. Missing/stale financial authority or required USD marks returns 503 funding_source_unavailable. For a timeout or uncertain response, retry the same quote_id and Idempotency-Key.

HTTP 200 response — illustrative sandbox booking:

{
  "order_id": "33333333-3333-4333-8333-333333333333",
  "trade_id": "33333333-3333-4333-8333-333333333333",
  "status": "pending",
  "updated_at": "2026-10-13T12:00:02.000Z",
  "quote": {
    "quote_id": "22222222-2222-4222-8222-222222222222",
    "symbol": "USDT/USD",
    "market": "OTC-SPOT",
    "side": "buy",
    "price": "1.001",
    "pay": {"asset": "USD", "amount": "1001"},
    "receive": {"asset": "USDT", "amount": "1000"},
    "issued_at": "2026-10-13T12:00:00.000Z",
    "expires_at": "2026-10-13T12:00:30.000Z"
  },
  "accepted_at": "2026-10-13T12:00:02.000Z"
}

The embedded quote contains the original quoted terms. accepted_at is the acceptance timestamp. Initial status is pending; after review it becomes filled or cancelled. Both are terminal. Quote expiry does not change an accepted order's status. Use current balances to check available capacity after cancellation.

GET /v1/orders and GET /v1/orders/{order_id}

Read your API order history or a single order using the same bearer key and approved source IP. Send no body; neither Content-Type nor Idempotency-Key is needed. Requires ViewQuotes and market access.

GET /v1/orders returns {"records": [...], "next_after_id": null}. Each record has the acceptance shape above. Pages contain up to 50 records, newest first. For another page, request /v1/orders?after_id=<next_after_id>. The cursor is opaque and account-scoped. Other query parameters and caller-supplied account IDs are rejected.

GET /v1/orders/{order_id} returns one record. Missing and another account's IDs both return 404 quote_not_found. order_id and the compatibility trade_id are the same identifier. accepted_at and quote terms never change; updated_at is initially the acceptance time and later the terminal reporting transition time.

Repeating the original POST /v1/accept also returns the current order status, not a frozen pending response. Its immutable booking identity and quote terms remain unchanged, and retries never create another order.

Idempotency and recovery

  1. Generate a UUID for each new operation. Persist it and the request body before sending. Keep successful receipts durably, along with their operation UUIDs.
  2. Retry an operation with the same UUID and canonical body. JSON property ordering and normalized decimal spelling do not change command identity.
  3. A repeated successful command returns its original terms, even after expiry. Acceptance additionally reports the current order status. A changed body under the same scoped UUID returns 409 idempotency_conflict.
  4. Keys are scoped by account and operation, not bearer credential. Rotation to a different valid bearer key for the same account preserves recovery scope; revoked/expired credentials cannot authenticate.
  5. Successful results are retained without key reuse. Only successful operations create receipts. Pricing may run more than once before a single result commits.
  6. A timeout, disconnect or error does not prove an earlier attempt failed. Keep retrying the original command with bounded backoff, or contact support. Never replace an uncertain acceptance with a new UUID or a new trade.
  7. Replay still requires current read eligibility. It does not require the original mutation permission (SubmitRfq / AcceptTrade). If read access is lost, stop automated trading and reconcile with support using retained IDs.

Honor Retry-After when supplied; otherwise use bounded exponential backoff with jitter. Account-specific rate limits are available from support.

Errors

Native API errors have this shape; branch on code, not the human-readable message:

{
  "code": "pricing_unavailable",
  "message": "pricing_unavailable",
  "request_id": "77777777-7777-4777-8777-777777777777"
}
HTTPCodeMeaning / next step
400invalid_requestInvalid JSON, fields, metadata or product quantity. Check exact strings/schema
400market_requiredSpecify an eligible market to disambiguate the symbol
401sandbox_key_on_productionSandbox-prefixed key sent to production; use https://api.elkcrypto.com/sandbox/v1/...
401unauthenticatedMissing, invalid, expired or revoked bearer key; check environment and contact support
403permission_deniedWrong source IP, inactive account or missing current read/product/underlying/market eligibility; also browser Origin rejection
403action_unavailableMissing permission for a new quote or acceptance on a readable resource
404quote_not_foundMissing or other-account quote; no ownership information is exposed
409idempotency_conflictSame scoped operation UUID with different canonical request
409quote_expiredQuote was not accepted before its exclusive expiry
409quote_already_acceptedQuote already booked under a different acceptance UUID; recover with the original UUID
409insufficient_fundsFunded-only account cannot cover the immutable pay amount; no new booking is created by this rejection
409insufficient_creditAvailable funds and permitted credit cannot cover the immutable pay amount; resolve capacity
413request_too_largeBody exceeds configured bounds; keep requests minimal. Ingress may return a non-JSON 413
415unsupported_media_typeMissing/unsupported Content-Type or Content-Encoding
429rate_limitedDelay and retry the original command, honoring Retry-After if present
503pricing_unavailablePricing absent, unavailable or timed out; do not invent prices
503quote_unavailableInvalid pricing result or changed authorization/product snapshot
503funding_source_unavailableDesk admission capability or required USD marks unavailable; preserve the original operation for recovery
503catalogue_unavailableCatalogue or authorization storage unavailable; back off before reading again
503service_unavailableDatabase/internal failure or request timeout; preserve original command identity

Wrong HTTP methods return 405 with Allow: POST for quote/accept routes or Allow: GET for read routes. Unknown paths return 404 (ingress may return its own body). Use the authenticated heartbeat for connectivity checks.

Wrong-environment keys

New sandbox keys start with otc_sandbox_. Production /v1/get_quote and /v1/accept reject these with HTTP 401 sandbox_key_on_production and an explanation directing you to https://api.elkcrypto.com/sandbox/v1/.... The prefix is a diagnostic marker, not authorization: never alter it. Keys are authenticated against separate databases and cannot grant cross-environment access. Legacy unmarked sandbox keys receive generic unauthenticated on production; replace them for the clearer diagnostic.

Integration checklist

  • Use a trusted HTTPS URL, secret storage and approved egress IPs.
  • Implement decimal parsing, final pay/receive amounts and expiry handling.
  • Journal operation UUIDs/body before sending; recover across process restarts.
  • Parse HTTP status/content type and retain response request IDs.
  • Reconcile unknown outcomes; never retry acceptance as a new trade.
  • Complete the sandbox scenarios and check automatic progress. Production access is a separate approval.

On this page