Supertransaction API

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

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

Base URL: https://api.biconomy.io

Tutorials

1. Get Quote

Build your first quote request

2. Sign Payload

Handle different signature types

3. Execute

Submit and track your transaction

Welcome

ERC-8211 Smart Batching

AbstractJS SDK

Supertransaction API

The Pattern

What You Can Build

Token Swaps

DeFi Actions

Multi-Step Flows

Custom Contracts

Instruction Types

Account Modes

Gas Options

Sponsored (Gasless)

User Pays in Token

API Reference

Tutorials

1. Get Quote

2. Sign Payload

3. Execute

​The Pattern

​What You Can Build

Token Swaps

DeFi Actions

Multi-Step Flows

Custom Contracts

​Instruction Types

​Account Modes

​Gas Options

Sponsored (Gasless)

User Pays in Token

​API Reference

​Tutorials

1. Get Quote

2. Sign Payload

3. Execute

The Pattern

What You Can Build

Instruction Types

Account Modes

Gas Options

API Reference

Tutorials