Sats Connect

https://docs.xverse.app/sats-connect/
Admin
Sats Connect is a JavaScript library that connects applications to Bitcoin, Spark, Starknet, Stacks,...
Tokens:91,030
Snippets:583
Trust Score:5.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Sats Connect

Source: https://docs.xverse.app/sats-connect/sats-connect.md

Install the Sats Connect library using npm. Ensure you are using version 4.2.x.

```sh
npm install sats-connect@4.2.x
```

--------------------------------

### Querying Documentation with GET Request

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/runes_getorder.md

Perform an HTTP GET request to query the documentation. Append the 'ask' query parameter with your specific question in natural language.

```bash
GET https://docs.xverse.app/sats-connect/bitcoin-methods/runes_getorder.md?ask=<question>
```

--------------------------------

### Install bitcoinjs-message

Source: https://docs.xverse.app/sats-connect/guides/verify-bitcoin-message-signatures.md

Install the bitcoinjs-message library using npm. This is the first step before verifying messages in a JavaScript or Node.js environment.

```bash
npm install bitcoinjs-message
```

--------------------------------

### Wallet Connect Response Example

Source: https://docs.xverse.app/sats-connect/connecting-to-the-wallet/connect-to-xverse-wallet.md

This is an example of the response object received after a successful wallet connection. It includes wallet type, connection ID, and a list of user addresses with their associated details.

```typescript
const response = {
  walletType: 'software',
  id: 'dj0f7g5xtdakgecvf45dvssu66',
  addressses: [
    {
      address: 'tb1pzwa68q3udj0f7g5xtdakgecvf45dvssu66ry7y3at22w7vus20vq3sgw62',
      publicKey: 'b9907521ddb85e0e6a37622b7c685efbdc8ae53a334928adbd12cf204ad4e717',
      purpose: 'ordinals',
      addressType: 'p2tr',
      network: 'mainnet'
    },
    {
      address: '2NBfRKCUpafbatj5gV9T82uau3igdSf9BXJ',
      publicKey: '02818b7ff740a40f311d002123087053d5d9e0e1546674aedb10e15a5b57fd3985',
      purpose: 'payment',
      addressType: 'p2sh',
      network: 'mainnet'
    },
  ],
  network: {
    bitcoin: {
      name: 'Mainnet',
    },
    stacks: {
      name: 'Mainnet',
    },
  },
};
```

--------------------------------

### Querying Documentation

Source: https://docs.xverse.app/sats-connect/connecting-to-the-wallet/connect-to-xverse-wallet.md

To get more information not present on the current page, you can query the documentation dynamically. Perform an HTTP GET request to the page URL with the 'ask' query parameter.

```bash
GET https://docs.xverse.app/sats-connect/connecting-to-the-wallet/connect-to-xverse-wallet.md?ask=<question>
```

--------------------------------

### Querying Documentation with GET Request

Source: https://docs.xverse.app/sats-connect/stacks-methods/stx_callcontract.md

Use this method to ask questions about the documentation. The response includes a direct answer and relevant excerpts.

```bash
GET https://docs.xverse.app/sats-connect/stacks-methods/stx_callcontract.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes/runes_estimatemint.md

Perform an HTTP GET request to query the documentation dynamically. Include your specific question in the 'ask' query parameter. The response will provide a direct answer and relevant excerpts.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes/runes_estimatemint.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_executerouteswap.md

To get more information not directly available on the page, make an HTTP GET request to the current page URL with the 'ask' query parameter. The question should be specific and self-contained.

```bash
GET https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_executerouteswap.md?ask=<question>
```

--------------------------------

### Querying Documentation Dynamically

Source: https://docs.xverse.app/sats-connect/spark-methods

To get more information not directly on a page, make an HTTP GET request to the page URL with an 'ask' query parameter. The question should be specific and in natural language.

```HTTP
GET https://docs.xverse.app/sats-connect/spark-methods.md?ask=<question>
```

--------------------------------

### Wallet getAccount Response Example

Source: https://docs.xverse.app/sats-connect/wallet-methods/wallet_getaccount.md

This is an example of the successful response from the wallet_getAccount method when a user's active Xverse account is connected and has granted the necessary permissions. It includes the wallet type, account ID, and a list of addresses with their public keys, purposes, and types.

```typescript
{
  walletType: "software",
  id: "dj0f7g5xtdakgecvf45dvssu66",
  addressses: [
    {
      address: "tb1pzwa68q3udj0f7g5xtdakgecvf45dvssu66ry7y3at22w7vus20vq3sgw62",
      publicKey: "b9907521ddb85e0e6a37622b7c685efbdc8ae53a334928adbd12cf204ad4e717",
      purpose: "ordinals",
      addressType: "p2tr",
      network: 'mainnet'
    },
    {
      address: "2NBfRKCUpafbatj5gV9T82uau3igdSf9BXJ",
      publicKey: "02818b7ff740a40f311d002123087053d5d9e0e1546674aedb10e15a5b57fd3985",
      purpose: "payment",
      addressType: "p2sh",
      network: 'mainnet'
    }
  ]
}
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.xverse.app/sats-connect/xverse-wallet-permissions.md

