SmallSwap SmallSwap

API Reference

Trocador-shaped HTTP API. Cake Wallet and any aggregator that already speaks Trocador works with a base-URL change.

Base URLs

https://smallswap.example/api/v1 clearnet
http://<onion>.onion/api/v1 tor

Every response sets Onion-Location pointing at the .onion equivalent. The two surfaces are byte-identical.

Authentication

Pass your key in the API-Key header. X-SmallSwap-API-Key is accepted as an alias.

curl https://smallswap.example/api/v1/new_rate?ticker_from=xmr&ticker_to=usdt&network_from=monero&network_to=tron&amount_from=1.0 \
  -H 'API-Key: prt_yourkeyhere'
Anonymous
No key. Reads + swap creation. No commission.
Affiliate aff_*
Self-serve from /affiliates. End-user commission.
Partner prt_*
Issued out-of-band. Higher rate limits, webhook support.

Endpoints

  • GET /api/v1/new_rate — get a quote
  • GET /api/v1/new_trade — create a swap
  • GET /api/v1/trade — get swap status
  • GET /api/v1/coin — list supported currencies
  • GET /api/v1/pairs — list supported pairs (with routing policy)
  • GET /api/v1/limits — min/max per pair
  • GET /api/v1/exchanges — Cake-compat provider list

Error model

Every non-2xx response carries a structured body:

{
  "error": {
    "code": "amount_below_min",
    "message": "Minimum amount is 0.05 xmr for this pair",
    "details": {
      "min_amount_from": "0.05",
      "your_amount_from": "0.01"
    }
  }
}
  • code is stable and machine-readable. Meaning never changes.
  • message is human-readable. Subject to copy edits.
  • details is per-code structured data, documented on each endpoint.

Idempotency

/new_trade requires an Idempotency-Key header. We store (key, body-hash, response) for 24 hours. Same key + same body → same response. Same key + different body → 409 idempotency_conflict.

Rate limits

ClassRead /minWrite /min
Anonymous606
Affiliate30030
Partner6000600

Sliding-window per minute. Exceeded → 429 with Retry-After.

Versioning

  • URL-versioned: /api/v1/.
  • Within a major version, only additive changes. New fields, new endpoints, new enum values — never removed or repurposed.
  • Breaking changes get /api/v2/. v1 supported for at least 12 months past v2 GA.
  • Every response carries X-SmallSwap-API-Version: 1 for sniffing.

Integrating