# 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();
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://satsterminal.gitbook.io/sats-terminal/swap-sdk/editor/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.