{"openapi":"3.1.0","info":{"title":"Swaplume","description":"Free crypto swap aggregator: one request asks every connected instant exchange for the same swap and returns every\nquote, best first. No API key or account; limits are per IP.\n\n**Flow:** `GET /v1/quotes` → `POST /v1/swaps` (returns the deposit address; with an `Idempotency-Key`, a retry never\nmakes a second swap) → `GET /v1/swaps/{id}` every `poll_after` seconds until `is_final`.\n\n* Assets are a ticker plus a network: `usdt:trx`, or `usdt` with its network in `from_network`/`to_network`. Network\n  names (`tron`, `erc20`, `bep20`) and legacy tickers (`usdttrc20`) work too.\n* Amounts are decimal strings. Every error is `{\"error\": {\"code\", \"message\", \"details\"}}`.\n* The API never holds funds: the user sends the deposit to the exchange, which pays out to the user's address.\n* AI agents: the same operations are MCP tools at `/mcp` (streamable HTTP), and `/llms.txt` is a short guide.\n","version":"0.1.0"},"servers":[{"url":"https://api.swaplume.com"}],"paths":{"/v1/providers":{"get":{"tags":["Meta"],"summary":"List the exchanges compared","operationId":"listProviders","responses":{"200":{"description":"The exchanges.","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/ProviderInfo"},"type":"array","title":"Response Listproviders"}}}},"429":{"description":"Too Many Requests: `rate_limited`","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}}}}}}}},"/v1/currencies":{"get":{"tags":["Currencies"],"summary":"List supported assets (ticker + network)","description":"The assets at least one provider supports, one entry per network. An asset's `id` (`usdt:trx`) works\nanywhere an asset is expected.","operationId":"listCurrencies","parameters":[{"name":"search","in":"query","required":false,"schema":{"description":"Filter by ticker or name (substring).","title":"Search","type":"string","maxLength":64},"description":"Filter by ticker or name (substring)."},{"name":"ticker","in":"query","required":false,"schema":{"description":"Exact ticker, e.g. `usdt`.","title":"Ticker","type":"string","maxLength":32},"description":"Exact ticker, e.g. `usdt`."},{"name":"network","in":"query","required":false,"schema":{"description":"Network code or name, e.g. `trx`/`tron`.","title":"Network","type":"string","maxLength":64},"description":"Network code or name, e.g. `trx`/`tron`."},{"name":"provider","in":"query","required":false,"schema":{"description":"Only assets this provider supports.","title":"Provider","type":"string","maxLength":32},"description":"Only assets this provider supports."}],"responses":{"200":{"description":"The matching assets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrencyList"}}}},"422":{"description":"Unprocessable Content: `invalid_request`","content":{"application/json":{"examples":{"invalid_search":{"summary":"A search too long","value":{"error":{"code":"invalid_request","message":"search: String should have at most 64 characters","details":{"problems":[{"field":"search","message":"String should have at most 64 characters"}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: `rate_limited`","content":{"application/json":{"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/v1/quotes":{"get":{"tags":["Quotes"],"summary":"Compare every provider's rate for a swap, best first","description":"Asks every provider for the same swap at once and returns all the quotes, best first: by what you receive\nafter fees, or with `amount_to`, by what you send. Providers that can't quote are in `errors`, with their limits\nwhen the amount is out of range.","operationId":"getQuotes","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Asset you send: `btc`, `usdt:trx` or legacy `usdttrc20`.","title":"From"},"description":"Asset you send: `btc`, `usdt:trx` or legacy `usdttrc20`."},{"name":"to","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Asset you receive.","title":"To"},"description":"Asset you receive."},{"name":"amount","in":"query","required":false,"schema":{"description":"Amount you send. Pass this or `amount_to`.","title":"Amount","type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},"description":"Amount you send. Pass this or `amount_to`."},{"name":"amount_to","in":"query","required":false,"schema":{"description":"Amount you want to receive, instead of `amount` (fixed rate only): each provider says what to send, and the least comes first.","title":"Amount To","type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},"description":"Amount you want to receive, instead of `amount` (fixed rate only): each provider says what to send, and the least comes first."},{"name":"from_network","in":"query","required":false,"schema":{"description":"Network of `from` if ambiguous.","title":"From Network","type":"string","maxLength":64},"description":"Network of `from` if ambiguous."},{"name":"to_network","in":"query","required":false,"schema":{"description":"Network of `to` if ambiguous.","title":"To Network","type":"string","maxLength":64},"description":"Network of `to` if ambiguous."},{"name":"rate_type","in":"query","required":false,"schema":{"description":"`float` or `fixed`. Default `float`, or `fixed` with `amount_to`.","title":"Rate Type","$ref":"#/components/schemas/RateType"},"description":"`float` or `fixed`. Default `float`, or `fixed` with `amount_to`."},{"name":"providers","in":"query","required":false,"schema":{"description":"Comma-separated provider ids to restrict to.","title":"Providers","type":"string","maxLength":200},"description":"Comma-separated provider ids to restrict to."}],"responses":{"200":{"description":"The comparison.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuotesResponse"}}}},"400":{"description":"Bad Request: `invalid_request`, `ambiguous_asset`","content":{"application/json":{"examples":{"same_asset":{"summary":"The same asset twice","value":{"error":{"code":"invalid_request","message":"`from` and `to` must be different assets."}}},"ambiguous_asset":{"summary":"A ticker on several networks","value":{"error":{"code":"ambiguous_asset","message":"'pepe' exists on 2 networks. Set `from_network` (e.g. from_network=eth) or use 'pepe:<network>'.","details":{"networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found: `unknown_asset`, `unknown_network`, `unknown_provider`","content":{"application/json":{"examples":{"unknown_asset":{"summary":"An unknown asset","value":{"error":{"code":"unknown_asset","message":"Unknown asset 'bitcoin'. Find it in GET /v1/currencies (over MCP, list_currencies).","details":{"suggestions":["btc","bch","btcb","bsv"]}}}},"asset_not_on_network":{"summary":"An asset not on that network","value":{"error":{"code":"unknown_asset","message":"'pepe' is not available on network 'trx'.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_network":{"summary":"An unknown network","value":{"error":{"code":"unknown_network","message":"Unknown network 'tronn' for `to`.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_providers":{"summary":"Unknown providers","value":{"error":{"code":"unknown_provider","message":"None of the requested providers exist.","details":{"providers":["changenow","fixedfloat","sideshift","simpleswap"]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Content: `invalid_request`","content":{"application/json":{"examples":{"invalid_amount":{"summary":"An invalid amount","value":{"error":{"code":"invalid_request","message":"amount: Input should be greater than 0","details":{"problems":[{"field":"amount","message":"Input should be greater than 0"}]}}}},"amount_or_amount_to":{"summary":"Neither or both amounts","value":{"error":{"code":"invalid_request","message":"Pass either `amount` (what you send) or `amount_to` (what you receive).","details":{"problems":[{"field":"","message":"Pass either `amount` (what you send) or `amount_to` (what you receive)."}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: `rate_limited`","content":{"application/json":{"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/v1/quotes/stream":{"get":{"tags":["Quotes"],"summary":"The same comparison, sent as the providers answer (Server-Sent Events)","description":"Same parameters and data as GET /v1/quotes, as an event stream, so the fastest offers show at once. Each\nevent's data is the comparison so far, best first, with `pending` listing the providers still being asked. The\nlast event has no `pending` and is what GET /v1/quotes returns; then the stream ends (with EventSource, close\nit on that event, or it reconnects). A bad request gets a JSON error instead of a stream.","operationId":"streamQuotes","parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Asset you send: `btc`, `usdt:trx` or legacy `usdttrc20`.","title":"From"},"description":"Asset you send: `btc`, `usdt:trx` or legacy `usdttrc20`."},{"name":"to","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Asset you receive.","title":"To"},"description":"Asset you receive."},{"name":"amount","in":"query","required":false,"schema":{"description":"Amount you send. Pass this or `amount_to`.","title":"Amount","type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},"description":"Amount you send. Pass this or `amount_to`."},{"name":"amount_to","in":"query","required":false,"schema":{"description":"Amount you want to receive, instead of `amount` (fixed rate only): each provider says what to send, and the least comes first.","title":"Amount To","type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},"description":"Amount you want to receive, instead of `amount` (fixed rate only): each provider says what to send, and the least comes first."},{"name":"from_network","in":"query","required":false,"schema":{"description":"Network of `from` if ambiguous.","title":"From Network","type":"string","maxLength":64},"description":"Network of `from` if ambiguous."},{"name":"to_network","in":"query","required":false,"schema":{"description":"Network of `to` if ambiguous.","title":"To Network","type":"string","maxLength":64},"description":"Network of `to` if ambiguous."},{"name":"rate_type","in":"query","required":false,"schema":{"description":"`float` or `fixed`. Default `float`, or `fixed` with `amount_to`.","title":"Rate Type","$ref":"#/components/schemas/RateType"},"description":"`float` or `fixed`. Default `float`, or `fixed` with `amount_to`."},{"name":"providers","in":"query","required":false,"schema":{"description":"Comma-separated provider ids to restrict to.","title":"Providers","type":"string","maxLength":200},"description":"Comma-separated provider ids to restrict to."}],"responses":{"200":{"description":"Events, each with the comparison so far.","content":{"text/event-stream":{"itemSchema":{"type":"object","properties":{"data":{"type":"string","contentMediaType":"application/json","contentSchema":{"$ref":"#/components/schemas/QuotesResponse"}},"event":{"type":"string"},"id":{"type":"string"},"retry":{"type":"integer","minimum":0}},"required":["data"]}}}},"400":{"description":"Bad Request: `invalid_request`, `ambiguous_asset`","content":{"application/json":{"examples":{"same_asset":{"summary":"The same asset twice","value":{"error":{"code":"invalid_request","message":"`from` and `to` must be different assets."}}},"ambiguous_asset":{"summary":"A ticker on several networks","value":{"error":{"code":"ambiguous_asset","message":"'pepe' exists on 2 networks. Set `from_network` (e.g. from_network=eth) or use 'pepe:<network>'.","details":{"networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found: `unknown_asset`, `unknown_network`, `unknown_provider`","content":{"application/json":{"examples":{"unknown_asset":{"summary":"An unknown asset","value":{"error":{"code":"unknown_asset","message":"Unknown asset 'bitcoin'. Find it in GET /v1/currencies (over MCP, list_currencies).","details":{"suggestions":["btc","bch","btcb","bsv"]}}}},"asset_not_on_network":{"summary":"An asset not on that network","value":{"error":{"code":"unknown_asset","message":"'pepe' is not available on network 'trx'.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_network":{"summary":"An unknown network","value":{"error":{"code":"unknown_network","message":"Unknown network 'tronn' for `to`.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_providers":{"summary":"Unknown providers","value":{"error":{"code":"unknown_provider","message":"None of the requested providers exist.","details":{"providers":["changenow","fixedfloat","sideshift","simpleswap"]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Content: `invalid_request`","content":{"application/json":{"examples":{"invalid_amount":{"summary":"An invalid amount","value":{"error":{"code":"invalid_request","message":"amount: Input should be greater than 0","details":{"problems":[{"field":"amount","message":"Input should be greater than 0"}]}}}},"amount_or_amount_to":{"summary":"Neither or both amounts","value":{"error":{"code":"invalid_request","message":"Pass either `amount` (what you send) or `amount_to` (what you receive).","details":{"problems":[{"field":"","message":"Pass either `amount` (what you send) or `amount_to` (what you receive)."}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: `rate_limited`","content":{"application/json":{"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/v1/validate-address":{"post":{"tags":["Swaps"],"summary":"Check a payout or refund address before creating a swap","description":"Catches links, random text, addresses for another network and typos in checksummed formats.\n`POST` so addresses stay out of URLs and logs. `POST /v1/swaps` runs the same check.","operationId":"validateAddress","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressValidationRequest"}}},"required":true},"responses":{"200":{"description":"Whether the address fits the asset's network.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressValidation"}}}},"400":{"description":"Bad Request: `ambiguous_asset`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"ambiguous_address_asset":{"summary":"A ticker on several networks","value":{"error":{"code":"ambiguous_asset","message":"'pepe' exists on 2 networks. Set `network` (e.g. network=eth) or use 'pepe:<network>'.","details":{"networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}}}}}},"404":{"description":"Not Found: `unknown_asset`, `unknown_network`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown_asset":{"summary":"An unknown asset","value":{"error":{"code":"unknown_asset","message":"Unknown asset 'bitcoin'. Find it in GET /v1/currencies (over MCP, list_currencies).","details":{"suggestions":["btc","bch","btcb","bsv"]}}}},"asset_not_on_network":{"summary":"An asset not on that network","value":{"error":{"code":"unknown_asset","message":"'pepe' is not available on network 'trx'.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_address_network":{"summary":"An unknown network","value":{"error":{"code":"unknown_network","message":"Unknown network 'tronn' for `asset`.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}}}}}},"422":{"description":"Unprocessable Content: `invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing_address":{"summary":"No address","value":{"error":{"code":"invalid_request","message":"address: Field required","details":{"problems":[{"field":"address","message":"Field required"}]}}}}}}}},"429":{"description":"Too Many Requests: `rate_limited`","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}}}}}}}},"/v1/swaps":{"post":{"tags":["Swaps"],"summary":"Create a swap (returns the deposit address)","description":"Creates the swap with one provider and returns its deposit address: send `amount_from` of `from` there.\nWith `provider` (from a quote), only that provider is asked. Without it, the best one now, then the next best\nif it fails, among those without a `notice`. Addresses are checked first, as by POST /v1/validate-address.","operationId":"createSwap","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"description":"Any unique value, such as a UUID, made once per swap you mean to create. A request made again with the same key and body returns the swap the first one created: a retry never makes a second swap.","title":"Idempotency-Key","type":"string","maxLength":255},"description":"Any unique value, such as a UUID, made once per swap you mean to create. A request made again with the same key and body returns the swap the first one created: a retry never makes a second swap."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapCreate"}}}},"responses":{"201":{"description":"The swap, with where to send the deposit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Swap"}}}},"400":{"description":"Bad Request: `invalid_request`, `ambiguous_asset`, `invalid_address`, `invalid_extra_id`, `invalid_email`, `email_required`, `refund_address_required`, `provider_required`","content":{"application/json":{"examples":{"same_asset":{"summary":"The same asset twice","value":{"error":{"code":"invalid_request","message":"`from` and `to` must be different assets."}}},"rate_id_without_provider":{"summary":"`rate_id` without `provider`","value":{"error":{"code":"invalid_request","message":"`rate_id` requires `provider` (the provider that issued it)."}}},"ambiguous_asset":{"summary":"A ticker on several networks","value":{"error":{"code":"ambiguous_asset","message":"'pepe' exists on 2 networks. Set `from_network` (e.g. from_network=eth) or use 'pepe:<network>'.","details":{"networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"invalid_address":{"summary":"An invalid address","value":{"error":{"code":"invalid_address","message":"Not a valid Ethereum (ERC-20) address.","details":{"field":"address"}}}},"invalid_extra_id":{"summary":"An invalid memo or tag","value":{"error":{"code":"invalid_extra_id","message":"SideShift: Invalid memo for this address","details":{"field":"extra_id"}}}},"invalid_email":{"summary":"An email the provider refuses","value":{"error":{"code":"invalid_email","message":"Alfacash: Please enter a valid e-mail address.","details":{"field":"email"}}}},"email_required":{"summary":"The provider needs an email","value":{"error":{"code":"email_required","message":"Alfacash needs the user's email (it uses it to reach them, e.g. about a refund) for this swap. Pass `email`.","details":{"field":"email","provider":"alfacash"}}}},"refund_address_required":{"summary":"The provider needs a refund address","value":{"error":{"code":"refund_address_required","message":"InstaSwap needs a refund address (where the deposit goes back if the swap can't be done) for this swap. Pass `refund_address`.","details":{"field":"refund_address","provider":"instaswap"}}}},"provider_required":{"summary":"Only a provider with a notice can do it","value":{"error":{"code":"provider_required","message":"Only exchanges that require their notice to be shown first, such as FixedFloat, can do this swap right now. Show the quote's `notice`, then pass its `provider`.","details":{"provider":"fixedfloat"}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found: `unknown_asset`, `unknown_network`, `unknown_provider`","content":{"application/json":{"examples":{"unknown_asset":{"summary":"An unknown asset","value":{"error":{"code":"unknown_asset","message":"Unknown asset 'bitcoin'. Find it in GET /v1/currencies (over MCP, list_currencies).","details":{"suggestions":["btc","bch","btcb","bsv"]}}}},"asset_not_on_network":{"summary":"An asset not on that network","value":{"error":{"code":"unknown_asset","message":"'pepe' is not available on network 'trx'.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_network":{"summary":"An unknown network","value":{"error":{"code":"unknown_network","message":"Unknown network 'tronn' for `to`.","details":{"available_networks":[{"network":"eth","network_name":"Ethereum (ERC-20)","id":"pepe:eth","name":"Pepe"},{"network":"bsc","network_name":"BNB Smart Chain (BEP-20)","id":"pepe:bsc","name":"Pepe"}]}}}},"unknown_provider":{"summary":"An unknown provider","value":{"error":{"code":"unknown_provider","message":"Unknown provider 'changenoww'.","details":{"providers":["changenow","fixedfloat","sideshift","simpleswap"]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: `rate_expired`","content":{"application/json":{"examples":{"rate_expired":{"summary":"The fixed rate expired","value":{"error":{"code":"rate_expired","message":"CCE Cash's fixed rate expired. Get a new quote and try again."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Content: `invalid_request`, `no_route`, `amount_too_low`, `amount_too_high`, `pair_unsupported`, `pair_unavailable`, `rate_type_unsupported`, `amount_to_unsupported`","content":{"application/json":{"examples":{"invalid_amount":{"summary":"An invalid amount","value":{"error":{"code":"invalid_request","message":"amount: Input should be greater than 0","details":{"problems":[{"field":"amount","message":"Input should be greater than 0"}]}}}},"amount_or_amount_to":{"summary":"Neither or both amounts","value":{"error":{"code":"invalid_request","message":"Pass either `amount` (what you send) or `amount_to` (what you receive).","details":{"problems":[{"field":"","message":"Pass either `amount` (what you send) or `amount_to` (what you receive)."}]}}}},"no_route":{"summary":"No provider can do it","value":{"error":{"code":"no_route","message":"No provider can do this swap right now.","details":{"errors":[{"provider":"fixedfloat","code":"amount_too_low","message":"FixedFloat: the minimum is 0.00013168 BTC"},{"provider":"sideshift","code":"pair_unavailable","message":"SideShift returned no price for this pair"}]}}}},"amount_too_low":{"summary":"Below the provider's minimum","value":{"error":{"code":"amount_too_low","message":"FixedFloat: the minimum is 0.00013168 BTC","details":{"min_amount":"0.00013168","max_amount":"1.78658206"}}}},"amount_too_high":{"summary":"Above the provider's maximum","value":{"error":{"code":"amount_too_high","message":"FixedFloat: the maximum is 1.78658206 BTC","details":{"min_amount":"0.00013168","max_amount":"1.78658206"}}}},"pair_unsupported":{"summary":"The provider doesn't list an asset","value":{"error":{"code":"pair_unsupported","message":"Alfacash does not support pepe:bsc"}}},"pair_unavailable":{"summary":"The provider can't do the pair now","value":{"error":{"code":"pair_unavailable","message":"SideShift returned no price for this pair"}}},"rate_type_unsupported":{"summary":"No rate of that type","value":{"error":{"code":"rate_type_unsupported","message":"SideShift has no fixed rate for this pair"}}},"amount_to_unsupported":{"summary":"No swaps by amount received","value":{"error":{"code":"amount_to_unsupported","message":"CCE Cash can't fix the amount received"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: `rate_limited`","content":{"application/json":{"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}},"swaps_rate_limited":{"summary":"Too many swaps created from this IP","value":{"error":{"code":"rate_limited","message":"Too many swaps created from this IP. Retry in 1260s.","details":{"retry_after":1260}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}},"502":{"description":"Bad Gateway: `swap_failed`, `provider_error`, `provider_unavailable`","content":{"application/json":{"examples":{"swap_failed":{"summary":"No provider could create it","value":{"error":{"code":"swap_failed","message":"Could not create the swap with any provider. Try again shortly.","details":{"attempts":[{"provider":"changenow","code":"provider_error","message":"ChangeNOW is having problems (HTTP 500)"},{"provider":"simpleswap","code":"provider_timeout","message":"SimpleSwap did not respond in time"}]}}}},"provider_error":{"summary":"The provider failed","value":{"error":{"code":"provider_error","message":"ChangeNOW is having problems (HTTP 500)"}}},"provider_unavailable":{"summary":"The provider refuses requests for now","value":{"error":{"code":"provider_unavailable","message":"SimpleSwap is blocking our requests for now"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable: `provider_rate_limited`","content":{"application/json":{"examples":{"provider_rate_limited":{"summary":"The provider is rate limiting","value":{"error":{"code":"provider_rate_limited","message":"Changelly is rate limiting requests"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Gateway Timeout: `provider_timeout`","content":{"application/json":{"examples":{"provider_timeout":{"summary":"The provider didn't answer in time","value":{"error":{"code":"provider_timeout","message":"SimpleSwap did not respond in time"}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/swaps/{swap_id}":{"get":{"tags":["Swaps"],"summary":"Get a swap's live status","description":"The swap, with its live status from the provider. Read it again after `poll_after` seconds until\n`is_final`: every read asks the exchange. If the provider can't be reached, the swap is as last seen, with a\nwarning. A swap that never got a deposit is deleted a week after it was created.","operationId":"getSwap","parameters":[{"name":"swap_id","in":"path","required":true,"schema":{"type":"string","minLength":4,"maxLength":40,"pattern":"^sw_[a-z0-9]+$","description":"The swap's `id`.","title":"Swap Id"},"description":"The swap's `id`."}],"responses":{"200":{"description":"The swap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Swap"}}}},"404":{"description":"Not Found: `swap_not_found`","content":{"application/json":{"examples":{"swap_not_found":{"summary":"No such swap","value":{"error":{"code":"swap_not_found","message":"No swap with id 'sw_k3j9x0a2b7'. A swap that never got a deposit is deleted a week after it was created."}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Content: `invalid_request`","content":{"application/json":{"examples":{"invalid_swap_id":{"summary":"Not a swap id","value":{"error":{"code":"invalid_request","message":"swap_id: String should match pattern '^sw_[a-z0-9]+$'","details":{"problems":[{"field":"swap_id","message":"String should match pattern '^sw_[a-z0-9]+$'"}]}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests: `rate_limited`","content":{"application/json":{"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}}}}}},"/v1/prices":{"get":{"tags":["Quotes"],"summary":"Prices of BTC, ETH, SOL, XMR, LTC, XRP and TON in USDT","description":"What one coin costs in USDT at the best exchange, for a 1,000 USDT swap (USDT on Tron): the exchanges' own\nprices, fees included. Asked again every 5 minutes at most. `/v1/prices.png` draws them.","operationId":"getPrices","responses":{"200":{"description":"The prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"429":{"description":"Too Many Requests: `rate_limited`","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}}}}}}}},"/v1/prices.png":{"get":{"tags":["Quotes"],"summary":"The prices as an image","description":"`/v1/prices` drawn for link previews and chat bots, with the time the exchanges were asked.","operationId":"getPricesImage","responses":{"200":{"description":"A 1200x630 PNG.","content":{"image/png":{}}},"429":{"description":"Too Many Requests: `rate_limited`","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"Too many requests from this IP","value":{"error":{"code":"rate_limited","message":"Too many requests. Retry in 12s.","details":{"retry_after":12}}}}}}}}}}},"/health":{"get":{"tags":["Meta"],"summary":"Service health","operationId":"health","responses":{"200":{"description":"The service's state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"components":{"schemas":{"AddressValidation":{"properties":{"asset":{"$ref":"#/components/schemas/AssetRef","description":"The asset the address was checked for."},"valid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Valid","description":"`true`: right format for this network (and checksum, where the format has one we verify). `false`: see `reason`. `null`: this network's format is not checked here; the exchange validates the address when the swap is created."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the address is invalid, written for the end user.","examples":[null]},"extra_id_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extra Id Name","description":"If set, this asset uses a memo/tag (e.g. 'Destination tag'): pass it as `extra_id` when the receiving wallet or account needs it.","examples":[null]}},"type":"object","required":["asset","valid"],"title":"AddressValidation"},"AddressValidationRequest":{"properties":{"asset":{"type":"string","maxLength":64,"minLength":1,"title":"Asset","description":"Asset the address receives: 'usdt:trx', 'btc'..."},"network":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Network","description":"Network of `asset` if ambiguous."},"address":{"type":"string","maxLength":256,"title":"Address","description":"The address to check."}},"type":"object","required":["asset","address"],"title":"AddressValidationRequest","examples":[{"address":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","asset":"usdt:trx"}]},"AssetRef":{"properties":{"id":{"type":"string","title":"Id","description":"Asset id: `ticker:network`, or `ticker:network:contract` for a token whose ticker another token has on that network. Accepted wherever an asset is expected.","examples":["usdt:trx"]},"ticker":{"type":"string","title":"Ticker","examples":["usdt"]},"network":{"type":"string","title":"Network","description":"Canonical network code.","examples":["trx"]},"network_name":{"type":"string","title":"Network Name","examples":["Tron (TRC-20)"]},"name":{"type":"string","title":"Name","examples":["Tether (TRC20)"]}},"type":"object","required":["id","ticker","network","network_name","name"],"title":"AssetRef"},"CoinPrice":{"properties":{"id":{"type":"string","title":"Id","description":"Asset id.","examples":["btc:btc"]},"name":{"type":"string","title":"Name","examples":["Bitcoin"]},"price":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Price","description":"What one coin costs in USDT at the best exchange, for a 1,000 USDT swap. Null if no exchange quoted it this time.","examples":["74915.57"]},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"The exchange with that price.","examples":["instaswap"]}},"type":"object","required":["id","name","price","provider"],"title":"CoinPrice"},"Currency":{"properties":{"id":{"type":"string","title":"Id","description":"Asset id: `ticker:network`, or `ticker:network:contract` for a token whose ticker another token has on that network. Accepted wherever an asset is expected.","examples":["usdt:trx"]},"ticker":{"type":"string","title":"Ticker","examples":["usdt"]},"network":{"type":"string","title":"Network","description":"Canonical network code.","examples":["trx"]},"network_name":{"type":"string","title":"Network Name","examples":["Tron (TRC-20)"]},"name":{"type":"string","title":"Name","examples":["Tether (TRC20)"]},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image","description":"A logo URL from one of the providers, if any.","examples":["https://content-api.changenow.io/uploads/usdttrc20_87164a7b35.svg"]},"contract":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract","description":"Token contract address; null for native coins.","examples":["TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"]},"extra_id_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extra Id Name","description":"Label of the memo/tag field when this asset uses one (e.g. XRP 'Destination tag'). If your receiving wallet needs one, pass it as `extra_id` when creating a swap.","examples":[null]},"providers":{"items":{"type":"string"},"type":"array","title":"Providers","description":"Providers that support this asset.","examples":[["changenow","fixedfloat","sideshift"]]}},"type":"object","required":["id","ticker","network","network_name","name","providers"],"title":"Currency"},"CurrencyList":{"properties":{"count":{"type":"integer","title":"Count","description":"Number of matching assets."},"currencies":{"items":{"$ref":"#/components/schemas/Currency"},"type":"array","title":"Currencies","description":"The matching assets, by ticker then network (with `search`, the exact ticker first)."}},"type":"object","required":["count","currencies"],"title":"CurrencyList"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"What went wrong, for code to act on. Each endpoint lists the codes it sends.","examples":["amount_too_low"]},"message":{"type":"string","title":"Message","description":"What went wrong, in plain English.","examples":["FixedFloat: the minimum is 0.00013168 BTC"]},"details":{"additionalProperties":true,"type":"object","title":"Details","description":"More about it, for some codes: e.g. `min_amount` with `amount_too_low`, `networks` with `ambiguous_asset`, `retry_after` (seconds) with `rate_limited`. Left out when empty.","examples":[{"max_amount":"1.78658206","min_amount":"0.00013168"}]}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse","description":"The body of every error, whatever its HTTP status."},"Health":{"properties":{"status":{"type":"string","enum":["ok","starting"],"title":"Status","description":"`starting` until the asset list has loaded."},"version":{"type":"string","title":"Version","examples":["0.1.0"]},"uptime_s":{"type":"integer","title":"Uptime S","description":"Seconds since the API started.","examples":[86400]},"assets":{"type":"integer","title":"Assets","description":"Assets in the list.","examples":[2785]},"registry_updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Registry Updated At","description":"When the asset list was last refreshed.","examples":["2026-11-05T22:30:00Z"]},"providers":{"additionalProperties":{"type":"string"},"type":"object","title":"Providers","description":"Each provider: `ok`, or `degraded: ` and why its currency list failed to refresh.","examples":[{"changenow":"ok","sideshift":"ok"}]},"cache":{"additionalProperties":{"type":"integer"},"type":"object","title":"Cache","description":"Entries in the quote cache, and its counters.","examples":[{"coalesced":88,"entries":412,"errors_cached":35,"hits":9520,"misses":1204,"stale_hits":310}]}},"type":"object","required":["status","version","uptime_s","assets","registry_updated_at","providers","cache"],"title":"Health"},"Kyc":{"type":"string","enum":["never","rare","occasional","often"],"title":"Kyc","description":"How likely an exchange is to pause a swap and ask the user for identity verification (KYC)."},"Limits":{"properties":{"min_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount","description":"The lowest minimum an exchange states for the amount sent.","examples":["0.02"]},"max_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount","description":"The highest maximum an exchange states for the amount sent.","examples":[null]},"min_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount To","description":"The lowest minimum an exchange states for the amount received (with `amount_to`).","examples":[null]},"max_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount To","description":"The highest maximum an exchange states for the amount received (with `amount_to`).","examples":[null]}},"type":"object","title":"Limits"},"PendingQuote":{"properties":{"provider":{"type":"string","title":"Provider","examples":["changenow"]},"provider_name":{"type":"string","title":"Provider Name","examples":["ChangeNOW"]}},"type":"object","required":["provider","provider_name"],"title":"PendingQuote"},"PriceList":{"properties":{"at":{"type":"string","format":"date-time","title":"At","description":"When the exchanges were asked: every 5 minutes at most."},"prices":{"items":{"$ref":"#/components/schemas/CoinPrice"},"type":"array","title":"Prices"}},"type":"object","required":["at","prices"],"title":"PriceList"},"ProviderInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Pass it in `providers` (GET /v1/quotes) or as `provider` (POST /v1/swaps).","examples":["changenow"]},"name":{"type":"string","title":"Name","examples":["ChangeNOW"]},"website":{"type":"string","title":"Website","examples":["https://changenow.io"]},"logo":{"type":"string","title":"Logo","description":"The exchange's logo, as swaplume.com shows it.","examples":["https://swaplume.com/exchanges/changenow.webp"]},"status":{"type":"string","enum":["ok","degraded"],"title":"Status","description":"`degraded` if its currency list failed to refresh."},"currencies":{"type":"integer","title":"Currencies","description":"Number of assets currently supported.","examples":[1163]},"refund_address_supported":{"type":"boolean","title":"Refund Address Supported","description":"Whether a refund address can be set at swap creation.","examples":[true]},"refund_address_required":{"type":"boolean","title":"Refund Address Required","description":"Whether swaps with this provider need `refund_address`.","examples":[false]},"email_required":{"type":"boolean","title":"Email Required","description":"Whether swaps with this provider need the user's `email`.","examples":[false]},"amount_to_supported":{"type":"boolean","title":"Amount To Supported","description":"Whether it does fixed swaps by the amount received (`amount_to`).","examples":[true]},"kyc":{"anyOf":[{"$ref":"#/components/schemas/Kyc"},{"type":"null"}],"description":"How likely this exchange is to pause a swap and ask the user for identity verification (KYC): `never`, `rare`, `occasional` or `often`. Null when not rated yet.","examples":["occasional"]},"ip_shared":{"type":"boolean","title":"Ip Shared","description":"Whether this exchange gets the IP address of the request that creates the swap, as it would on its own site (for its fraud and country checks).","examples":[true]},"ip_kept":{"type":"boolean","title":"Ip Kept","description":"Whether Swaplume keeps the IP address and browser languages of the request that creates the swap, for a year, because this exchange requires it of its partners (a week if no deposit arrives: the swap is then deleted). Shared only with that exchange, when it asks about the swap.","examples":[false]},"notice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice","description":"A sentence this exchange requires its partners to show the user before a swap is created, about its rules (`terms_url`). Show it next to the button that creates the swap.","examples":[null]},"terms_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms Url","description":"The exchange's rules, which `notice` refers to.","examples":[null]}},"type":"object","required":["id","name","website","logo","status","currencies","refund_address_supported","refund_address_required","email_required","amount_to_supported","kyc","ip_shared","ip_kept"],"title":"ProviderInfo"},"Quote":{"properties":{"provider":{"type":"string","title":"Provider","description":"Provider id: pass it as `provider` to POST /v1/swaps to swap at this quote.","examples":["changenow"]},"provider_name":{"type":"string","title":"Provider Name","examples":["ChangeNOW"]},"rate_type":{"$ref":"#/components/schemas/RateType"},"amount_from":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","title":"Amount From","description":"Amount you send. With `amount_to`, what this provider asks for it.","examples":["0.01"]},"amount_to":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","title":"Amount To","description":"Amount you receive after all provider and network fees (an estimate for `float`, guaranteed for `fixed` until `expires_at`). With `amount_to`, the amount you asked for.","examples":["747.673444"]},"rate":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","title":"Rate","description":"amount_to / amount_from.","examples":["74767.3444"]},"diff_from_best_pct":{"type":"number","title":"Diff From Best Pct","description":"How this quote compares to the best one, in percent (0 = best; below 0: you receive less, or with `amount_to`, send more).","examples":[0]},"min_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount","description":"The least you can send this provider for the pair.","examples":["0.0001684"]},"max_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount","description":"The most you can send, if the provider has a maximum.","examples":[null]},"min_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount To","description":"The least you can receive, when the provider states it (with `amount_to`).","examples":[null]},"max_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount To","description":"The most you can receive, when the provider states it (with `amount_to`).","examples":[null]},"rate_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rate Id","description":"Fixed-rate id; pass it to POST /v1/swaps to lock this rate.","examples":[null]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"When the fixed rate expires (30 s to 2 minutes, depending on the provider).","examples":[null]},"eta_minutes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eta Minutes","description":"Provider's estimated duration, e.g. '10-60'.","examples":["10-60"]},"email_required":{"type":"boolean","title":"Email Required","description":"This provider needs the user's `email` to create the swap.","default":false},"refund_address_supported":{"type":"boolean","title":"Refund Address Supported","description":"Whether this provider takes `refund_address` when the swap is created. If false, it arranges refunds with the user when one is needed.","default":false},"refund_address_required":{"type":"boolean","title":"Refund Address Required","description":"This provider needs `refund_address` to create the swap.","default":false},"kyc":{"anyOf":[{"$ref":"#/components/schemas/Kyc"},{"type":"null"}],"description":"How likely this exchange is to pause a swap and ask the user for identity verification (KYC): `never`, `rare`, `occasional` or `often`. Null when not rated yet.","examples":["occasional"]},"ip_shared":{"type":"boolean","title":"Ip Shared","description":"Whether this exchange gets the IP address of the request that creates the swap, as it would on its own site (for its fraud and country checks).","default":false,"examples":[true]},"ip_kept":{"type":"boolean","title":"Ip Kept","description":"Whether Swaplume keeps the IP address and browser languages of the request that creates the swap, for a year, because this exchange requires it of its partners (a week if no deposit arrives: the swap is then deleted). Shared only with that exchange, when it asks about the swap.","default":false},"notice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice","description":"A sentence this exchange requires its partners to show the user before a swap is created, about its rules (`terms_url`). Show it next to the button that creates the swap.","examples":[null]},"terms_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Terms Url","description":"The exchange's rules, which `notice` refers to.","examples":[null]},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning","description":"A note from the provider about this swap, in its words.","examples":[null]}},"type":"object","required":["provider","provider_name","rate_type","amount_from","amount_to","rate","diff_from_best_pct"],"title":"Quote"},"QuoteError":{"properties":{"provider":{"type":"string","title":"Provider","examples":["sideshift"]},"provider_name":{"type":"string","title":"Provider Name","examples":["SideShift"]},"code":{"type":"string","title":"Code","description":"Why: `amount_too_low` or `amount_too_high` (see the min/max), `pair_unsupported` (it doesn't list an asset), `pair_unavailable`, `rate_type_unsupported`, `amount_to_unsupported`, or the provider failing: `provider_unavailable`, `provider_rate_limited`, `provider_timeout`, `provider_error`, `provider_auth_error`.","examples":["amount_too_low"]},"message":{"type":"string","title":"Message","description":"Why, in plain English.","examples":["SideShift: the minimum is 0.02 BTC"]},"min_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount","description":"The least you can send, when the amount is out of range.","examples":["0.02"]},"max_amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount","description":"The most you can send, when the amount is out of range.","examples":["1.2"]},"min_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Min Amount To","description":"The least you can receive, when the provider states it (with `amount_to`).","examples":[null]},"max_amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Max Amount To","description":"The most you can receive, when the provider states it (with `amount_to`).","examples":[null]}},"type":"object","required":["provider","provider_name","code","message"],"title":"QuoteError"},"QuotesResponse":{"properties":{"from":{"$ref":"#/components/schemas/AssetRef","description":"The asset you send, as understood from your request.","examples":[{"id":"btc:btc","name":"Bitcoin","network":"btc","network_name":"Bitcoin","ticker":"btc"}]},"to":{"$ref":"#/components/schemas/AssetRef","description":"The asset you receive, as understood from your request.","examples":[{"id":"usdt:trx","name":"Tether (TRC20)","network":"trx","network_name":"Tron (TRC-20)","ticker":"usdt"}]},"amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount","description":"The amount to send you asked about; null with `amount_to`.","examples":["0.01"]},"amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount To","description":"The amount to receive you asked about (fixed rate only); null with `amount`.","examples":[null]},"rate_type":{"$ref":"#/components/schemas/RateType"},"best":{"anyOf":[{"$ref":"#/components/schemas/Quote"},{"type":"null"}],"description":"The quote that gives you the most, or with `amount_to`, asks the least; null if no provider can do it."},"quotes":{"items":{"$ref":"#/components/schemas/Quote"},"type":"array","title":"Quotes","description":"All successful quotes, best first."},"errors":{"items":{"$ref":"#/components/schemas/QuoteError"},"type":"array","title":"Errors","description":"Providers that could not quote, and why."},"savings_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Savings Pct","description":"How much better the best quote is than the worst successful one, in percent: you receive that much more, or with `amount_to`, send that much less.","examples":[2.06]},"limits":{"anyOf":[{"$ref":"#/components/schemas/Limits"},{"type":"null"}],"description":"When no exchange can do the swap because of the amount: the lowest minimum and the highest maximum they state, on the amount asked about (`amount` or `amount_to`), or on the other one when none states those. Null when there's an offer.","examples":[null]},"refresh_after":{"type":"integer","title":"Refresh After","description":"Seconds until these quotes are worth asking for again (floating rates move, fixed ones expire). Ask then, not sooner: exchanges count every quote.","examples":[20]},"pending":{"items":{"$ref":"#/components/schemas/PendingQuote"},"type":"array","title":"Pending","description":"Providers still being asked. Only in /v1/quotes/stream events: the last one, like GET /v1/quotes, has none.","examples":[[]]},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"When the providers answered.","examples":["2026-11-05T22:34:34Z"]}},"type":"object","required":["from","to","amount","amount_to","rate_type","best","quotes","errors","refresh_after","generated_at"],"title":"QuotesResponse"},"RateType":{"type":"string","enum":["float","fixed"],"title":"RateType","description":"`float`: the market rate when the deposit arrives. `fixed`: what you receive is locked when the swap is\ncreated, usually at a slightly worse rate."},"Swap":{"properties":{"id":{"type":"string","title":"Id","description":"Our swap id: GET /v1/swaps/{id} returns its status.","examples":["sw_k3j9x0a2b7q4"]},"status":{"$ref":"#/components/schemas/SwapStatus","description":"Where the swap is (see SwapStatus).","examples":["waiting"]},"is_final":{"type":"boolean","title":"Is Final","description":"True once the swap can no longer change (finished, failed, refunded, expired).","examples":[false]},"poll_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Poll After","description":"Seconds to wait before reading the swap again: 15 while its deposit is awaited or it moves, 60 once the deposit is an hour late or past `expires_at`, 300 while the exchange holds it. Null once `is_final`: stop then.","examples":[15]},"instructions":{"type":"string","title":"Instructions","description":"The next step, in plain English, for the user.","examples":["Send 0.01 BTC on Bitcoin to bc1q...exchange-deposit-address. The final amount follows the market rate when the deposit is confirmed. You should receive about 747.673444 USDT."]},"provider":{"type":"string","title":"Provider","description":"Id of the provider doing the swap.","examples":["changenow"]},"provider_name":{"type":"string","title":"Provider Name","examples":["ChangeNOW"]},"provider_swap_id":{"type":"string","title":"Provider Swap Id","description":"The provider's own id, for their support.","examples":["a1f8c3e09b2d47"]},"provider_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Status","description":"The status as the provider words it.","examples":["waiting"]},"from":{"$ref":"#/components/schemas/AssetRef","examples":[{"id":"btc:btc","name":"Bitcoin","network":"btc","network_name":"Bitcoin","ticker":"btc"}]},"to":{"$ref":"#/components/schemas/AssetRef","examples":[{"id":"usdt:trx","name":"Tether (TRC20)","network":"trx","network_name":"Tron (TRC-20)","ticker":"usdt"}]},"rate_type":{"$ref":"#/components/schemas/RateType"},"amount_from":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount From","description":"Amount to send (or received, once known).","examples":["0.01"]},"amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount To","description":"Expected payout (or sent, once known).","examples":["747.673444"]},"deposit_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Address","description":"Send `amount_from` of `from` here.","examples":["bc1q...exchange-deposit-address"]},"deposit_extra_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Extra Id","description":"If set, include this memo/tag in your deposit or the funds may be lost.","examples":[null]},"deposit_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deposit Uri","description":"The deposit as a payment link with the amount (BIP 21, EIP-681, Solana Pay, Monero), for a QR code; null where the network has none: encode `deposit_address` then.","examples":["bitcoin:bc1q...?amount=0.01"]},"payout_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payout Address","description":"Where the provider sends what you receive.","examples":["TXYZ...your-tron-address"]},"payout_extra_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payout Extra Id","description":"Memo/tag of the payout address.","examples":[null]},"refund_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refund Address","description":"Where the provider returns the deposit if the swap fails.","examples":["bc1q...your-btc-address"]},"tx_in":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx In","description":"Deposit transaction hash.","examples":[null]},"tx_out":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tx Out","description":"Payout transaction hash.","examples":[null]},"created_at":{"type":"string","format":"date-time","title":"Created At","examples":["2026-11-05T22:35:02Z"]},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At","description":"When Swaplume last saw the swap change.","examples":["2026-11-05T22:35:02Z"]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Deposit deadline / fixed-rate expiry, if any.","examples":[null]},"track_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Track Url","description":"Provider's public status page, if available.","examples":["https://changenow.io/exchange/txs/a1f8c3e09b2d47"]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"What the user should know, e.g. that the live status couldn't be fetched (the swap is then as last seen).","examples":[[]]}},"type":"object","required":["id","status","is_final","instructions","provider","provider_name","provider_swap_id","from","to","rate_type","created_at"],"title":"Swap"},"SwapCreate":{"properties":{"from":{"type":"string","maxLength":64,"minLength":1,"title":"From","description":"Asset you send: a ticker ('btc'), 'ticker:network' ('usdt:trx') or a legacy ticker ('usdttrc20')."},"from_network":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"From Network","description":"Network of `from` if ambiguous (codes or names: 'trx', 'tron', 'trc20')."},"to":{"type":"string","maxLength":64,"minLength":1,"title":"To","description":"Asset you receive."},"to_network":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"To Network","description":"Network of `to` if ambiguous."},"amount":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount","description":"Amount you send. Pass this or `amount_to`."},"amount_to":{"anyOf":[{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["0.1"]},{"type":"null"}],"title":"Amount To","description":"Amount you want to receive, instead of `amount`: a fixed-rate swap where the provider sets what you send (`amount_from` in the reply). Providers with `amount_to_supported` take it."},"address":{"type":"string","maxLength":256,"minLength":4,"title":"Address","description":"Your payout address for `to`."},"extra_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Extra Id","description":"Memo/tag for the payout address, if needed."},"refund_address":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Refund Address","description":"Where `from` funds go if the swap fails. Recommended, and required by providers whose quote has `refund_address_required`."},"refund_extra_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Refund Extra Id","description":"Memo/tag for the refund address, if needed."},"rate_type":{"$ref":"#/components/schemas/RateType","description":"`float` (market rate at deposit time) or `fixed` (locked amount, slightly worse rate). Default `float`, or `fixed` with `amount_to`.","default":"float"},"provider":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Provider","description":"Provider id from a quote. Omit to use the best quote at creation time, with automatic fallback to the next best."},"rate_id":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Rate Id","description":"Fixed rate only: `rate_id` from a quote by the same `provider`. If omitted, a fresh fixed rate is requested."},"email":{"anyOf":[{"type":"string","maxLength":254,"format":"email"},{"type":"null"}],"title":"Email","description":"The user's email. Only for providers whose quote has `email_required` (they use it to reach the user, e.g. about a refund). Passed to that provider only; not stored by this API."}},"type":"object","required":["from","to","address"],"title":"SwapCreate","examples":[{"address":"TXYZ...your-tron-address","amount":"0.01","from":"btc","refund_address":"bc1q...your-btc-address","to":"usdt","to_network":"trx"},{"address":"0x...your-eth-address","amount_to":"1","from":"btc","refund_address":"bc1q...your-btc-address","to":"eth"}]},"SwapStatus":{"type":"string","enum":["waiting","confirming","exchanging","sending","finished","failed","refunding","refunded","expired","verifying","action_required","unknown"],"title":"SwapStatus","description":"Where a swap is: `waiting` for the deposit, `confirming` it on the blockchain, `exchanging`, `sending` the\npayout, then `finished`. Otherwise: `failed`, `refunding` and `refunded` (the deposit goes back), `expired` (no\ndeposit in time), `verifying` (held by the exchange for a compliance check), `action_required` (the exchange\nneeds a decision from the user, e.g. after a wrong amount was sent) or `unknown`."}}},"tags":[{"name":"Quotes"},{"name":"Swaps"},{"name":"Currencies"},{"name":"Meta"}]}