Requests
- Base URL:
https://maker.signet.kaleidoswap.com, with every route under/v2. - JSON request and response bodies, with camelCase keys. LSPS1 routes use snake_case, as their specification does.
- Swap IDs are 26-character ULIDs.
Authentication
Most routes need no authentication. Three credentials exist, each for one purpose:
Send an organization key or an API key, never both: the maker rejects the request with
400 attribution_conflict. Without either, swaps are created unattributed.
Every swap creation returns a swapAuth, issued once. Store it with the swap. It authorizes the routes that decide a live swap’s outcome, so knowing the swap ID is not enough. If it is lost, recover it with a signed proof of key ownership: POST /v2/swap/{id}/auth/challenge, then POST /v2/swap/{id}/auth/recover.
Amounts
- Amounts are integers in the asset’s smallest unit: sats for BTC and L-BTC, the contract’s smallest unit for RGB assets (six decimals for USDT-RGB).
- LSPS1 amounts are decimal strings, as the LSPS1 specification requires.
- Fee percentages follow the Boltz convention:
0.5means 0.5%.
Errors
Errors use the Boltz envelope:error is a stable machine-readable code; branch on it. details is human-readable, present on 4xx responses and absent on 5xx.
Rate limits
Quote and swap-creation routes are rate limited per caller, and swap creation also has a rolling notional budget. A429 carries Retry-After. Organizations using an API key get their own budget.
Idempotency
POST /v2/swap/pay accepts an Idempotency-Key header (a random UUIDv4). Retrying with the same key and request returns the original response. Check that GET /v2/version lists pay_through_idempotency_v1 before relying on it.
Trading halts
WhenGET /v2/info reports trading as halted, the maker refuses quotes and new swaps with 503 trading_halted, publishes an empty pair catalogue, and keeps settling swaps already in flight.