Guide: Native Swap Example

This guide provides a complete, code-first walkthrough for creating and submitting a swap transaction using the API. We will build a real-world example: swapping USD to cBTC on the Citrea blockchain backed by Sepolia ETH as collateral, using Crest as a liquidity source.

The Goal

Our goal is to create an “intent” that performs the following actions:

On Sepolia Testnet: A user deposits 0.0001 Sepolia ETH into an escrow EOA.
On Citrea Testnet: Using the value from the deposit, execute a swap for cBTC via crest contract.
Finally: The solver sends the principal amount of the deposit back to the user on Citrea.

This entire process will be defined in a single intent, signed by the user once, and submitted to the API.

Prerequisites

You’ll need viem to interact with chains, create authorizations, and sign messages. For frontend applications, you would need to use privy SDK to work with embedded wallets.

import {
  createWalletClient,
  http,
  parseUnits,
  getAddress,
  formatEther
} from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { citreaTestnet, sepolia } from "viem/chains";

Step 1: Setting up Accounts and Clients

First, we define the accounts and blockchain clients we’ll be working with. In a real application, the user would be the end-user interacting with your application, and their private key would be managed by their wallet.

// A sample user account
const user = privateKeyToAccount("0x...");

// The escrow contract address where the initial deposit is sent
const escrowAddress = getAddress("0x...");


const publicSepoliaClient = createPublicClient({
  chain: sepolia,
  transport: http(),
});

const publicCitreaClient = createPublicClient({
  chain: citreaTestnet,
  transport: http(),
});

Step 2: Define the Intent Parameters

We’ll define the amounts and generate a quote for the swap part of our intent.

const depositAmount = parseUnits("0.0001", 18);

// In a real app, you would call an external service like crest's /rfqt endpoint
// to get a signed quote for the swap.
const crestRfqt = await generateRfqt({
  quoteId: "0x...",
  user: user.address,
  tokenIn: "usd",
  tokenOut: "bitcoin",
  amountIn: formatEther(depositAmount),
  amountOut: "100", // Targeting 100 USD
  expiry: Math.floor(Date.now() / 1000) + 60, // 1 minute expiry
});

Step 3: Create EIP-7702 Authorizations

The core of the process is the user granting our system one-time authority on each chain. The user’s wallet will sign an EIP-7702 authorization for each delegate contract on each chain.

// Fetch the current nonce for the user on each chain
const nonceSepolia = await publicSepoliaClient.getTransactionCount({address: user.address});
const nonceCitrea = await publicCitreaClient.getTransactionCount({address: user.address});

// Read the delegate contract per chain from the SDK; do not hardcode (it differs per chain).
import { getDelegateContract } from "@spicenet-io/spiceflow-core";
const delegateAddressSepolia = getDelegateContract(sepolia.id);
const delegateAddressCitrea = getDelegateContract(citreaTestnet.id);

// User signs an authorization for Sepolia
const userAuthSepolia = await user.signAuthorization({
  address: delegateAddressSepolia,
  chainId: sepolia.id,
  nonce: nonceSepolia,
});

// User signs another authorization for Citrea
const userAuthCitrea = await user.signAuthorization({
  address: delegateAddressCitrea,
  chainId: citreaTestnet.id,
  nonce: nonceCitrea,
});

These authorization objects are what a solver will use to execute transactions on the user’s behalf.

Step 4: Construct the Chain Batches

Now we define the specific on-chain actions. Each object in the chainBatches array represents a set of calls to be executed on a specific blockchain, in order. Import the hashing helpers from @spicenet-io/spiceflow-core. Do not hand-roll them, and do not add a recentBlock field: the current chain-batch shape is { chainId, calls }, and the request schema rejects unknown keys.

import { hashChainBatches } from "@spicenet-io/spiceflow-core";

