spark_flashnet_executeRouteSwap

This method is coming 🔜

Use the spark_flashnet_executeRouteSwap method to request a multi-hop swap through Flashnet. Your app specifies the input amount, route (up to 4 hops), and slippage parameters. The wallet handles the full process: verifying the Spark transfer, signing the swap request, submitting it to Flashnet, and returning the results.

This abstracts all route complexity into a single wallet request while preserving atomic execution: either all hops succeed, or the swap is reverted.


Example

import { request } from "sats-connect";

try {
  const response = await request("spark_flashnet_executeRouteSwap", {
    userPublicKey: "02abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567",
    initialSparkTransferId: "spark-route-transfer-uuid-123456",
    inputAmount: 100000000, // sats or smallest unit of input asset
    maxRouteSlippageBps: 200, // 2.00% tolerance
    minAmountOut: 99500000, // optional safety check
    nonce: "unique-route-swap-nonce-789",
    hops: [
      {
        assetInAddress: "03bitcoinassetpubkey0000000000000000000000000000000000000000000000",
        assetOutAddress: "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
        hopIntegratorFeeRateBps: "25",
        poolId: "03pool1aabbccddeeff00112233445566778899aabbccddeeff00112233445566778"
      },
      {
        assetInAddress: "03ethereumassetpubkey1111111111111111111111111111111111111111111111",
        assetOutAddress: "03usdstablecoinpubkey2222222222222222222222222222222222222222222222",
        hopIntegratorFeeRateBps: "25",
        poolId: "03pool2bbccddeeffffaabbccddeeff00112233445566778899aabbccddeeff0011"
      }
    ]
  });

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

Parameters

  • userPublicKey (string, required) — Spark public key of the user.

  • initialSparkTransferId (string, required) — Spark transfer ID proving the input deposit.

  • inputAmount (integer, required) — Amount of input asset in smallest units.

  • maxRouteSlippageBps (integer, required) — Maximum slippage allowed for the entire route.

  • minAmountOut (integer, required) — Minimum acceptable final output.

  • nonce (string, required) — Unique identifier to prevent replay.

  • hops (array, required) — Ordered sequence of hops (1–4). Each hop includes:

    • assetInAddress

    • assetOutAddress

    • poolId

    • hopIntegratorFeeRateBps (optional)

  • integratorFeeRateBps (integer, optional) — Default integrator fee for the route.

  • integratorPublicKey (string, optional) — Public key of the integrator.


What it does

When called, the wallet:

  1. Shows a confirmation screen summarizing:

    • Input asset & amount

    • Route hops (pool IDs, asset in/out per hop)

    • Expected output & slippage tolerance

    • Applicable fees

  2. On approval:

    • Validates and signs the route swap request

    • Submits to Flashnet

    • Displays a progress screen

  3. Returns the route swap result back to the dApp.


Response

The method returns a Promise resolving to a SparkFlashnetRouteSwapResult.

✅ Success

{
  "accepted": true,
  "outputAmount": 99500000,
  "executionPrice": "0.00004975",
  "finalOutboundTransferId": "spark-transfer-out-123",
  "requestId": "01HJZKFABCDEFGHJKLMNPQRSTVW"
}

❌ Failure

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

Last updated