Skip to main content

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.5 means 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. A 429 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

When GET /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.