Skip to main content

​
V2 (recommended)

​
swapQuote(params: SwapV2QuoteParams)

Get a quote with normalized token direction.
ParamTypeNotes
amountstringAmount in fromToken units
fromTokenstringe.g., BTC
toTokenstringe.g., USDC, GOLD DUST
addressstringUser BTC address
protocolstringrunes, alkanes, …
paramsRecord<string, any>Protocol-specific extras
marketplaces?string[]Optional allowlist
const quote = await swaps.swapQuote({
  amount: "0.00008",
  fromToken: "BTC",
  toToken: "GOLD DUST",
  address: "bc1p...",
  params: {},
  protocol: "alkanes",
});

// quote.bestMarketplace, quote.swapId, quote.metrics, quote.marketplaces
Response highlights
  • bestMarketplace: string
  • swapId: string
  • fromTokenAmount / toTokenAmount: strings
  • metrics: per-marketplace fulfillment and pricing
  • marketplaces: per-marketplace amounts + swapIds

​
swapPSBT(params: SwapV2PSBTParams)

Create PSBT(s) for the swap; returns an array because some swaps need multiple signatures.
ParamTypeNotes
marketplacestringFrom the quote
swapIdstringFrom the quote/previous step
addressstringUser BTC address
publicKeystringBTC pubkey matching address
paymentAddressstringChange/receive address
paymentPublicKeystringPubkey for paymentAddress
feeRatenumbersats/vByte
slippagenumberpercent
protocolstringe.g., runes
themeID?string | nullOptional widget theme
const psbt = await swaps.swapPSBT({
  marketplace: quote.bestMarketplace,
  swapId: quote.swapId,
  address: "bc1p...",
  publicKey: "...",
  paymentAddress: "...",
  paymentPublicKey: "...",
  feeRate: 3,
  slippage: 9,
  themeID: null,
  protocol: "alkanes",
});

// psbt.psbts: [{ base64, hex, inputs }]

​
swapSubmit(params: SwapV2SubmitParams)

Submit signed PSBTs to complete the swap.
ParamTypeNotes
marketplacestringFrom quote/PSBT
swapIdstringFrom PSBT step
addressstringUser BTC address
publicKeystringBTC pubkey
paymentAddressstringChange/receive address
paymentPublicKeystringPubkey for change
protocolstringe.g., runes
signedPsbtsstring[]Signed PSBT hex strings
const result = await swaps.swapSubmit({
  marketplace: quote.bestMarketplace,
  swapId: psbt.swapId,
  address: "bc1p...",
  publicKey: "...",
  paymentAddress: "...",
  paymentPublicKey: "...",
  protocol: "runes",
  signedPsbts: psbt.psbts.map(({ hex }) => sign(hex)),
});
Response highlights
  • txid: string
  • marketplace: string
  • rbfProtection?: { fundsPreparationTxId, fulfillmentId }
  • isRbfTxid: boolean

​
V1 (legacy rune trading)

These methods stay for existing integrations and RBF flows.
  • signIn({ ord_address, btc_address, ord_public_key, btc_public_key, provider })
  • bind({ btcAddress, nftAddress, sign })
  • points({ ord_address })
  • popularCollections()
  • search({ rune_name, sell? })
  • fetchQuote({ btcAmount, runeName, address, marketplaces?, themeID?, sell?, rbfProtection?, fill? })
  • getPSBT({ orders, address, publicKey, paymentAddress, paymentPublicKey, runeName, utxos?, feeRate?, slippage?, themeID?, sell?, rbfProtection? })
  • confirmPSBT({ orders, address, publicKey, paymentAddress, paymentPublicKey, signedPsbtBase64, signedRbfPsbtBase64?, swapId, runeName, sell?, marketplaces?, rbfProtection? })

​
V1 flow (short)

const quote = await swaps.fetchQuote({
  btcAmount: 0.0001,
  runeName: "LOBO•THE•WOLF•PUP",
  address: "bc1p...",
  marketplaces: ["MagicEden"],
  rbfProtection: true,
});

const psbt = await swaps.getPSBT({
  orders: quote.selectedOrders,
  address: "bc1p...",
  publicKey: "...",
  paymentAddress: "3Pc...",
  paymentPublicKey: "...",
  runeName: "LOBO•THE•WOLF•PUP",
  feeRate: 5,
  slippage: 9,
  rbfProtection: true,
});

const confirmation = await swaps.confirmPSBT({
  orders: quote.selectedOrders,
  address: "bc1p...",
  publicKey: "...",
  paymentAddress: "3Pc...",
  paymentPublicKey: "...",
  signedPsbtBase64: "<signed-psbt>",
  signedRbfPsbtBase64: psbt.rbfProtected?.base64 ? "<signed-rbf-psbt>" : undefined,
  swapId: psbt.swapId,
  runeName: "LOBO•THE•WOLF•PUP",
  rbfProtection: true,
});

​
Errors

All methods throw descriptive errors. Wrap calls in try/catch and surface useful hints (slippage, insufficient balance, marketplace unsupported, swap expired). For network issues, check connectivity and API key validity.