Quickstart

Sign your first request, open your first order, verify your first webhook. Examples in bash, Python, and Node at every step.

Prerequisites

• Your three credentials from onboarding: apiKey, apiSecret, webhookSecret. Plain values are shown once; store them on receipt.
• A public HTTPS endpoint for webhooks. For local development, ngrok or cloudflared work fine.
• A shell with curl and openssl, or Python, or Node.

Step 1 — Sign your first request

POST /api/v1/price is the smallest signed call we have. The snippet quotes 0.01 BTC to USDT (Tron) and returns the rate the server will sign on a matching /v1/create.

# Sign your first request — a quote for 0.01 BTC -> USDT (Tron).
APIKEY="rWqZ...your-api-key...Rg"
APISECRET="G1JV...your-api-secret...n4"
BODY='{"type":"float","fromCcy":"btc","toCcy":"usdt_trc20","direction":"from","amount":"0.01"}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APISECRET" | sed 's/^.* //')
NONCE=$(openssl rand -hex 16)

curl -sS -X POST https://0trace.io/api/v1/price \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $APIKEY" \
  -H "X-API-SIGN: $SIGN" \
  -H "X-API-NONCE: $NONCE" \
  --data "$BODY"
# Expect 200 OK with { "code": 0, "data": { "from": ..., "to": ..., "markupBps": 0 } }

Expect HTTP 200 with { "code": 0, "data": { "from": …, "to": …, "markupBps": 0 } }. If you get code: 3 AUTH_INVALID, your signature was computed over different bytes than the body you sent. Re-read Authentication / Common mistakes.

Step 2 — Open an order

POST /api/v1/create reserves a pay-in address. Send an Idempotency-Key so retries are safe.

# Step 2 — open an order. The Idempotency-Key makes retries safe.
APIKEY="rWqZ...Rg"
APISECRET="G1JV...n4"
BODY='{"type":"float","fromCcy":"btc","toCcy":"usdt_trc20","direction":"from","amount":"0.01","toAddress":"TXyz...recipient","refundAddress":"bc1q...refund"}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APISECRET" | sed 's/^.* //')
NONCE=$(openssl rand -hex 16)
IDEMP=$(openssl rand -hex 12)

curl -sS -X POST https://0trace.io/api/v1/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $APIKEY" \
  -H "X-API-SIGN: $SIGN" \
  -H "X-API-NONCE: $NONCE" \
  -H "Idempotency-Key: $IDEMP" \
  --data "$BODY"
# Persist data.id and data.token from the response immediately.
# data.token is returned exactly once and is not recoverable.

Persist data.id and data.token from the response immediately. The token is returned once and cannot be recovered.

Step 3 — Poll order state

POST /api/v1/order returns the partner DTO. Poll once every 30–60 seconds, or rely on webhooks (Step 4).

# Step 3 — poll the order state.
APIKEY="rWqZ...Rg"
APISECRET="G1JV...n4"
ORDER_ID="<from /v1/create>"
ORDER_TOKEN="<from /v1/create>"
BODY="{\"id\":\"$ORDER_ID\",\"token\":\"$ORDER_TOKEN\"}"
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APISECRET" | sed 's/^.* //')
NONCE=$(openssl rand -hex 16)

curl -sS -X POST https://0trace.io/api/v1/order \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $APIKEY" \
  -H "X-API-SIGN: $SIGN" \
  -H "X-API-NONCE: $NONCE" \
  --data "$BODY"
# Status walks NEW -> PENDING -> EXCHANGE -> DONE.

Status walks NEW → PENDING → EXCHANGE → DONE. See Status mapping for the full vocabulary.

Step 4 — Verify your first webhook

Spin up a tiny receiver, point your partner record’s webhook URL at it (operator-mediated), and verify the inbound HMAC. Production-ready scaffolds in Node, Python, and Go: Webhook receiver scaffold.

Minimum checks every receiver must implement:

1. Read the exact request body bytes before any middleware re-serialises.
2. Recompute HMAC-SHA256(webhookSecret, rawBody) in hex.
3. Compare with X-Partner-Webhook-Sign using a constant-time function.
4. Reject events where X-Partner-Webhook-Timestamp is more than 5 minutes old or 1 minute in the future.
5. Reply 2xx within 10 seconds. Anything else triggers the retry ladder.

Step 5 — What to read next

• Authentication — full HMAC recipe, replay window, common signing mistakes.
• Errors and Errors cookbook — every numeric code with real-world remedies.
• Reference codes — multiple per-surface markup variants in one partner record.
• /v1/create — full request and response schema for the create call.
• Cabinet — self-serve dashboard, key rotation UI.