The Supertransaction API lets you build complex blockchain operations—swaps, bridges, DeFi deposits—without writing smart contracts. Users sign once, and Biconomy handles everything.
The Pattern
Every Supertransaction follows the same four steps:
Build Your Flow
Define what you want to do using composeFlows—swap tokens, bridge chains, call contracts
Get a Quote
POST to /v1/quote → receive execution costs, routing info, and a payload to sign
Sign the Payload
User signs once (the format depends on wallet type)
Execute
POST to /v1/execute → Biconomy handles all the blockchain complexity
// The complete flow in 20 lines
const quote = await fetch('https://api.biconomy.io/v1/quote', {
method: 'POST',
body: JSON.stringify({
mode: 'smart-account',
ownerAddress: userAddress,
composeFlows: [{
type: '/instructions/intent-simple',
data: { srcChainId: 8453, dstChainId: 10, srcToken: USDC, dstToken: USDT, amount: '100000000', slippage: 0.01 }
}]
})
}).then(r => r.json());
const signature = await wallet.signMessage(quote.payloadToSign[0]);
const result = await fetch('https://api.biconomy.io/v1/execute', {
method: 'POST',
body: JSON.stringify({ ...quote, payloadToSign: [{ ...quote.payloadToSign[0], signature }] })
}).then(r => r.json());
What You Can Build
Token Swaps
Same-chain or cross-chain swaps with automatic routing
DeFi Actions
Deposit, withdraw, stake across any protocol
Multi-Step Flows
Chain operations: swap → bridge → deposit in one tx
Custom Contracts
Call any smart contract function
Instruction Types
The composeFlows array supports four instruction types:
| Type | Use Case | Example |
|---|
/instructions/intent-simple | Token swaps (same or cross-chain) | Swap USDC → ETH |
/instructions/intent | Complex multi-token operations | Rebalance portfolio |
/instructions/build | Custom contract calls | Deposit into Aave |
/instructions/build-raw | Pre-encoded calldata | Advanced integrations |
Start with intent-simple for swaps—it handles routing, bridging, and DEX selection automatically.
Account Modes
Choose the mode that matches your users’ wallets:
smart-account
eoa
eoa-7702
For: Biconomy Nexus accounts, ERC-4337 smart accounts{ mode: 'smart-account', ownerAddress: '0x...' }
- Native gas abstraction
- Single signature always
- Funds stay in smart account
For: MetaMask, Rabby, Trust Wallet, any EOA{
mode: 'eoa',
ownerAddress: '0x...',
fundingTokens: [{ tokenAddress: '0x...', chainId: 8453, amount: '1000000' }]
}
- Works with any wallet
- Requires
fundingTokens parameter
- Uses Fusion execution under the hood
For: Embedded wallets (Privy, Dynamic, Turnkey) with EIP-7702{ mode: 'eoa-7702', ownerAddress: '0x...' }
- Best of both worlds
- Single signature like smart accounts
- No fundingTokens needed
Gas Options
Sponsored (Gasless)
Omit feeToken—gas is paid from your sponsorship account{ mode: 'smart-account', ownerAddress: '0x...' }
// No feeToken = sponsored
User Pays in Token
Set feeToken to deduct from user’s balance{
feeToken: { address: USDC, chainId: 8453 }
}
API Reference
| Endpoint | Purpose |
|---|
POST /v1/quote | Get execution quote and signable payload |
POST /v1/execute | Submit signed quote for execution |
GET /v1/explorer/{hash} | Track execution status |
https://api.biconomy.io
Tutorials
