Common Protocol

Request conventions

• Every business endpoint must include the common authentication headers (see Common request headers). Signing rules are in Request Signing.
• GET (query): business parameters go in the query string; compute Digest over an empty body.
• POST (quote, create, fee calc): business parameters go in the JSON body; compute Digest over the raw request body bytes.

GET query example:

/coin/v1/exchange/query?trade_sn=ORD-001

POST body example:

/coin/v1/exchange/quote
{
  "receive_amount": 100,
  "pay_currency": "BRL",
  "receive_currency": "USDT"
}

Response conventions

Responses use a unified HTTP envelope. Business fields live only in data.

Success example:

{
  "status": 200,
  "msg": "SUCCESS",
  "data": {}
}

Error example:

{
  "status": 401,
  "msg": "签名校验失败",
  "data": {}
}

Notes:

• On normal handling the HTTP status is usually 200; read business result from body status (see Business status codes).
• data holds business payload; on failure it is typically {}.
• Business time fields (expires_at / created_at / finished_at) use RFC3339 with timezone, e.g. 2026-06-16T16:00:10+08:00.

Common request headers

All /coin/v1/* endpoints require:

X-Merchant-Id: M1781678976331286876
X-Timestamp: 1710000000
X-Nonce: a9f3c1d47e8b9a2c
Digest: SHA-256=<Base64(SHA256(body))>
Authorization: Signature keyId="<merchant_id>",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<Base64>"

Field	Type	Required	Description
X-Merchant-Id	string	Yes	Merchant ID (must match Authorization.keyId)
X-Timestamp	int64	Yes	Unix timestamp in seconds; skew within 300 seconds
X-Nonce	string	Yes	Random string; same X-Merchant-Id + X-Nonce must not repeat within 5 minutes
Digest	string	Yes	SHA-256= + Base64(SHA256(raw body); GET / DELETE use empty bytes)
Authorization	string	Yes	Signature keyId=...,alg="ES256",headers="...",signature="..."