API Reference

Methods

swapQuote

---

Get a quote for swapping tokens with simplified parameters.

async swapQuote(params: SwapV2QuoteParams): Promise<SwapV2QuoteResponse>

Parameters:

• amount (string): Amount to swap (e.g., "0.00008")

• fromToken (string): Source token (e.g., "BTC")

• toToken (string): Destination token (e.g., "GOLD DUST")

• address (string): User's Bitcoin address

• params (Record<string, object>): Additional parameters

• protocol (string): Protocol to use (e.g., "alkanes", "runes")

• marketplaces (list): Marketplaces to include (e.g. ["MagicEden", "Dotswap])

Example:

const quote = await satsTerminal.swapQuote({
  amount: "0.00008",
  fromToken: "BTC",
  toToken: "GOLD DUST",
  address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj",
  params: {},
  protocol: "alkanes"
});

Example Response:

{
  bestMarketplace: "IdClub",
  swapId: "st-mdyr4s5y-14277fae41249423",
  fromTokenAmount: "0.00007946",
  toTokenAmount: "1843.84645",
  metrics: {
    idclub: {
      percentFulfilled: "99.33",
      totalPurchased: "1843.84645000",
      percentDifference: "0.00",
      averageUnitPrice: "0.00000004"
    },
    unisat: {
      percentFulfilled: "94.27",
      totalPurchased: "1257.00300000",
      percentDifference: "-31.83",
      averageUnitPrice: "0.00000006"
    }
  },
  marketplaces: {
    Unisat: {
      fromTokenAmount: "0.00007542",
      toTokenAmount: "1257.003",
      swapId: "st-mdyr4rd9-653eb38defef8af2"
    },
    IdClub: {
      fromTokenAmount: "0.00007946",
      toTokenAmount: "1843.84645",
      swapId: "st-mdyr4s5y-14277fae41249423"
    }
  }
}

swapPSBT

---

Get PSBT (Partially Signed Bitcoin Transaction) for the swap.

async swapPSBT(params: SwapV2PSBTParams): Promise<SwapV2PSBTResponse>

Parameters:

• marketplace (string): Marketplace to use (e.g., "Unisat", "IdClub")

• swapId (string): Swap ID from quote response

• address (string): User's Bitcoin address

• publicKey (string): User's public key

• paymentAddress (string): Payment address

• paymentPublicKey (string): Payment public key

• feeRate (number): Fee rate (e.g., 3)

• slippage (number): Slippage tolerance (e.g., 9)

• themeID? (string | null): Theme ID (optional)

• protocol (string): Protocol to use

Example:

const psbt = await satsTerminal.swapPSBT({
  marketplace: "Unisat",
  swapId: "st-mdyr4rd9-653eb38defef8af2",
  address: "bc1p4mffk7l9a040dgqrl8spunwkguxn68ldwx848urafar9sj85nnrq9rcvyj",
  publicKey: "03962e74f53d3620f82aab9ecfadbaa2d2b34ab1d794b346f53deb4c1a9d287bfc",
  paymentAddress: "bc1qjtyqu4uqrpnvsfg9tq0wzzsdge3e559wzk4epc",
  paymentPublicKey: "02325fb34ee9ff76df92b34d13059fa8d14008a9426fb1de52f038bfdca5075588",
  feeRate: 3,
  slippage: 9,
  themeID: null,
  protocol: "alkanes"
});

Example Response:

{
  psbts: [
    {
      base64: "cHNidP8BAP0WAQIAAAACxmLniE724xFErO3qK9jgKBkkVwz5dlTLTvdIVNw5JgMBAAAAAP////9CpNjLkmww5ugi0C91HbKTs5Sp9Ts+/fiobxMdIavsKgAAAAAA/////wVKAQAAAAAAACJRIPlmr/3KwxxsRAYxpoi+7UIK9UWARgEX5wKBAtW2LVMySgEAAAAAAAAiUSDhuqw5iXV8zvWrr9JnI/UX5lyEC0wBEnsf8wdHMT0gtQAAAAAAAAAAEGpdDQCp5zSmH7Oooon6AQGIEwAAAAAAACJRIMAdzzCKtujgeRdBvtozpwBAapRiHrmh7iK8lfPqe8HgTNQAAAAAAAAXqRTwcmaf/igf0hSlNZd3ss2y7lyJpYcAAAAAAAEA9gIAAAAAAQHjnkbASwGvRKDU+UFwaZ3QH5empgLm8vOYZ3wAFuOvzQEAAAAXFgAUY9wnP/vXXCJ9d3tDwzvzOL1cNV/9////AhAnAAAAAAAAFgAUksgOV4AYZsglBVge4QoNRmOaUK4t7QAAAAAAABepFPByZp/+KB/SFKU1l3eyzbLuXImlhwJHMEQCIBD6SFKCQKyb1Qv5hx6bHE8n6jpuzMWioSsoLtje7PtuAiA5WWCEEabkHchSVY7I6AachBHXIvDlCEVYaZjM8oRwXAEhAq9tcSQzhuOiSiPr9H6pHc8NEUuOwpFj7ZcW6bFKj+PYAAAAAAEDBAEAAAABBBYAFGPcJz/711wifXd7Q8M78zi9XDVfAAEBK0oBAAAAAAAAIlEg+Wav/crDHGxEBjGmiL7tQgr1RYBGARfnAoEC1bYtUzIBAwQBAAAAAAAAAAAA",
      hex: "70736274ff0100fd16010200000002c662e7884ef6e31144acedea2bd8e0281924570cf97654cb4ef74854dc3926030100000000ffffffff42a4d8cb926c30e6e822d02f751db293b394a9f53b3efdf8a86f131d21abec2a0000000000ffffffff054a01000000000000225120f966affdcac31c6c440631a688beed420af54580460117e7028102d5b62d53324a01000000000000225120e1baac3989757ccef5abafd26723f517e65c840b4c01127b1ff30747313d20b50000000000000000106a5d0d00a9e734a61fb3a8a289fa01018813000000000000225120c01dcf308ab6e8e0791741beda33a700406a94621eb9a1ee22bc95f3ea7bc1e04cd400000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a58700000000000100f602000000000101e39e46c04b01af44a0d4f94170699dd01f97a6a602e6f2f398677c0016e3afcd010000001716001463dc273ffbd75c227d777b43c33bf338bd5c355ffdffffff02102700000000000016001492c80e57801866c82505581ee10a0d46639a50ae2ded00000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a58702473044022010fa48528240ac9bd50bf9871e9b1c4f27ea3a6eccc5a2a12b282ed8deecfb6e02203959608411a6e41dc852558ec8e8069c8411d722f0e50845586998ccf284705c012102af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d80000000001030401000000010416001463dc273ffbd75c227d777b43c33bf338bd5c355f0001012b4a01000000000000225120f966affdcac31c6c440631a688beed420af54580460117e7028102d5b62d533201030401000000000000000000",
      inputs: [0]
    }
  ],
  swapId: "st-mdyrtdw5-cfbcc46b313f348a"
}

swapSubmit

Submit signed PSBT to complete the swap.

async swapSubmit(params: SwapV2SubmitParams): Promise<SwapV2SubmitResponse>

Parameters:

• marketplace (string): Marketplace to use

• swapId (string): Swap ID from PSBT response

• address (string): User's Bitcoin address

• publicKey (string): User's public key

• paymentAddress (string): Payment address

• paymentPublicKey (string): Payment public key

• protocol (string): Protocol to use

• signedPsbts (string[]): Array of signed PSBT hex strings

Example:

const result = await satsTerminal.swapSubmit({
  marketplace: "Seekermint",
  swapId: "st-mdonupt8-897950607c0ef3d2",
  address: "bc1puxa2cwvfw47vaadt4lfxwgl4zln9epqtfsq3y7cl7vr5wvfayz6s22mmwp",
  publicKey: "dd4c950d7a5f86e92235687cffeee1bfb61b5c8a9e15b80751077c3d4315821c",
  paymentAddress: "3PcP9J6C9ZNQpTRHrtqFBhP3LoBjSmMkZq",
  paymentPublicKey: "02af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d8",
  protocol: "runes",
  signedPsbts: ["70736274ff0100fd030102000000021673b1a059f118d75c27a4c11ef366c137d7a0b77e141d6202b6abb348d84e120400000000ffffffff9e4d7db2d381db866caed76a53b0318a747fd3e83f7d3e8f796efcffab69bad50100000000ffffffff050000000000000000156a5d1200c0a2330388ffc358010000f0ec959636022202000000000000225120e1baac3989757ccef5abafd26723f517e65c840b4c01127b1ff30747313d20b522020000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5b88130000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5bb6ff01000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a5870000000000010120981902000000000017a914f072669ffe281fd214a5359777b2cdb2ee5c89a587220202af6d71243386e3a24a23ebf47ea91dcf0d114b8ec29163ed9716e9b14a8fe3d84730440220257cd5c3dc7a1d66d76ac8b23479cdd9a1cacfd48f6e29b8e4a48b84c75df182022047885e889da1f0685796269c2694ec8d541a315fdc46258b22e7d9e04ae347190101030401000000010416001463dc273ffbd75c227d777b43c33bf338bd5c355f0001011f22020000000000001600142d0e4a3334c4ba29e9304831343ef6e6b9927a5b01030401000000000000000000"]
});

Example Response:

{
  marketplace: "Seekermint",
  txid: "abc123def456789...",
  rbfProtection: {
    fundsPreparationTxId: "prep_tx_123",
    fulfillmentId: "fulfill_456"
  },
  isRbfTxid: false,
  error: undefined
}

signIn

---

Register and authenticate a user with their Bitcoin and Ordinals addresses.

async signIn(params: SignInParams): Promise<SignInResponse>

Parameters:

• ord_address (string): Ordinals address

• btc_address (string): Bitcoin address

• ord_public_key (string): Ordinals public key

• btc_public_key (string): Bitcoin public key

• provider (string): Wallet provider (e.g., 'xverse', 'unisat')

Example:

const signIn = await satsTerminal.signIn({
  ord_address: "bc1...",
  btc_address: "3Pc...",
  ord_public_key: "...",
  btc_public_key: "...",
  provider: "xverse"
});

bind

---

Bind a user's wallet to Unisat and DotSwap. This is required only once before performing transactions.

async bind(params: BindParams): Promise<BindResponse>

Parameters:

• btcAddress (string): Bitcoin address

• nftAddress (string): Ordinals address

• sign (string): User's signature of the bind message

Example:

const bind = await satsTerminal.bind({
  btcAddress: "3Pc...",
  nftAddress: "bc1...",
  sign: "user_signature_here"
});

points

---

Get the user's accumulated Amber points balance.

async points(params: PointsParams): Promise<PointsResponse>

Parameters:

• ord_address (string): Ordinals address

Example:

const points = await satsTerminal.points({
  ord_address: "bc1..."
});

search

---

Search for runes by name.

async search(params: SearchParams): Promise<SearchResponse>

Parameters:

• rune_name (string): The name of the rune to search for

• sell (boolean, optional): Whether to search for sell orders

Example:

const result = await satsTerminal.search({
  rune_name: 'LOBO•THE•WOLF•PUP',
  sell: false
});

popularCollections

---

Fetch popular rune collections.

async popularCollections(params: PopularCollectionsParams): Promise<PopularCollectionsResponse>

Example:

const collections = await satsTerminal.popularCollections();