POST /v1/order
Fetch current order state by id + token.
POST
/api/v1/orderAuth requiredFetches the current state of an order you created. Returns the same partner DTO shape as /v1/create, minus the one-time token field.
Partner-scoped, NOT_FOUND collapsed. Wrong owner, wrong id, wrong token, and soft-deleted orders all return the same { code: 6, msg: "NOT_FOUND" } envelope. The four cases are indistinguishable on the wire. token is verified against a stored hash with a constant-time compare.
Request
Body
idstring (UUID)requiredOrder id from the /v1/create response.
tokenstring (43-char base64url)requiredRaw access token returned by /v1/create. The server verifies it against a stored hash. A malformed value collapses to NOT_FOUND.
Response
200 OK
{
"code": 0,
"msg": "",
"data": {
"id": "1f8c5e0b-9c92-4d6a-b0a8-3c5f8d6e7a4b",
"type": "float",
"status": "PENDING",
"time": {
"reg": 1716800000,
"expiration": 1716801800,
"left": 1450,
"update": 1716800350,
"finish": null
},
"from": {
"code": "btc",
"network": "Bitcoin",
"amount": "0.01000000",
"address": "bc1q...payin-address",
"tx": {
"id": "abc...payin-tx-hash",
"amount": "0.01000000"
}
},
"to": {
"code": "usdt_trc20",
"network": "Tron",
"amount": "619.987654",
"address": "TXyz...recipient",
"tx": { "id": null, "amount": null }
},
"back": {
"address": "bc1q...refund",
"tx": { "id": null }
},
"emergency": { "status": [], "choice": "NONE" },
"rate": "62450.12345678",
"networkFee": "1.20",
"markupBps": 50
}
}Fields
data.statusstringPartner-facing status. See Status mapping for the full vocabulary.
data.from.tx{ id: string|null, amount: string|null }Deposit transaction. id is populated once we have observed an on-chain payin. amount reflects what was actually received.
data.to.tx{ id: string|null, amount: string|null }Payout transaction. id is populated once the payout has been broadcast (around the EXCHANGE → DONE transition on the wire).
data.back{ address: string|null, tx: { id: string|null } }Refund destination and tx. address is non-null when refundAddress was supplied at create time. tx.id appears once a refund (manual or auto) has been broadcast.
data.emergency{ status: array, choice: string }Empty array and
NONE outside of EMERGENCY. See /v1/emergency for how to resolve.data.time.leftnumber (seconds)Computed each call as max(0, expiration − now). Reaches 0 once the deposit window has closed.
data.markupBpsnumber | nullApplied afftax stored on the order at creation time. null on public (non-partner) orders.
Errors
| code | msg | HTTP | Description |
|---|---|---|---|
| 1 | INVALID_REQUEST | 400 | Body fails validation: unsupported asset, disabled pair, unparseable amount, invalid address, FLOAT without refundAddress, malformed Idempotency-Key. The same code + HTTP 409 fires on Idempotency-Key reuse with a different payload. |
| 2 | AUTH_REQUIRED | 401 | One of X-API-KEY / X-API-SIGN is missing on an endpoint that requires authentication. |
| 3 | AUTH_INVALID | 401 | Unknown key, malformed signature, signature mismatch, expired or replayed nonce, decrypt failure. Generic body — never an oracle for "which" of those it was. |
| 4 | AUTH_DISABLED | 401 | Partner record enabled = false. Reachable only with a valid signature, so the operator can distinguish a kill-switched partner from a stolen-and-revoked key. |
| 5 | RATE_LIMIT | 429 | Per-partner weight budget exhausted within the 60-second sliding window. Response includes Retry-After: <seconds>. |
| 6 | NOT_FOUND | 404 | Order does not exist OR exists but belongs to a different partner OR exists and the token is wrong. The three cases collapse to one envelope. |
| 99 | INTERNAL | 500 | Unexpected server-side condition. Already logged on our side; safe to retry. |
Code examples
# Fetch the current state of an order.
APIKEY="rWqZ...Rg"
APISECRET="G1JV...n4"
NONCE=$(openssl rand -hex 16)
BODY='{"id":"1f8c5e0b-9c92-4d6a-b0a8-3c5f8d6e7a4b","token":"v8k3-Po9...43-char-base64url"}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$APISECRET" | sed 's/^.* //')
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"Rate limit
Weight 1 per call. Counts against the default 2500 weight-unit / minute sliding-window budget per partner.
Notes
Polling. 30–60 s is comfortable at weight 1. For event-driven updates, subscribe to webhooks.
Soft-delete. A user-deleted order returns code 6 NOT_FOUND on this endpoint. Aggregate counters on your partner record never decrement; earnings stay accurate even when the order is no longer visible on the wire.
