1Authentication1 of 13
API reference · v1

MindSwap API

The same API mindswap.io runs on. Amounts are decimal strings, never numbers.

Base URL
https://api.mindswap.io/v1
Key header
x-api-key: msk_live_…

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.

Assets, quotes, tracking, problems
No key. Tracking and problem reports prove the order with its payout address.
Create an order
Optional. Without a key, open the order later with its ID and payout address.
Read an order or its events
The key that created it, or the 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 key
GET/v1/assets

Every 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 key
GET/v1/quotes

Every 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:network in lower case, for example btc: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 routeId to create an order before expiresAt.
mind
objectThe routeId MIND 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 key
GET/v1/quotes/stream

The 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.1
event: snapshot
data: { "routes": [ … ], "mind": { … }, "complete": false }

event: done
data: { "routes": [ … ], "mind": { … }, "complete": true }

Create an order

Key optional
POST/v1/orders

Turns 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
enummind when you take MIND's pick, otherwise user.
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 cap
GET/v1/orders/{id}

The 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
enumawaiting_deposit, confirming, exchanging, private_routing, sending, completed, expired, refund_pending, refunded, failed, on_hold or partially_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 cap
GET/v1/orders/{id}/events

Server-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 id of 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=$CAP
id: 0.0
data: { "type": "order", "order": { "id": "MS-7HK2PQ", "version": 0, … } }

data: { "type": "heartbeat", "version": 0 }

Track an order

No key
POST/v1/orders/track

Opens 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 key
POST/v1/orders/{id}/issues

One 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
enumrefund, not_received, wrong_network, wrong_amount or other.
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 refundMemo when 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
enumreceived, in_progress, needs_info or resolved.
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.

create_in_doubt
502
Never retry and never send funds. Contact support with the requestId.
quote_moved
409
No order was made. Show the fresh route; create with it if the user accepts.
route_expired
410
The quote is too old. Quote again.
address_invalid
422
Ask the user for the address again. Never guess or fix it.
rate_limited
429
Wait retryAfterMs, then call again.

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.

Personal key
300 calls/min
Commercial key
1,200 calls/min
Get quotes
120 a minute per IP
Create an order
20 a minute per IP
Track an order
30 a minute per IP
Per order: 10 at once, then 1 every 6 min

Webhooks

CommercialNot live yet

Signed 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}`)