Sandbox certification
Test scenarios and progress tracking.
Use https://api.elkcrypto.com/sandbox with the sandbox API key provided by your
onboarding contact. All customers use this base URL; your key identifies your
account. Sandbox keys do not work at https://api.elkcrypto.com, and production
keys do not work in the sandbox. Confirm your access is activated before testing.
The sandbox records your integration's progress automatically as it handles requests. There is no results form to submit or manual checklist review. Once all scenarios are recorded, your key is marked complete and staff can issue a separate production key after the normal account approvals.
What to call
| Action | Method and URL |
|---|---|
| Request or retry a quote | POST https://api.elkcrypto.com/sandbox/v1/get_quote |
| Accept or retry acceptance | POST https://api.elkcrypto.com/sandbox/v1/accept |
| Check your progress | GET https://api.elkcrypto.com/sandbox/v1/sandbox/progress |
Every request requires Authorization: Bearer <your sandbox key>. Your outbound
IP must be approved for that key. Newly issued sandbox keys start with
otc_sandbox_. Sending one to production /v1/... returns HTTP 401
sandbox_key_on_production with instructions to use /sandbox/v1/....
Do not change or remove the key prefix. Legacy sandbox keys without this marker
still work in the sandbox, but production can only return generic
unauthenticated for them; ask for a replacement key for explicit diagnostics.
Keep HTTPS certificate and hostname verification
enabled. Never send your key in a URL, support ticket or log.
Every POST also requires Content-Type: application/json and an
Idempotency-Key containing a UUID. Use a fresh UUID for each new operation;
reuse the original UUID and body for a retry. Acceptance has its own UUID,
separate from the quote request. The progress GET needs neither a body nor an
idempotency key.
Set up the examples
These examples use curl and Python 3. Save the key in a private header file so it does not appear in shell history or the curl command line:
mkdir -m 700 sandbox-test
cd sandbox-test
umask 077
python3 - <<'PY'
import getpass, os
key = getpass.getpass('Sandbox API key: ')
if not key or any(c.isspace() for c in key):
raise SystemExit('Invalid key input')
fd = os.open('auth.headers', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, 'w') as output:
output.write('Authorization: Bearer ' + key + '\n')
PY
BASE_URL=https://api.elkcrypto.com/sandbox
new_id() { python3 -c 'import uuid; print(uuid.uuid4())'; }
post() {
curl --connect-timeout 5 --max-time 10 \
--header @auth.headers --header 'Content-Type: application/json' \
--header "Idempotency-Key: $2" --data-binary "@$3" \
--dump-header "$4.headers" --output "$4.json" \
--write-out 'HTTP %{http_code}\n' "$BASE_URL$1"
python3 -m json.tool "$4.json"
}Run the following blocks in that same shell. Keep request IDs and private receipts
when implementing retries in your own integration. Inspect HTTP status and JSON
code: an HTTP error does not necessarily make curl exit nonzero.
Request buy and sell quotes
BUY_ID=$(new_id)
printf '%s\n' '{"symbol":"USDT/USD","market":"OTC-SPOT","side":"buy","quantity":"1000"}' > buy.json
post /v1/get_quote "$BUY_ID" buy.json buy-response
# Repeat the exact request to exercise quote replay.
post /v1/get_quote "$BUY_ID" buy.json buy-replay
SELL_ID=$(new_id)
printf '%s\n' '{"symbol":"USDT/USD","market":"OTC-SPOT","side":"sell","quantity":"1000"}' > sell.json
post /v1/get_quote "$SELL_ID" sell.json sell-responseBoth return HTTP 200. Sandbox USDT/USD prices are fixed: buy 1.001, sell 0.999.
For quantity 1000, buying pays 1001 USD and receives 1000 USDT; selling pays
1000 USDT and receives 999 USD. Amounts are decimal strings.
The quantity step, minimum quantity and price tick are 0.0001.
Accept and retry
Quotes last at most 30 seconds. Run this promptly after obtaining the buy quote. If it has expired, request a fresh buy quote with a new UUID first.
python3 - <<'PY'
import json
quote = json.load(open('buy-response.json'))
with open('accept.json', 'w') as output:
json.dump({'quote_id': quote['quote_id']}, output)
PY
ACCEPT_ID=$(new_id)
post /v1/accept "$ACCEPT_ID" accept.json accepted
post /v1/accept "$ACCEPT_ID" accept.json accept-replay
# A different acceptance operation for the same quote must be rejected.
post /v1/accept "$(new_id)" accept.json duplicate-acceptanceThe first two responses are HTTP 200 with the same trade_id and quote terms.
The last is HTTP 409 quote_already_accepted. After an uncertain acceptance,
retry the original UUID and body—even after expiry—rather than requesting a
replacement trade. See recovery rules.
Exercise error responses
Use the same POST helper and authentication. Each new operation gets a fresh UUID, except for the deliberate idempotency-conflict test below.
| Check ID | Request and expected response |
|---|---|
buy_quote | POST /v1/get_quote, USDT/USD, side buy, quantity 1000: HTTP 200. |
sell_quote | POST /v1/get_quote, USDT/USD, side sell, quantity 1000: HTTP 200. |
accept_quote | POST /v1/accept with an unexpired quote's quote_id: HTTP 200. |
quote_replay | Repeat a successful quote request with its original UUID and body: HTTP 200, same receipt. |
accept_replay | Repeat successful acceptance with its original UUID and body: HTTP 200, same trade ID. |
idempotency_conflict | POST /v1/get_quote using BUY_ID again but quantity 2000: HTTP 409 idempotency_conflict. |
duplicate_acceptance | POST /v1/accept for an already accepted quote, with a new UUID: HTTP 409 quote_already_accepted. |
expired_quote | Request a fresh quote, leave it unaccepted until after expires_at, then POST /v1/accept: HTTP 409 quote_expired. |
invalid_input | POST /v1/get_quote with quantity 0: HTTP 400 invalid_request. |
unsupported_pair | POST /v1/get_quote with an unknown symbol such as FOO/BAR: HTTP 403 permission_denied. |
Use valid normal fields for each negative test except the field being tested. No extra keys, accounts or permission grants are needed. Failed authentication cannot be attributed to your key and does not count toward completion. HTTPS verification remains your responsibility; the server cannot observe your client's certificate-validation settings.
View progress and move to production
curl --connect-timeout 5 --max-time 10 --header @auth.headers \
"$BASE_URL/v1/sandbox/progress" --output progress.json
python3 -m json.tool progress.jsonThe response identifies your key_id, the sandbox-auto-v1 checklist version,
passed_checks, missing_checks, and completed. When all ten checks are
recorded, completed becomes true and completed_at contains the completion
time. Passed checks remain recorded.
Progress is tracked per key; a replacement key starts fresh. Run the scenarios through your integration. Retry availability errors with the original UUID and body.
Once complete, request production access from your onboarding contact. Use the
separate production key with https://api.elkcrypto.com. The progress endpoint
is sandbox-only.