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 addressparams
(Record<string, object>): Additional parametersprotocol
(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 responseaddress
(string): User's Bitcoin addresspublicKey
(string): User's public keypaymentAddress
(string): Payment addresspaymentPublicKey
(string): Payment public keyfeeRate
(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 useswapId
(string): Swap ID from PSBT responseaddress
(string): User's Bitcoin addresspublicKey
(string): User's public keypaymentAddress
(string): Payment addresspaymentPublicKey
(string): Payment public keyprotocol
(string): Protocol to usesignedPsbts
(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 addressbtc_address
(string): Bitcoin addressord_public_key
(string): Ordinals public keybtc_public_key
(string): Bitcoin public keyprovider
(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 addressnftAddress
(string): Ordinals addresssign
(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 forsell
(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();
Last updated