{displayAssets.map((a) => (
))}
setAmount(e.target.value)} />
{statusMsg &&
);
}
```
Everything above the JSX is wiring; the JSX is yours to replace entirely.
## Scaling to All Markets
Only two things vary per market: `destinationToken` and `buildActionCalls`. Wrap the panel in a
component that takes those as props (or a market config object) and every market gets any-asset,
any-chain funding with the same code path.
## Withdrawals
`SpiceWithdraw` handles withdrawing Spice balances back to a wallet on any supported chain. To build
your own withdraw UI instead, use `useSpiceAssets` for balances and `useSpiceExecution` for
execution — see [Hooks](/sdk/hooks).
## Testing
Set `network="testnet"` on `SpiceFlowProvider` (and swap the wagmi/Privy chain set to the testnet
chains) to run the identical flow against testnet infrastructure. Testnet funds for supported tokens
come from the [airdrop endpoint](/api-reference/endpoint/airdrop). Move to `network="mainnet"` only
after the full supply → withdraw loop passes on testnet.
## Notes
* `feeExecutionMode: "backend-transfer"` lets the backend collect fees from the funded amount; the
fee quote's `netAmount` is what reaches the market.
* `executeSupply` drives your state through the `ui` setters — render `step`, `statusMsg`, and
`error` however you like. Steps: `idle → signing-delegation → signing-intent → submitting →
executing → success | error`.
* Supported chains come from the SDK per `network` — see
[Configuration](/sdk/configuration#default-chains-by-network). Restrict with `supportedChainIds`
or `sourceChains` on `useSupplyAssets`.
# Native Swap Example
Source: https://spiceflow-docs.spicenet.io/guides/native-swap
Create a simple asset swap on Citrea backed by collateral on Ethereum sepolia
# 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](https://x.com/crest_btc) as a liquidity source.
## The Goal
Our goal is to create an "intent" that performs the following actions:
1. **On Sepolia Testnet**: A user deposits `0.0001` Sepolia ETH into an escrow EOA.
2. **On Citrea Testnet**: Using the value from the deposit, execute a swap for cBTC via `crest` contract.
3. **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.
```typescript theme={null}
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.
```typescript theme={null}
// 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.
```typescript theme={null}
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.
```typescript theme={null}
// 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.
```typescript theme={null}
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:
```typescript theme={null}
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):
```typescript theme={null}
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](/api-reference/endpoint/actions-create) reference
for the full request and response schema.
```bash theme={null}
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:
1. Pick up your intent.
2. Execute **Step 0** by sending a transaction to the `Delegate` contract on Sepolia, using your signed authorization. This deposits your funds to escrow.
3. Wait for the required block confirmations.
4. Execute **Step 1** by sending a transaction to the `Delegate` contract on Citrea, which performs the swap.
5. 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.
# How It Works
Source: https://spiceflow-docs.spicenet.io/how-it-works
Understanding the technical flow behind Spice Flow API
## Naming Convention
The API uses the following naming convention:
* **Intent**: The parent action which contains ChainBatch(es)
* **ChainBatch**: For a specific chain, and has many Call(s)
* **Call**: Has `to`, `data`, and `value` parameters
{statusMsg}
} {error &&{error}
} {txHash &&{txHash}
}Loading...
; if (!hasBalance) returnNo deposits yet
; return (-
{assets.map(asset => (
- {asset.symbol}: {asset.balanceFormatted} on chain {asset.chainId} ))}
Not connected
; return (Connected via {provider}: {address}
No embedded wallet
; returnEmbedded: {embeddedAddress}
; } ``` *** ## useAssetInput Manage asset selection and amount input state. Used to control the asset selector in deposit and lock flows from your own UI. ### Usage ```tsx theme={null} import { useAssetInput } from "@spicenet-io/spiceflow-ui"; function CustomInput() { const { selectedAsset, setSelectedAsset, assetAmount, setAssetAmount } = useAssetInput(); return ( setAssetAmount(e.target.value)} placeholder="Amount" /> ); } ``` ### Return Value | Field | Type | Description | | ------------------ | ----------------------- | ------------------------ | | `selectedAsset` | `SelectedAsset \| null` | Currently selected asset | | `setSelectedAsset` | `(asset) => void` | Set the selected asset | | `assetAmount` | `string` | Current amount string | | `setAssetAmount` | `(amount) => void` | Set the amount | *** ## useLockDuration Manage lock duration selection state for `SpiceLock`. ### Usage ```tsx theme={null} import { useLockDuration } from "@spicenet-io/spiceflow-ui"; const durationOptions = [ { label: "1 Month", months: 1 }, { label: "6 Months", months: 6 }, { label: "12 Months", months: 12 }, ]; function DurationPicker() { const { selectedDurationIdx, setSelectedDurationIdx, selectedDuration } = useLockDuration(durationOptions); return (
{durationOptions.map((opt, i) => (
))}
);
}
```
***
## useSpicePendingDeposits
Detect funds stranded in the user's embedded wallet (deposits that were sent but not yet credited to Spice balance). Used by SpiceDeposit internally for recovery flows.
### Usage
```tsx theme={null}
import { useSpicePendingDeposits } from "@spicenet-io/spiceflow-ui";
function PendingCheck() {
const { pendingDeposits } = useSpicePendingDeposits({
chainIds: [8453, 4114],
});
if (pendingDeposits.length > 0) {
return You have {pendingDeposits.length} pending deposit(s) to recover.
; } return null; } ``` *** ## useSpiceBrand Resolve the current theme from the provider's `theme` prop and any component-level `styles`/`dark` overrides. Only used when building custom components that need to match the SDK's look. ### Usage ```tsx theme={null} import { useSpiceBrand } from "@spicenet-io/spiceflow-ui"; function CustomCard({ styles, dark }) { const { primaryColor, dk, palette } = useSpiceBrand(styles, dark); return (
Themed card
);
}
```
### Return Value
| Field | Type | Description |
| -------------- | --------------------- | ------------------------------------- |
| `dark` | `boolean` | Whether dark mode is active |
| `primaryColor` | `string` | Brand accent color |
| `theme` | `Theme` | Full theme object |
| `dk` | `ResolvedDarkPalette` | Dark palette values |
| `palette` | `ResolvedDarkPalette` | Mode resolved palette (light or dark) |
***
## Next Steps
Loading...
;
}
```
***
## Environment Variables
Store your provider credentials in environment variables:
```env theme={null}
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
```
Then use them in your code:
```tsx theme={null}
Custom card
Matches SDK palette