Business API Authentication

Every signed Business API request uses canonical headers for HMAC authentication.

Required headers

Header	Purpose
`X-API-KEY`	Your partner API key
`X-API-SIGN`	Lowercase hex HMAC-SHA256 signature
`X-API-TIMESTAMP`	Unix epoch seconds
`X-API-NONCE`	Unique nonce per request
`Idempotency-Key`	Required on all mutations

Compatibility aliases X-Signature, X-Timestamp, and X-Nonce still work but new integrations should use the canonical headers above.

How signing works

X-API-SIGN is a lowercase hex HMAC-SHA256 digest over the following payload:

Signed payload format

POST
/api/v3/quotes

1712534400
6b6f2f4b9f2f4d4b8e6d0f2d5f7c8a1b
{"amount":"0.5","direction":"from","fromCcy":"BTC","toCcy":"ETH","type":"fixed"}

The payload components are:

HTTP method
Request path only, including the /api/v3 prefix
Canonical query string (empty line if none)
Timestamp
Nonce
Canonical JSON body string

Important rules

Timestamp is Unix epoch seconds
Server tolerance window is 5 minutes
Nonce must be unique per principal and match ^[A-Za-z0-9._:-]{8,200}$
Signature must be a lowercase hex digest
Exclude the absolute origin from the signed payload; sign /api/v3/quotes, not https://mindswap.fun/api/v3/quotes
The bytes you sign must match the body you send

Use the official SDK helpers so the canonical JSON body is generated once and reused for both signing and transport.

API key permissions

Permission	Routes
`prices:read`	`GET /currencies`, `POST /quotes`, `GET /routes`
`orders:create`	`POST /routes/resolve`, `POST /orders`, `POST /onchain/routes/resolve`, `POST /onchain/executions`
`orders:read`	`GET /orders/{orderId}`, `GET /orders/{orderId}/status`, `GET /orders/{orderId}/qr`, `GET /onchain/executions/{executionPlanId}`
`orders:update`	`POST /orders/{orderId}/emergency`
`notifications:write`	`POST /orders/{orderId}/notifications/email`
`webhooks:read`	`GET /webhooks`
`webhooks:write`	`POST /callbacks/test`, webhook create, update, rotate-secret, replay

Key restrictions

Onchain execution report and status routes also require X-Onchain-Execution-Access-Token, which is returned by POST /api/v3/onchain/routes/resolve. This token scopes access to the execution plan and is separate from API-key HMAC authentication.

Business keys can also be restricted by:

IP whitelist
Allowed domains / origins
Active / revoked status

A valid signature can still fail if the key is inactive or the request origin / IP doesn't match the key policy.

Business API Overview

Endpoints