Skip to main content

​
Swaps at a glance

  • V2 (recommended): Simplified swapQuote → swapPSBT → swapSubmit flow with automatic marketplace selection and cleaner parameters. Supports multiple PSBTs per swap and protocols like runes and alkanes.
  • V1 (legacy): Granular rune trading with manual order handling (fetchQuote → getPSBT → confirmPSBT) and optional RBF protection. Kept for backwards compatibility.
  • Packages: Use the standalone @satsterminal-sdk/swaps or the suite satsterminal-sdk (exports the same SatsTerminal client).

​
Install

npm install @satsterminal-sdk/swaps
# or
npm install satsterminal-sdk

​
Choose your flow

Use caseGo withWhy
New integrations, fastest pathV23 calls, normalized data, auto marketplace routing
RBF protection or legacy rune flowsV1Explicit marketplace control and single-PSBT handling
Multiple products (swaps + borrow)AggregatorOne createClient call yields both clients

​
Protocols and tokens

  • protocol: runes for rune trading, alkanes for alkanes tokens, more coming.
  • fromToken/toToken: clear directionality (e.g., BTC → USDC or DOG•GO•TO•THE•MOON → BTC).
  • Marketplaces are selected automatically for V2; pass marketplace when creating PSBTs or submitting.

​
Quick V2 shape

const quote = await swaps.swapQuote({ amount, fromToken, toToken, address, protocol, params: {} });
const psbt = await swaps.swapPSBT({ ...quote, address, publicKey, paymentAddress, paymentPublicKey, feeRate, slippage, protocol });
const result = await swaps.swapSubmit({ ...psbt, address, publicKey, paymentAddress, paymentPublicKey, protocol, signedPsbts });

​
What changed from V1

  • Direction is expressed via fromToken/toToken instead of sell.
  • Multiple PSBTs per swap (array) vs single PSBT.
  • Automatic order management; you only sign and submit.
  • Consistent response shapes and marketplace metrics.
See the detailed API and examples:
  • API reference: swaps/api
  • Quickstart: swaps/quickstart
  • Examples: swaps/examples