MindSwap API
The same API mindswap.io runs on. Amounts are decimal strings, never numbers.
Authentication
Send your key as x-api-key, or as Authorization: Bearer msk_live_…. Call from your server: the API only accepts browsers on mindswap.io.
cap from tracking (read-only, 24 h).New keys switch on after your account's first completed order. Until then calls answer key_inactive.
List assets
No keyEvery asset you can swap, with its networks and venues. Cached for 60 s: send If-None-Match with the ETag and an unchanged list answers 304.
curl https://api.mindswap.io/v1/assets{
"assets": [{
"id": "btc:bitcoin",
"symbol": "BTC",
"name": "Bitcoin",
"network": "bitcoin",
"contract": null,
"decimals": 8,
"memo": "none",
"status": "active"
}, …],
"networks": [ … ],
"venues": [ … ]
}Response
- assets
- Asset[]Each asset's
id(symbol:network), symbol, name, network, decimals, memo rule and status. - networks
- Network[]Each network's name, confirmations and explorer link.
- venues
- Venue[]The
id, name and logo of each venue a route can run on.
Get quotes
No keyEvery route we can run for this amount, answered by a deadline, grouped by order type with MIND's pick first. Routes that arrive late come through the stream.
Query
- fromRequired
- asset IDThe asset you send,
symbol:networkin lower case, for examplebtc:bitcoin. - toRequired
- asset IDThe asset you receive, for example
eth:ethereum. - amountInRequired
- decimalHow much you send, in whole units as a string:
"0.1"BTC, never satoshi.
curl https://api.mindswap.io/v1/quotes \
--get \
-d from=btc:bitcoin \
-d to=eth:ethereum \
-d amountIn=0.1{
"routes": [{
"routeId": "r1.k1.Zk3v…",
"kind": "exchange",
"rateType": "fixed",
"amountIn": "0.1",
"amountOut": "3.5324",
"fees": { "totalUser": {
"amount": "0.0283",
"asset": "eth:ethereum"
} },
"expiresAt": "2026-11-17T14:15:00Z"
}],
"mind": {
"float": "r1.k1.Hn8w…",
"fixed": "r1.k1.Zk3v…",
"private": null
},
"complete": true
}Response
- routes
- Route[]Each priced route. Pass its
routeIdto create an order beforeexpiresAt. - mind
- objectThe
routeIdMIND picks for float, fixed and private, or null. - complete
- booleanFalse while late routes are still coming. Use the stream to get them.
Stream quotes
No keyThe same query as Get quotes, as server-sent events. A snapshot event carries the whole answer again each time a late route lands, then done carries the final one. Replace what you show with each event; never merge.
curl -N https://api.mindswap.io/v1/quotes/stream \
--get \
-d from=btc:bitcoin \
-d to=eth:ethereum \
-d amountIn=0.1event: snapshot
data: { "routes": [ … ], "mind": { … }, "complete": false }
event: done
data: { "routes": [ … ], "mind": { … }, "complete": true }Create an order
Key optionalTurns a quoted route into an order and returns where the user sends the deposit. Never retried blindly: one Idempotency-Key per swap the user confirms.
Headers
- Idempotency-KeyRequired
- string8 to 64 printable characters, for example a UUID. A retry with the same key and body returns the first answer, never a second order.
- Accept-LanguageOptional
- stringThe end user's language, for example
en-US. MIND float and private routes, and some exchange routes, refuse an order without it. - X-Client-TimezoneOptional
- stringThe end user's IANA time zone, for example
Europe/Berlin. Never a made-up value.
Body
- routeIdRequired
- stringFrom a quote, unchanged. It stops working at the route's
expiresAt. - pickedByRequired
- enum
mindwhen you take MIND's pick, otherwiseuser. - payoutRequired
- address
{ address, memo }. Set memo when the asset needs one, else null. - refundRequired
- address | nullWhere a refund goes. Required for fixed routes; send it for every order.
- refRequired
- string | nullAn affiliate code, up to 20 characters. Send null when you have none.
curl https://api.mindswap.io/v1/orders \
-H "x-api-key: $MINDSWAP_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Accept-Language: en-US" \
-H "X-Client-Timezone: Europe/Berlin" \
-H "content-type: application/json" \
-d @- <<JSON
{
"routeId": "$ROUTE_ID",
"pickedBy": "mind",
"payout": { "address": "$PAYOUT_ADDRESS", "memo": null },
"refund": { "address": "$REFUND_ADDRESS", "memo": null },
"ref": null
}
JSON{
"id": "MS-7HK2PQ",
"type": "fixed",
"status": "awaiting_deposit",
"deposit": {
"address": "bc1q9h7garjv5p2m8u0kq4ksd2d6e0q3t5xw8yz2hf4n",
"memo": null,
"amount": "0.1",
"expiresAt": "2026-11-17T14:30:00Z",
"expiresSource": "provider"
}
}Read an order
Key or capThe order as the user sees it: status, deposit instructions, every step so far and the transactions.
Query
- capOptional
- stringFrom Track an order: read-only access for 24 h. Not needed with the key that created the order.
curl https://api.mindswap.io/v1/orders/$ORDER_ID \
-H "x-api-key: $MINDSWAP_API_KEY"{
"id": "MS-7HK2PQ",
"version": 0,
"type": "fixed",
"status": "awaiting_deposit",
"deposit": { "address": "bc1q9h7g…", "amount": "0.1", … },
"amountOut": "3.5324",
"steps": [{ "status": "awaiting_deposit", "at": "2026-11-17T14:00:00Z" }],
…
}Response
- status
- enum
awaiting_deposit,confirming,exchanging,private_routing,sending,completed,expired,refund_pending,refunded,failed,on_holdorpartially_completed. - deposit
- DepositWhere and how much to send, and until when:
address,memo,amount,expiresAt. - steps
- Step[]Every status the order entered, oldest first.
- version
- integerGoes up by one on every change. Drop any view that is not newer than the one you show.
Order events
Key or capServer-sent events. The first event is the current order and each change sends the whole order again; a heartbeat comes every 15 s, and end closes the stream once the order can no longer change.
Query and headers
- capOptional
- stringFrom Track an order. Not needed with the key that created the order.
- Last-Event-IDOptional
- stringThe
idof the last event you received, sent back unchanged. The stream skips what you already have.
curl -N https://api.mindswap.io/v1/orders/$ORDER_ID/events \
--get \
-d cap=$CAPid: 0.0
data: { "type": "order", "order": { "id": "MS-7HK2PQ", "version": 0, … } }
data: { "type": "heartbeat", "version": 0 }Track an order
No keyOpens any order from any device with its ID and payout address. A missing order and a wrong address both answer 404 not_found.
Body
- orderIdRequired
- stringThe order ID, for example
MS-7HK2PQ. - payoutAddressRequired
- stringThe address the order pays out to, exactly as it was given.
curl https://api.mindswap.io/v1/orders/track \
-H "content-type: application/json" \
-d @- <<JSON
{ "orderId": "$ORDER_ID", "payoutAddress": "$PAYOUT_ADDRESS" }
JSON{
"order": { "id": "MS-7HK2PQ", "status": "awaiting_deposit", … },
"cap": "1795022983.Z4Pq…"
}Response
- order
- OrderViewThe same order as Read an order.
- cap
- string | nullRead-only access for 24 h. Pass it as
?cap=to read the order and its events.
Report a problem
No keyOne flow for every route. Prove the order the same way as tracking: its payout address, a cap, or the key that created it.
Body
- kindRequired
- enum
refund,not_received,wrong_network,wrong_amountorother. - payoutAddressOptional
- stringThe order's payout address, as proof. Leave it out when you send
?cap=or the key. - detailsOptional
- stringWhat happened, in the user's words. Up to 4,000 characters.
- depositTxHashOptional
- stringThe deposit transaction, when the user has it.
- refundAddressOptional
- stringWhere to send a refund, with
refundMemowhen the network needs one.
curl https://api.mindswap.io/v1/orders/$ORDER_ID/issues \
-H "content-type: application/json" \
-d @- <<JSON
{
"kind": "not_received",
"payoutAddress": "$PAYOUT_ADDRESS",
"details": "Sent the deposit two hours ago. Nothing arrived yet."
}
JSON{
"id": "7e33efd4-931e-4272-ada0-8a5261568ca5",
"kind": "not_received",
"state": "received",
"timeline": [{ "at": "2026-11-17T17:23:40Z", "text": "We received your request." }],
"nextUpdateBy": "2026-11-18T05:23:40Z",
"action": null
}Response
- state
- enum
received,in_progress,needs_infoorresolved. - timeline
- object[]What happened so far, in plain words, oldest first.
- nextUpdateBy
- string | nullWhen we answer next at the latest. Null once resolved.
Errors
Every error has the same shape. Branch on code, show message, and quote requestId to support.
Rate limits
Each key has its own budget, and every call also counts against your IP. The first limit you hit answers 429 rate_limited.
Webhooks
CommercialNot live yetSigned POSTs to your endpoint are planned for Commercial keys. Until they launch, follow each order live with GET /v1/orders/{id}/events.
- order.deposit_detected
- order.completed
- order.refunded
Code examples
One swap, from quote to deposit instructions. Run it on your server with MINDSWAP_API_KEY, PAYOUT_ADDRESS and REFUND_ADDRESS set.
const api = 'https://api.mindswap.io/v1'
const headers = { 'x-api-key': process.env.MINDSWAP_API_KEY }
// 1. Quote: MIND's fixed pick for 0.1 BTC to ETH
const quote = await fetch(`${api}/quotes?from=btc:bitcoin&to=eth:ethereum&amountIn=0.1`, { headers })
.then((r) => r.json())
if (!quote.mind.fixed) throw new Error('No fixed route for this pair right now')
// 2. Create, once per confirmation. Keep the key: a retry with it never makes a second order.
const order = await fetch(`${api}/orders`, {
method: 'POST',
headers: { ...headers, 'content-type': 'application/json', 'idempotency-key': crypto.randomUUID() },
body: JSON.stringify({
routeId: quote.mind.fixed,
pickedBy: 'mind',
payout: { address: process.env.PAYOUT_ADDRESS, memo: null },
refund: { address: process.env.REFUND_ADDRESS, memo: null },
ref: null,
}),
}).then((r) => r.json())
if (order.error) throw new Error(`${order.error.code}: ${order.error.message}`)
// 3. Deposit instructions
console.log(`Send ${order.deposit.amount} BTC to ${order.deposit.address}`)