To get more information not directly on this page, make an HTTP GET request to the current page URL with the `ask` query parameter. The question should be specific and in natural language.

```http
GET https://docs.xverse.app/sats-connect/xverse-wallet-permissions.md?ask=<question>
```

--------------------------------

### Query Documentation with GET Request

Source: https://docs.xverse.app/sats-connect/wallet-methods/request-methods.md

Use this method to ask specific questions about the documentation. The response includes a direct answer, excerpts, and sources.

```http
GET https://docs.xverse.app/sats-connect/wallet-methods/request-methods.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/ord_getinscriptions.md

Perform an HTTP GET request on the current page URL with the 'ask' query parameter to dynamically query the documentation. The question should be specific and in natural language.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/ord_getinscriptions.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/getaddresses.md

Use this method to ask questions about the documentation dynamically. The response includes a direct answer and relevant excerpts.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/getaddresses.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/etch-runes.md

To get information not directly on the page, send an HTTP GET request to the page URL with the 'ask' query parameter. The response includes a direct answer and relevant excerpts.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/etch-runes.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://docs.xverse.app/sats-connect/guides

To get specific information not readily available on the page, make an HTTP GET request to the page URL with an 'ask' query parameter. The question should be clear and self-contained.

```HTTP
GET https://docs.xverse.app/sats-connect/guides.md?ask=<question>
```

--------------------------------

### Querying Documentation

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes.md

You can query this documentation dynamically by asking a question via an HTTP GET request. The question should be specific and self-contained.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/wallet-providers/getproviders-and-getproviderbyid.md

Use this method to ask specific questions about the documentation. The response includes direct answers and relevant excerpts.

```http
GET https://docs.xverse.app/sats-connect/wallet-providers/getproviders-and-getproviderbyid.md?ask=<question>
```

--------------------------------

### Query Documentation API

Source: https://docs.xverse.app/sats-connect/guides/mobile-integration.md

Perform an HTTP GET request to query the documentation dynamically. Replace <question> with your specific query.

```http
GET https://docs.xverse.app/sats-connect/guides/mobile-integration.md?ask=<question>
```

--------------------------------

### Querying Documentation with `ask` Parameter

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes/runes_mint.md

To get more information not directly available on the page, perform an HTTP GET request to the current page URL with the `ask` query parameter. The question should be specific and in natural language.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/mint-runes/runes_mint.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/bitcoin-methods/speed-up-a-rune-mint-or-etch-order/runes_estimaterbforder.md

Use this method to ask questions about the documentation when the answer is not explicitly present. The question should be specific and self-contained.

```http
GET https://docs.xverse.app/sats-connect/bitcoin-methods/speed-up-a-rune-mint-or-etch-order/runes_estimaterbforder.md?ask=<question>
```

--------------------------------

### Full Success Response Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_addliquidity.md

This JSON structure represents a successful liquidity provision where the full requested amount was accepted.

```json
{
  "accepted": true,
  "assetAAmountUsed": "100000000",
  "assetBAmountUsed": "50000",
  "lpTokensMinted": "12340000",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}
```

--------------------------------

### Example getNetwork Result

Source: https://docs.xverse.app/sats-connect/wallet-methods/wallet_getnetwork.md

The response object from `wallet_getNetwork` provides network information for each supported chain, indicating the active network name.

```json
{
  "bitcoin": {
    "name": "Mainnet"
  },
  "stacks": {
    "name": "Mainnet"
  },
  "spark": {
    "name": "Mainnet"
  },
  "starknet": {
    "name": "Mainnet"
  }
}
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.xverse.app/sats-connect/guides/creating-bitcoin-psbts.md

Use this method to ask specific questions about the documentation when the answer is not explicitly present. The question should be self-contained and in natural language.

```http
GET https://docs.xverse.app/sats-connect/guides/creating-bitcoin-psbts.md?ask=<question>
```

--------------------------------

### Rejection Response Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_addliquidity.md

This JSON structure indicates that the liquidity provision was rejected, including a reason and details for refunding the provided assets.

