1Install1 of 9
SDK · 0.1.0

TypeScript SDK

A typed client for the API, with safe retries and live order events.

Package
@mindswap/sdk
Not on npm yet
Runs on
Node 22 or newer, on your server

Install

The package is not on npm yet, so there is no install command to run. Until it is published, call the HTTP API directly: every method below maps to one endpoint.

The install command appears here once the package is on npm. Until then, the API reference has every call in cURL, and quotes, orders and the full swap in JavaScript, Python and Go.

Quickstart

Quote a swap, create the order, and show the user where to send funds.

import { MindSwap } from '@mindswap/sdk'

const ms = new MindSwap({
  apiKey: process.env.MINDSWAP_API_KEY!,
})

const quote = await ms.quote({
  from: 'btc:bitcoin',
  to: 'usdt:tron',
  amountIn: '0.01',
})
if (!quote.mind.float) {
  throw new Error('No MIND route right now')
}

const order = await ms.createOrder({
  routeId: quote.mind.float,
  pickedBy: 'mind',
  payout: {
    address: process.env.PAYOUT_ADDRESS!,
  },
  refund: {
    address: process.env.REFUND_ADDRESS!,
  },
})

const { amount, address } = order.deposit
console.log(`Send ${amount} BTC to ${address}`)

Client options

Pass them to new MindSwap(options). All are optional.

apiKey
None
Your msk_live_… key, sent as x-api-key. Needed to read orders by ID.
baseUrl
api.mindswap.io
Where the API lives.
timeoutMs
30 s
How long each request waits for the answer's headers.
maxRetries
2
Automatic retries after a rate limit, a pause or a lost answer.
maxRetryWaitMs
10 s
A longer Retry-After is not waited out: the error is thrown.
endUser
From Intl
The end user's language and time zone. See End user.
fetch
Global fetch
Your own fetch, for proxies or tests.

Methods

Each method calls one endpoint and returns its typed answer.

assets()GET /v1/assets
Every asset, network and venue. Cached with ETag, so a repeat costs one 304.
quote(req)GET /v1/quotes
Answers by a deadline. complete: false means late routes are still coming.
quoteStream(req)GET /v1/quotes/stream
Yields the whole snapshot again each time a late route lands, then done with the final one.
createOrder(input, opts?)POST /v1/orders
Sends one Idempotency-Key and reuses it on every retry, so it never makes two orders.
getOrder(id, { cap? })GET /v1/orders/{id}
Orders your key created, or any order with a cap from trackOrder.
trackOrder(id, payoutAddress)POST /v1/orders/track
Any order. Returns the order and a cap with read-only access for 24 h.
orderEvents(id, opts?)GET /v1/orders/{id}/events
Live updates. A dropped connection resumes from lastEventId.
reportIssue(id, issue, { cap? })POST /v1/orders/{id}/issues
Refund, deposit not received, wrong network or amount. One open issue per order.

Types

Generated from the API's OpenAPI file, so they always match what the API sends. Amounts are decimal strings in whole units, never numbers.

  • AssetCatalog
  • QuoteRequest
  • QuoteSnapshot
  • Route
  • UnavailableRoute
  • CreateOrderInput
  • OrderView
  • OrderStatus
  • Deposit
  • TrackResult
  • OrderEvent
  • ReportIssueBody
  • IssueView
  • ApiErrorCode

Errors

Every failure throws a MindSwapError. Branch on code; four codes have their own class. Messages never contain your key.

create_in_doubt
CreateInDoubtError
Never retry and never send funds. Contact support with the requestId.
quote_moved
QuoteMovedError
No order was made. Show freshRoute; create again with freshRouteId and a new key.
rate_limited
RateLimitedError
The SDK already waited and retried. Wait retryAfterMs, then try again.
pair_unavailable
PairUnavailableError
No provider can swap this pair right now.
timeout
MindSwapError
No answer arrived. Retries reuse the same Idempotency-Key, so no second order.

End user

Some routes are refused unless the create carries the end user's language and time zone. The SDK sends both from its runtime's Intl. A server that creates orders for many users passes each user's own. Never send a made-up value.

const order = await ms.createOrder(input, {
  endUser: { language: 'de-DE', timeZone: 'Europe/Berlin' },
})

Recovering a create

createOrder retries a lost answer with the same Idempotency-Key, so it never makes a second order. If retries run out or your process crashes, only that key finds the order again. For money flows, store the key with the user's intent before you call.

const key = crypto.randomUUID()
await db.saveIntent({ intentId, idempotencyKey: key, routeId, payout }) // persist first
const order = await ms.createOrder(input, { idempotencyKey: key })

// After a crash: call createOrder again with the same input and the stored key.
// The API answers with the original order and never creates a second one.

Use from an agent

Not public yet

Our MCP server wraps this SDK as six tools an agent can call. Every amount names its asset, order answers say what to do next, and create_order takes an intentId so a retry never makes a second order. It is not public yet, so there is no server to connect to today.

  • list_assets
  • get_quote
  • create_order
  • get_order
  • track_order
  • report_issue