# Swaplume

> Free crypto swap aggregator API: one request asks every connected instant exchange for the same swap and returns
> every quote, best first. No API key, no account. Exchanges: ChangeNOW, SimpleSwap, FixedFloat, Alfacash, SideShift,
> InstaSwap, CoinCraddle, CCE Cash, Changelly.

Base URL: https://api.swaplume.com (the paths below are relative to it)
OpenAPI spec: /openapi.json
API reference: /docs

## How to swap

1. Quote: `GET /v1/quotes?from=btc&to=eth&amount=0.1`
   - An asset is a ticker plus a network: `usdt:trx`, or `to=usdt&to_network=trx`. Network names work too (`tron`,
     `erc20`, `bep20`). A token whose ticker another token has on the same network has an id ending with its
     contract (`lit:eth:0xb594…`): find ids with `/v1/currencies`.
   - `quotes` are sorted by `amount_to`, what the user receives after all fees; `best` is the first. `errors` lists
     the exchanges that can't, and why (with their min/max when the amount is out of range). With no quote at all,
     `limits` has the widest min/max: suggest an amount inside it.
   - Ask again after `refresh_after` seconds, not sooner.
   - `rate_type=fixed`: `amount_to` is guaranteed until the quote's `expires_at`. Pass its `rate_id`, if any, when
     creating the swap.
   - For an exact amount received, pass `amount_to` instead of `amount` (fixed rate only): each quote's `amount_from`
     is then what to send, and the least comes first.
   - `/v1/quotes/stream` takes the same parameters and sends Server-Sent Events as the exchanges answer: the last
     event, with nothing `pending`, is the full answer.
2. Check the payout address (optional: creating the swap checks it too): `POST /v1/validate-address` with
   `{"asset": "eth", "address": "<payout address>"}`. If `valid` is false, show `reason` to the user.
3. Create: `POST /v1/swaps` with an `Idempotency-Key: <new UUID>` header and
   `{"from": "btc", "to": "eth", "amount": "0.1", "address": "<payout address>", "refund_address": "<btc address>"}`
   - Pass the chosen quote's `provider` (and its `rate_id`, for a fixed rate). Without `provider`, the swap goes to
     the best exchange now, then the next best, skipping those with a `notice` or needing an `email` or
     `refund_address` the request lacks.
   - The answer has `deposit_address`, `deposit_extra_id` (a memo the deposit must include, when set),
     `deposit_uri` (a payment link with the amount, for a QR code, when the network has one) and plain-English
     `instructions`. The same key and body again return the same swap, never a second one.
4. Track: `GET /v1/swaps/{id}` every `poll_after` seconds until `is_final`. Once sent, it stays `waiting` until the
   exchange sees the deposit on-chain, often a few minutes. Statuses: waiting, confirming, exchanging, sending,
   finished, failed, refunding, refunded, expired, verifying, action_required, unknown.

## A quote's terms

- `email_required`: send the user's `email` with the swap.
- `refund_address_required`: send a `refund_address`. `refund_address_supported: false`: the exchange arranges
  refunds with the user instead.
- `notice` and `terms_url`: show the sentence and the link next to the button that creates the swap, then pass that
  quote's `provider`.
- `kyc`: how likely the exchange is to hold the swap for an ID check: `never`, `rare`, `occasional`, `often` (null:
  not rated).
- `ip_shared`: the exchange gets the user's IP when the swap is created, as it would on its own site.
- `ip_kept`: Swaplume keeps that IP and the browser's languages for a year, as the exchange requires (a week if no
  deposit arrives).

## Rules for agents

- Addresses come from the user: never make one up or change one.
- Before creating the swap, show the user what they send and receive, the exchange and the payout address, and wait
  for their yes.
- Swaplume never holds funds: the user sends the deposit to the exchange, which pays out to the user's address.

## MCP server

`https://api.swaplume.com/mcp` (streamable HTTP, no auth), with the tools `get_quotes`, `validate_address`,
`create_swap`, `get_swap`, `list_currencies` and `list_providers`.
- Claude Code: `claude mcp add --transport http swaplume https://api.swaplume.com/mcp`
- Claude Desktop, claude.ai: Settings > Connectors > Add custom connector, with that URL.
- Cursor, VS Code, Windsurf and others: add a remote (HTTP) MCP server with that URL.

## More

- `GET /v1/currencies?ticker=usdt`: assets and their networks (filters: `search`, `ticker`, `network`, `provider`).
- `GET /v1/providers`: the exchanges and their terms.
- `GET /v1/prices`: BTC, ETH, SOL, XMR, LTC, XRP and TON in USDT at the best exchange.
- Amounts are decimal strings. Errors: `{"error": {"code", "message", "details"}}`.
- Limits per IP: 60 requests a minute and 20 new swaps an hour, then a 429 with `Retry-After`.