API reference
Headers, permissions, responses, and errors.
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
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://api.elkcrypto.com/sandbox | Synthetic accounts, fixed USDT/USD prices, test bookings only |
| Production | https://api.elkcrypto.com, once support confirms activation | Approved 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
Originheader 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
ForwardedorX-Forwarded-Foryourself. 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
| Header | Required | Value |
|---|---|---|
Authorization | Yes | Bearer <key> |
Content-Type | POST only | application/json (also accepts application/json; charset=utf-8) |
Idempotency-Key | POST only | Client-generated canonical 36-character UUID; one per new operation |
X-Request-ID | No | Tracing 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
symbolis uppercaseBASE/QUOTE, e.g.USDT/USD.buymeans you acquire base and pay quote;sellmeans you deliver base and receive quote.quantityis base units.priceis 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. payandreceiveare 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"
}| Field | Required | Meaning |
|---|---|---|
symbol | Yes | Eligible uppercase pair; distinct base and quote |
market | No | Eligible uppercase market; omission and null are equivalent. Required if the pair is ambiguous (market_required) |
side | Yes | buy or sell, from your perspective |
quantity | Yes | Exact 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
- Generate a UUID for each new operation. Persist it and the request body before sending. Keep successful receipts durably, along with their operation UUIDs.
- Retry an operation with the same UUID and canonical body. JSON property ordering and normalized decimal spelling do not change command identity.
- 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. - 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.
- Successful results are retained without key reuse. Only successful operations create receipts. Pricing may run more than once before a single result commits.
- 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.
- 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"
}| HTTP | Code | Meaning / next step |
|---|---|---|
| 400 | invalid_request | Invalid JSON, fields, metadata or product quantity. Check exact strings/schema |
| 400 | market_required | Specify an eligible market to disambiguate the symbol |
| 401 | sandbox_key_on_production | Sandbox-prefixed key sent to production; use https://api.elkcrypto.com/sandbox/v1/... |
| 401 | unauthenticated | Missing, invalid, expired or revoked bearer key; check environment and contact support |
| 403 | permission_denied | Wrong source IP, inactive account or missing current read/product/underlying/market eligibility; also browser Origin rejection |
| 403 | action_unavailable | Missing permission for a new quote or acceptance on a readable resource |
| 404 | quote_not_found | Missing or other-account quote; no ownership information is exposed |
| 409 | idempotency_conflict | Same scoped operation UUID with different canonical request |
| 409 | quote_expired | Quote was not accepted before its exclusive expiry |
| 409 | quote_already_accepted | Quote already booked under a different acceptance UUID; recover with the original UUID |
| 409 | insufficient_funds | Funded-only account cannot cover the immutable pay amount; no new booking is created by this rejection |
| 409 | insufficient_credit | Available funds and permitted credit cannot cover the immutable pay amount; resolve capacity |
| 413 | request_too_large | Body exceeds configured bounds; keep requests minimal. Ingress may return a non-JSON 413 |
| 415 | unsupported_media_type | Missing/unsupported Content-Type or Content-Encoding |
| 429 | rate_limited | Delay and retry the original command, honoring Retry-After if present |
| 503 | pricing_unavailable | Pricing absent, unavailable or timed out; do not invent prices |
| 503 | quote_unavailable | Invalid pricing result or changed authorization/product snapshot |
| 503 | funding_source_unavailable | Desk admission capability or required USD marks unavailable; preserve the original operation for recovery |
| 503 | catalogue_unavailable | Catalogue or authorization storage unavailable; back off before reading again |
| 503 | service_unavailable | Database/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.
Sandbox certification
Test scenarios and progress tracking.
GET/v1/catalogueProducts and pricing availability
Lists products available to your account, including quantity rules and pricing availability. Requires ViewQuotes and an approved source IP. Use limit and after_id for pagination. No request body is required.