spark_flashnet_executeSwap

This method is coming 🔜

Use the spark_flashnet_executeSwap method to request a Flashnet swap directly from the user’s Spark wallet.

Your app provides the swap parameters (pool, assets, amount, slippage, etc.), and the wallet handles the full Flashnet swap process.

This abstracts all back-and-forth with Flashnet into a single request, making swaps simple and secure.

Parameters

🚀 Become an Xverse Partner to enable integrator fees for your app ⇒ reach out to get started

Request parameters	Description
poolId	a string representing the Flashnet liquidity pool to use
assetInAddress	a string representing the address of the Spark asset being swapped in
assetOutAddress	a string representing the address of the Spark asset being swapped out
amountIn	a string representing the amount of input asset (in sats or smallest unit)
maxSlippageBps	Max slippage in basis points (e.g. 50 = 0.5%)
minAmountOut	ℹ️ Optional - a string representing the minimum acceptable output amount
totalIntegratorFeeRateBps	Fee (in basis points) your app requests for routing the swap. ⚠️To activate your app fee, you must be an approved Xverse partner. If you’re not approved, Xverse will ignore this value and apply its own default fee instead. 🚀 Contact Xverse to become a partner and activate your app fee.
integratorPublicKey	Public key where your integrator fees should be sent. ⚠️ Only partner-approved (whitelisted) keys are accepted. If you pass a non-partner key, Xverse will replace it with its own. 🚀 Contact Xverse to become a partner and get your key whitelisted.
userPublicKey	a string which must match the connected user's Spark public key
nonce	ℹ️ Optional - a string representing a unique swap nonce

Example

import { request } from "sats-connect";

try {
  const response = await request("spark_flashnet_executeSwap", {
    poolId: "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
    assetInAddress: "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
    assetOutAddress: "03usdstablecoinpubkey111111111111111111111111111111111111111111111",
    amountIn: "100000000", // in sats or smallest token units
    maxSlippageBps: 50, // 0.50% tolerance
    minAmountOut: "99500000", // optional safety check
    totalIntegratorFeeRateBps: 100, // 1.00% fee
    integratorPublicKey: "03aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899",
    userPublicKey: "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567",
    nonce: "unique-swap-nonce-123"
  });

  if ("result" in response) {
    console.log("Swap result:", response.result);
  } else {
    console.error("Swap failed:", response.error.message);
  }
} catch (error) {
  console.error("Unexpected error:", error);
}

What spark_flashnet_executeSwap does

When called, this method:

1. Shows the user a confirmation screen with the swap details (pool, asset in/out, amount, fees, slippage).

2. On confirmation, the wallet:

   • Initiates the Spark transfer and authenticates your user with a Flashnet JWT

   • Generates the swap intent

   • Signs with the user’s Spark key

   • Submits to Flashnet

   • Returns the result (success or rejection)

3. Displays a progress screen while the steps complete.

4. Returns the swap result to the dApp.

Responses

The method returns a Promise that resolves to the SparkFlashnetSwapResultobject

✅ Success

{
  "accepted": true,
  "amountOut": 4975000,
  "assetInAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
  "assetOutAddress": "03usdstablecoinpubkey111111111111111111111111111111111111111111111",
  "executionPrice": "0.00004975",
  "feeAmount": 5000,
  "outboundTransferId": "spark-transfer-out-123",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}

❌ Failure

{
  "accepted": false,
  "error": "Insufficient liquidity in pool",
  "refundTransferId": "spark-transfer-refund-456",
  "refundedAmount": 100000000,
  "refundedAssetAddress": "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}