v1OpenAPI 3.1.0

MakeSwap Swap API

Headless and iframe-widget surface for token discovery, quotes, deposit channels, swap execution, and status tracking.

This is the MakeSwap headless and widget surface. Use the SDK or direct HTTP routes to discover supported tokens, quote routes, start swaps, and track progress across deposit, swap, outbound, completed, and failed phases.

Browser requests should use a short-lived integration token. Keep MakeSwap key secrets on your backend and exchange them for tokens before mounting an iframe or running headless requests.

Server
https://www.makeswap.io/api/v1
Authentication
Browser/widget calls use x-makeswap-integration-token and x-makeswap-session-id. Token issuance uses x-makeswap-key-id and x-makeswap-key-secret on the backend.Integration token
Client Libraries
@makeswap/sdkIframe widgetWeb component

Authentication

Browser/widget calls use x-makeswap-integration-token and x-makeswap-session-id. Token issuance uses x-makeswap-key-id and x-makeswap-key-secret on the backend.

Headers
x-makeswap-integration-tokenMAKESWAP_INTEGRATION_TOKEN
x-makeswap-session-idms_session_123
x-makeswap-key-idMAKESWAP_KEY_ID
x-makeswap-key-secretMAKESWAP_KEY_SECRET

Widget events

Embedded widgets communicate with the host page through postMessage events. Listen for makeswap.ready, makeswap.quote.updated, makeswap.swap.started, makeswap.swap.status, and makeswap.error to update host UI, resize containers, or persist swap status.

Operation reference

Endpoints

7 endpointsShell examplesJSON schemas

List tokens

Returns supported swap assets with chain, symbol, identifier, decimals, and logo metadata. Use this before building a quote form or widget prefill.

Body

noneapplication/json
This request does not require a JSON body.

Responses

application/json

The request completed successfully.

Response

tokensarray Object[]required
GET/api/v1/tokens
curl "https://www.makeswap.io/api/v1/tokens" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123"
Successful response
{
  "tokens": [
    {
      "chain": "Bitcoin",
      "chainId": "BTC",
      "ticker": "BTC",
      "identifier": "BTC.BTC",
      "symbol": "BTC",
      "name": "Bitcoin",
      "decimals": 8
    }
  ]
}
Successful response

List providers

Returns swap providers available to the current integration context. Use provider filters when you need to force or hide specific liquidity routes.

Body

noneapplication/json
This request does not require a JSON body.

Responses

application/json

The request completed successfully.

Response

providersarray string[]required[ "CHAINFLIP", "THORCHAIN", "NEAR_INTENTS" ]
GET/api/v1/providers
curl "https://www.makeswap.io/api/v1/providers" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123"
Successful response
{
  "providers": [
    "CHAINFLIP",
    "THORCHAIN",
    "NEAR_INTENTS"
  ]
}
Successful response

Create quote

Quotes one or more swap routes for a source asset, destination asset, amount, optional addresses, slippage, and provider filters.

Body

requiredapplication/json

Request

sellAssetstringrequiredBTC.BTC
buyAssetstringrequiredETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
sellAmountstringrequired0.01
sourceAddressstringrequiredbc1qsource...
destinationAddressstringrequired0xdestination...
slippageintegerrequired1
includeTxbooleanrequiredfalse
disableBalanceCheckbooleanrequiredtrue

Responses

application/json

The request completed successfully.

Response

routesarray Object[]required
POST/api/v1/quote
curl -X POST "https://www.makeswap.io/api/v1/quote" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123" \
  -d '{
  "sellAsset": "BTC.BTC",
  "buyAsset": "ETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "sellAmount": "0.01",
  "sourceAddress": "bc1qsource...",
  "destinationAddress": "0xdestination...",
  "slippage": 1,
  "includeTx": false,
  "disableBalanceCheck": true
}'
Successful response
{
  "routes": [
    {
      "routeId": "route-CHAINFLIP-0",
      "providers": [
        "CHAINFLIP"
      ],
      "sellAsset": "BTC.BTC",
      "sellAmount": "0.01",
      "buyAsset": "ETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "expectedBuyAmount": "620.12",
      "fees": [
        {
          "type": "network",
          "amount": "0.00002",
          "asset": "BTC.BTC"
        }
      ],
      "estimatedTime": {
        "total": 900
      }
    }
  ]
}
Successful response

Create deposit channel

Creates a Chainflip-style deposit channel for a quoted route and returns the address or channel identifiers that the payer should fund.

Body

requiredapplication/json

Request

routeIdstringrequiredroute-CHAINFLIP-0
sourceAddressstringrequiredbc1qsource...
destinationAddressstringrequired0xdestination...
chainflipMetaObjectrequired

Responses

application/json

The request completed successfully.

Response

