Authentication
Every request authenticates with a single API key. Send it as a Bearer token on every
call:
GET /api/v1/merchant/balance HTTP/1.1
Host: merchant-api.tradeon.market
Authorization: Bearer mer_live_…Or with curl:
curl --compressed https://merchant-api.tradeon.market/api/v1/merchant/balance \
-H "Authorization: Bearer mer_live_…"Getting the key
The key is issued in the merchant cabinet at merchant.tradeon.market after you complete
onboarding (invite link from the TradeOn admin team → set password → enable TOTP). Once
inside the cabinet, open Settings → API key to view or copy it.
The key is shown in full only once at issue. Store it in your secrets manager immediately. If you lose it, regenerate from the cabinet.
Properties
- The key has the prefix
mer_live_so it is identifiable in logs. - Treat it like a password — HTTPS only, never commit, never log.
- Rotation is performed in the cabinet (
Settings → Regenerate API key). The previous key is revoked immediately on rotation; switch your integration to the new key as part of the rotation flow. - Lost both the key and access to the cabinet? Contact the TradeOn admin team for a manual reset.
Failure modes
| HTTP | error.code | Meaning and action |
|---|---|---|
| 401 | MERCHANT_API_KEY_MISSING | Header missing or malformed, or key unrecognised, mistyped, or revoked. Check the header and active key before retrying. |
| 403 | MERCHANT_BLOCKED | Account blocked. Contact the TradeOn admin team. |
| 429 | MERCHANT_RATE_LIMITED | Request budget exceeded. Wait for Retry-After before retrying. |
The authentication challenge uses MERCHANT_API_KEY_MISSING for an invalid key too;
the code does not distinguish a missing key from a revoked one. This applies to REST
requests and the WebSocket upgrade request. A WebSocket connection requires a
server-side client that can send the header; query-string keys and cabinet cookies
are not accepted.
See Errors for the full list.