const chainBatches = hashChainBatches([
  // Step 0: Deposit Sepolia ETH to escrow
  {
    chainId: sepolia.id,
    calls: [{ to: escrowAddress, data: "0x", value: depositAmount }],
  },
  // Step 1: Swap for cBTC on Citrea. The RFQT object from Step 2 is a valid "Call".
  {
    chainId: citreaTestnet.id,
    calls: [crestRfqt],
  },
]);

hashChainBatches returns each batch as { hash, chainId, calls }.

Step 5: Sign the Intent and Build the Request

The user signs the intent hash. getIntentHash takes the signature type, a not-before timestamp (nbf), an expiry (exp), and the hashed chain batches:

import { getIntentHash } from "@spicenet-io/spiceflow-core";

const nbf = 0n;
const exp = BigInt(Math.floor(Date.now() / 1000) + 3600); // 1 hour

const digest = getIntentHash("ecdsa", nbf, exp, chainBatches);

const signature = await user.signMessage({ message: { raw: digest } });

Assemble the POST /actions request body. chainAuthorizations are the EIP-7702 authorizations from Step 3, each { r, s, yParity, address, chainId, nonce } (drop the legacy v field). Each chain batch also carries its tokenTransfers (how the solver moves tokens):

const apiRequest = {
  user: user.address,
  chainAuthorizations: [userAuthSepolia, userAuthCitrea],
  intents: [
    {
      mode: "7702",
      signatureType: "ecdsa",
      signature,
      nbf: Number(nbf),
      exp: Number(exp),
      chainBatches: chainBatches.map((b) => ({ ...b, tokenTransfers: [] })),
    },
  ],
};

Send it to POST /actions. See the POST /actions reference for the full request and response schema.

curl -X POST https://tx-submission-api.spicenet.io/actions \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x...",
    "chainAuthorizations": [ { "r": "0x...", "s": "0x...", "yParity": 0, "address": "0x...", "chainId": 11155111, "nonce": 0 } ],
    "intents": [
      {
        "mode": "7702",
        "signatureType": "ecdsa",
        "signature": "0x...",
        "nbf": 0,
        "exp": 1750000000,
        "chainBatches": [ { "hash": "0x...", "chainId": 11155111, "tokenTransfers": [], "calls": [ ... ] } ]
      }
    ]
  }'

What Happens Next: The Solver

After you submit the intent, the API makes it available to a network of solvers. A solver will:

Pick up your intent.
Execute Step 0 by sending a transaction to the Delegate contract on Sepolia, using your signed authorization. This deposits your funds to escrow.
Wait for the required block confirmations.
Execute Step 1 by sending a transaction to the Delegate contract on Citrea, which performs the swap.
As part of the final transaction, the solver also transfers the principal deposit amount (tokenAmount) back to your address (address) on the destination chain (Citrea).

Your application can track each step using the GET /actions/{actionId}/intents/{intentIndex}/steps/{stepIndex} endpoint. You have successfully orchestrated a cross-chain action without requiring the user to switch networks or manage gas on the destination chain.

Getting Started

SDK Reference

Guides & Examples

Technical Deep Dive

Native Swap Example

Guide: Native Swap Example

The Goal

Prerequisites

Step 1: Setting up Accounts and Clients

Step 2: Define the Intent Parameters

Step 3: Create EIP-7702 Authorizations

Step 4: Construct the Chain Batches

Step 5: Sign the Intent and Build the Request

What Happens Next: The Solver

​Guide: Native Swap Example

​The Goal

​Prerequisites

​Step 1: Setting up Accounts and Clients

​Step 2: Define the Intent Parameters

​Step 3: Create EIP-7702 Authorizations

​Step 4: Construct the Chain Batches

​Step 5: Sign the Intent and Build the Request

​What Happens Next: The Solver

Guide: Native Swap Example

The Goal

Prerequisites

Step 1: Setting up Accounts and Clients

Step 2: Define the Intent Parameters

Step 3: Create EIP-7702 Authorizations

Step 4: Construct the Chain Batches

Step 5: Sign the Intent and Build the Request

What Happens Next: The Solver