```json
{
  "accepted": false,
  "error": "Pool is not accepting liquidity",
  "refund": {
    "assetAAmount": "100000000",
    "assetATransferId": "850h9700-h50e-73g7-d049-779988770003",
    "assetBAmount": "50000",
    "assetBTransferId": "950i0800-i61f-84h8-e150-880099880004"
  },
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}
```

--------------------------------

### confirmInitialDeposit

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_signintent.md

Confirms the initial deposit into a newly created liquidity pool. This step finalizes the pool's setup after assets have been deposited.

```APIDOC
## confirmInitialDeposit

### Description
Confirms the initial deposit into a newly created liquidity pool. This step finalizes the pool's setup after assets have been deposited.

### Method
Not Applicable (SDK/Intent-based)

### Endpoint
Not Applicable (SDK/Intent-based)

### Parameters
#### Data Parameters
- **poolId** (string) - Required - The ID of the liquidity pool.
- **assetASparkTransferId** (string) - Required - The transfer ID associated with the initial deposit of asset A.
- **poolOwnerPublicKey** (string) - Required - The public key of the pool owner.
- **nonce** (string) - Required - A unique nonce for this transaction.

### Request Example
```json
{
  "type": "confirmInitialDeposit",
  "data": {
    "poolId": "03poollp...",
    "assetASparkTransferId": "spark-transfer-uuid...",
    "poolOwnerPublicKey": "03b06b7c...",
    "nonce": "confirm-deposit-nonce-789"
  }
}
```

### Response
#### Success Response
(Details not provided in source)

#### Response Example
(Details not provided in source)
```

--------------------------------

### Open Receive Screen for Payment Address

Source: https://docs.xverse.app/sats-connect/wallet-methods/wallet_open/wallet_openreceive.md

This example demonstrates how to use the wallet_openReceive method to open the user's receive screen for a Bitcoin payment address. It includes error handling for access denied scenarios, prompting the user to connect their account if necessary, and retrying the request.

```typescript
import { request, RpcErrorCode } from "sats-connect";

async function openReceive() {
  const res = await request("wallet_openReceive", {
    address: "payment",
  });

  if (res.status === "success") {
    // res.result.address contains the address object that was opened in the wallet
    return res.result.address;
  }

  if (res.error.code === RpcErrorCode.ACCESS_DENIED) {
    // Your app is not connected to the user's active account yet
    // You can prompt the user to connect first:
    const permissionRes = await request("wallet_requestPermissions", undefined);

    if (permissionRes.status === "error") {
      // user declined connection
      throw new Error("User declined connection");
    }

    // retry after permissions are granted
    const retry = await request("wallet_openReceive", { address: "payment" });

    if (retry.status === "error") {
      throw new Error("Failed to open receive screen", { cause: retry.error });
    }

    return retry.result.address;
  }

  // Other errors (e.g. invalid address type or address not available)
  throw new Error("Failed to open receive screen", { cause: res.error });
}
```

--------------------------------

### Flashnet Intent (executeSwap) Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_signstructuredmessage.md

Example of a structured message for a Flashnet intent, specifically an `executeSwap` operation. Ensure the payload matches supported Flashnet intent schemas.

```json
{
  message: JSON.stringify({
      userPublicKey: "02abcdef...",
      lpIdentityPublicKey: "03aabbccddeeff...",
      assetInSparkTransferId: "spark-transfer-uuid-123",
      assetInAddress: "03bitcoinassetpubkey...",
      assetOutAddress: "03usdstablecoinpubkey...",
      amountIn: "100000000",
      minAmountOut: "99500000",
      maxSlippageBps: "50",
      nonce: "swap-nonce-123",
      totalIntegratorFeeRateBps: "0"
    })
}
```

--------------------------------

### Example: Navigate to Gamma.io in Xverse In-App Browser (Universal Links)

Source: https://docs.xverse.app/sats-connect/guides/mobile-integration.md

An example of navigating to www.gamma.io within the Xverse in-app browser using Universal Links on iOS.

```url
https://connect.xverse.app/browser?url=www.gamma.io
```

--------------------------------

### Example: Open Magic Eden in Xverse In-App Browser (Custom URL Scheme)

Source: https://docs.xverse.app/sats-connect/guides/mobile-integration.md

An example of using the custom URL scheme to open www.magiceden.io in the Xverse in-app browser.

```url
xverse://browser?url=www.magiceden.io
```

--------------------------------

### Detect Installed Wallet Providers

Source: https://docs.xverse.app/sats-connect/wallet-providers/getproviders-and-getproviderbyid.md

Use the getProviders method to detect all installed wallet providers that adhere to the WBIP004 standard. This method requires no parameters and returns an array of provider objects.

