> For the complete documentation index, see [llms.txt](https://satsterminal.gitbook.io/sats-terminal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://satsterminal.gitbook.io/sats-terminal/swap-sdk/editor/api-reference.md).

# API Reference

## Methods

### swapQuote

***

Get a quote for swapping tokens with simplified parameters.

```typescript
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:**

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

**Example Response:**

```typescript
{
  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.

```typescript
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:**

```typescript
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:**

```typescript
{
  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.

```typescript
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:**

```typescript
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:**

```typescript
{
  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.

```javascript
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:**

```javascript
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.

```javascript
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:**

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

### **points**

***

Get the user's accumulated Amber points balance.

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

**Parameters:**

* `ord_address` (string): Ordinals address

**Example:**

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

### **search**

***

Search for runes by name.

```javascript
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:**

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

### **popularCollections**

***

Fetch popular rune collections.

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

**Example:**

```javascript
const collections = await satsTerminal.popularCollections();
```