depositAddressstringrequiredbc1qdeposit...
channelIdstringrequired210-Bitcoin-12345
depositChannelIdstringrequired12345
providerstringrequiredCHAINFLIP
POST/api/v1/channel
curl -X POST "https://www.makeswap.io/api/v1/channel" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123" \
  -d '{
  "routeId": "route-CHAINFLIP-0",
  "sourceAddress": "bc1qsource...",
  "destinationAddress": "0xdestination...",
  "chainflipMeta": {
    "sourceChain": "Bitcoin"
  }
}'
Successful response
{
  "depositAddress": "bc1qdeposit...",
  "channelId": "210-Bitcoin-12345",
  "depositChannelId": "12345",
  "provider": "CHAINFLIP"
}
Successful response

Start swap

Builds or starts a swap execution from the selected route, source address, destination address, amount, slippage, and provider preferences.

Body

requiredapplication/json

Request

routeIdstringrequiredroute-CHAINFLIP-0
sourceAddressstringrequiredbc1qsource...
destinationAddressstringrequired0xdestination...
sellAssetstringrequiredBTC.BTC
buyAssetstringrequiredETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
sellAmountstringrequired0.01
slippageintegerrequired1
includeRoutebooleanrequiredtrue

Responses

application/json

The request completed successfully.

Response

swapIdstringrequiredswap_01j...
depositAddressstringrequiredbc1qdeposit...
statusstringrequiredwaiting_deposit
routeIdstringrequiredroute-CHAINFLIP-0
POST/api/v1/swap
curl -X POST "https://www.makeswap.io/api/v1/swap" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123" \
  -d '{
  "routeId": "route-CHAINFLIP-0",
  "sourceAddress": "bc1qsource...",
  "destinationAddress": "0xdestination...",
  "sellAsset": "BTC.BTC",
  "buyAsset": "ETH.USDC-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "sellAmount": "0.01",
  "slippage": 1,
  "includeRoute": true
}'
Successful response
{
  "swapId": "swap_01j...",
  "depositAddress": "bc1qdeposit...",
  "status": "waiting_deposit",
  "routeId": "route-CHAINFLIP-0"
}
Successful response

Track swap

Tracks swap progress by transaction hash and chain, deposit channel id, swap id, or deposit address. Responses normalize phases into deposit, swapping, sending, complete, and failed states.

Body

requiredapplication/json

Request

hashstringrequired0xsource_tx_hash
chainIdstringrequiredETH
depositChannelIdstringrequired12345
depositAddressstringrequiredbc1qdeposit...

Responses

application/json

The request completed successfully.

Response

trackingStatusstringrequiredswapping
statusstringrequiredpending
legsarray Object[]required
POST/api/v1/track
curl -X POST "https://www.makeswap.io/api/v1/track" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-integration-token: MAKESWAP_INTEGRATION_TOKEN" \
  -H "x-makeswap-session-id: ms_session_123" \
  -d '{
  "hash": "0xsource_tx_hash",
  "chainId": "ETH",
  "depositChannelId": "12345",
  "depositAddress": "bc1qdeposit..."
}'
Successful response
{
  "trackingStatus": "swapping",
  "status": "pending",
  "legs": [
    {
      "type": "native_send",
      "hash": "0xsource_tx_hash",
      "status": "confirmed"
    },
    {
      "type": "swap",
      "trackingStatus": "swapping"
    }
  ]
}
Successful response

Issue integration token

Exchanges a MakeSwap key ID and secret for a browser-safe integration token bound to an origin, optional affiliate address, affiliate fee, and branding.

Body

requiredapplication/json

Request

originstringrequiredhttps://merchant.example
affiliateAddressstringrequired0xaffiliate...
affiliateFeeBpsintegerrequired25
brandingObjectrequired

Responses

application/json

The request completed successfully.

Response

tokenstringrequiredmsit_...
expiresAtstringrequired2026-04-19T12:00:00.000Z
originstringrequiredhttps://merchant.example
POST/api/v1/integrations/token
curl -X POST "https://www.makeswap.io/api/v1/integrations/token" \
  -H "Content-Type: application/json" \
  -H "x-makeswap-key-id: MAKESWAP_KEY_ID" \
  -H "x-makeswap-key-secret: MAKESWAP_KEY_SECRET" \
  -d '{
  "origin": "https://merchant.example",
  "affiliateAddress": "0xaffiliate...",
  "affiliateFeeBps": 25,
  "branding": {
    "name": "Merchant Co",
    "primaryColor": "#0f766e"
  }
}'
Successful response
{
  "token": "msit_...",
  "expiresAt": "2026-04-19T12:00:00.000Z",
  "origin": "https://merchant.example"
}
Successful response

SDK

Use @makeswap/sdk

The SDK wraps token discovery, quote, swap, tracking, and iframe lifecycle behavior while preserving the same HTTP routes shown above.

Node.js
import { createMakeSwapClient } from "@makeswap/sdk";

const client = createMakeSwapClient({
  baseUrl: "https://www.makeswap.io",
  integrationToken: process.env.MAKESWAP_INTEGRATION_TOKEN,
});

const quote = await client.quote({
  sellAsset: "BTC.BTC",
  buyAsset: "ETH.ETH",
  sellAmount: "0.01",
});