```tsx
import {getProviders} from "sats-connect";

const providers = getProviders()
```

--------------------------------

### Querying Documentation with 'ask' Parameter

Source: https://docs.xverse.app/sats-connect/stacks-methods/stx_signtransaction.md

Use this method to dynamically query the documentation for specific information. Replace `<question>` with your natural language query.

```HTTP
GET https://docs.xverse.app/sats-connect/stacks-methods/stx_signtransaction.md?ask=<question>
```

--------------------------------

### Flashnet JWT Issuance Challenge Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_signstructuredmessage.md

Example of a structured message for a Flashnet JWT issuance challenge. The message must be a string prefixed with `FLASHNET_AUTH_CHALLENGE_V1:` followed by 32 random bytes.

```string
{
  message: "FLASHNET_AUTH_CHALLENGE_V1:aabbccddeeff00112233445566778899..."
}
```

--------------------------------

### Create Bonding Pool Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_createbondingpool.md

Demonstrates how to use the spark_flashnet_createBondingPool method to request the creation of a bonding curve pool. Ensure the 'sats-connect' library is imported. The response will either contain the pool creation details or an error message.

```typescript
import { request } from "sats-connect";

try {
  const response = await request("spark_flashnet_createBondingPool", {
    assetAAddress: "0338d6978bd3163d1547f9ddb8b215d1c163bc7b4a552e559b89057f5449ba69de",
    assetAInitialReserve: "1000000000", // sats or smallest units
    assetBAddress: "020202020202020202020202020202020202020202020202020202020202020202",
    graduationThresholdPct: 50, // % of target to trigger graduation
    hostNamespace: "my-cool-exchange",
    lpFeeRateBps: 500, // 5.00%
    totalHostFeeRateBps: 200, // 2.00%
    targetBRaisedAtGraduation: "10000000000", // target raise
    poolOwnerPublicKey: "03b06b7c3e39bf922be19b7ad5f19554bb7991cae585ed2e3374d51213ff4eeb3c",
    nonce: "550e8400-e29b-41d4-a716-446655440000"
  });

  if ("result" in response) {
    console.log("Bonding pool created:", response.result);
  } else {
    console.error("Pool creation failed:", response.error.message);
  }
} catch (error) {
  console.error("Unexpected error:", error);
}
```

--------------------------------

### Success Response Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_createcppool.md

This JSON structure represents a successful creation of a liquidity pool, including the unique requestId.

```json
{
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}
```

--------------------------------

### Ask a Question via Documentation Index

Source: https://docs.xverse.app/sats-connect

Perform an HTTP GET request to the documentation index with the 'ask' parameter to retrieve specific information. The question should be self-contained and in natural language. The response includes the answer, relevant excerpts, and sources.

```HTTP
GET https://docs.xverse.app/readme.md?ask=<question>
```

--------------------------------

### Configure AI Agents with Sats Connect Context

Source: https://docs.xverse.app/sats-connect/ai-agent-integration.md

Add this markdown content to an AGENTS.md file at the root of your project to ensure AI agents automatically load Sats Connect expertise.

```markdown
## Sats Connect

This app uses Sats Connect for Bitcoin wallet integration.
When implementing or modifying wallet functionality, load the relevant Sats Connect skill.

Examples:

- Wallet connection → sats-connect-wallet-connect
- Get addresses → sats-connect-getAddresses
- Sign PSBT → sats-connect-signPsbt
- Runes transfer → sats-connect-runes-transfer
- Spark transfer → sats-connect-spark-transfer
```

--------------------------------

### Change Network Request

Source: https://docs.xverse.app/sats-connect/wallet-methods/wallet_changenetwork.md

Example of how to request a network change to 'Signet' using the wallet_changeNetwork method. Handles success and error responses.

```typescript
import Wallet from 'sats-connect';

async function example() {
  const res = await Wallet.request('wallet_changeNetwork', {
    name: 'Signet'
  });
  if (res.status === 'error') {
    console.error(res.error);
    return;
  }

  console.log(res.result);
}
```

--------------------------------

### Partial Success Response Example

Source: https://docs.xverse.app/sats-connect/spark-methods/flashnet-trading/spark_flashnet_addliquidity.md

This JSON structure represents a partial success where some liquidity was added, and the remaining unutilized assets are refunded.

```json
{
  "accepted": true,
  "assetAAmountUsed": "95000000",
  "assetBAmountUsed": "50000",
  "lpTokensMinted": "11500000",
  "refund": {
    "assetAAmount": "5000000",
    "assetATransferId": "750g8600-g49d-62f6-c938-668877660002"
  },
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}
```
Tokens:
Raw