Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Onchain Orchestration Explained

Onchain orchestration is the coordination of multiple blockchain operations across one or more chains into a unified, atomic execution flow. Instead of manually executing a series of transactions, orchestration handles:
  • Sequencing: Execute operations in the correct order
  • Dependencies: Ensure step B uses the output of step A
  • Atomicity: All-or-nothing execution (no partial failures)
  • Cross-chain coordination: Bridge assets and execute on destination chains
Think of it as a conductor coordinating an orchestra—each instrument (transaction) plays its part at the right time to create a cohesive result.
Modern DeFi operations often require multiple steps:Example: Deposit USDC into a yield vault on another chain
  1. Approve USDC spending
  2. Swap USDC → bridgeable asset
  3. Bridge to destination chain
  4. Swap back to destination USDC
  5. Approve vault contract
  6. Deposit into vault
Without orchestration, users must:
  • ❌ Execute 6+ separate transactions
  • ❌ Wait for each to confirm
  • ❌ Handle failures manually
  • ❌ Pay gas 6 times
  • ❌ Risk price slippage between steps
With orchestration:
  • ✅ One signature, one transaction
  • ✅ Atomic execution
  • ✅ Automatic dependency handling
  • ✅ Optimal gas efficiency
Biconomy’s Supertransaction system orchestrates complex workflows:
┌─────────────────────────────────────────────────────────┐
│                    Supertransaction                      │
├─────────────────────────────────────────────────────────┤
│  Instruction 1: Swap ETH → USDC (Chain A)               │
│       ↓                                                  │
│  Instruction 2: Bridge USDC (Chain A → Chain B)         │
│       ↓                                                  │
│  Instruction 3: Deposit USDC to Vault (Chain B)         │
└─────────────────────────────────────────────────────────┘
                           ↓
                    Single Signature
                           ↓
                   Atomic Execution
The orchestration layer:
  1. Builds optimal execution paths
  2. Quotes total costs across all operations
  3. Executes with guaranteed ordering
  4. Tracks progress across chains
A Supertransaction is Biconomy’s abstraction for orchestrated blockchain operations. It combines:
  • Instructions: Individual operations (swaps, bridges, contract calls)
  • Runtime values: Dynamic values computed during execution
  • Conditions: Logic to control execution flow
  • Fee configuration: How gas is paid (sponsored, token, etc.)
const supertransaction = {
  instructions: [
    {
      type: "intent",
      intent: "swap",
      params: { from: "ETH", to: "USDC", amount: "1.0" }
    },
    {
      type: "intent", 
      intent: "bridge",
      params: { 
        token: "USDC", 
        fromChain: 1, 
        toChain: 8453,
        amount: runtime.outputOf(0) // Uses output from first instruction
      }
    }
  ],
  feeToken: { address: "sponsored" }
};
Biconomy supports orchestrating any EVM operation:
CategoryOperations
DeFiSwaps, bridges, lending, borrowing, staking, LP provisioning
NFTsMinting, transfers, marketplace interactions
GamingIn-game purchases, asset transfers, crafting
DAOsVoting, delegation, treasury management
CustomAny smart contract interaction
Operations can be:
  • Intent-based: “Swap 1 ETH to USDC” (solver finds best route)
  • Explicit: Specific contract call with exact parameters
  • Conditional: Execute only if certain conditions are met
Cross-chain orchestration coordinates operations across multiple blockchains:
  1. Source chain execution: Execute initial operations
  2. Asset bridging: Move tokens to destination chain
  3. Destination execution: Complete operations on target chain
Biconomy integrates with multiple bridge providers to find optimal routes:
const crossChainFlow = {
  instructions: [
    // Step 1: Swap on Ethereum
    {
      chainId: 1,
      type: "intent",
      intent: "swap",
      params: { from: "ETH", to: "USDC", amount: "1.0" }
    },
    // Step 2: Bridge to Base
    {
      type: "intent",
      intent: "bridge", 
      params: {
        fromChain: 1,
        toChain: 8453,
        token: "USDC"
      }
    },
    // Step 3: Deposit on Base
    {
      chainId: 8453,
      type: "call",
      to: VAULT_ADDRESS,
      data: depositCalldata
    }
  ]
};
The orchestrator handles:
  • Bridge selection and routing
  • Waiting for bridge confirmation
  • Gas on destination chain
  • Failure recovery
Runtime values allow later instructions to reference outputs from earlier ones. This enables truly composable workflows:
import { runtime } from "@biconomy/abstractjs";

const instructions = [
  // Instruction 0: Swap - outputs USDC amount
  { type: "intent", intent: "swap", params: {...} },
  
  // Instruction 1: Use the EXACT output from swap
  {
    type: "call",
    to: vaultContract,
    value: 0n,
    data: encodeDeposit(runtime.outputOf(0)) // Dynamic!
  }
];
Without runtime values, you’d have to estimate outputs, leading to failed transactions or leftover tokens.
Orchestration provides different failure modes:
ModeBehaviorUse Case
AtomicAll operations succeed or all revertCritical multi-step operations
PartialContinue after failures, collect resultsNon-critical batch operations
ConditionalSkip steps based on conditionsComplex branching logic
// Atomic execution (default)
const result = await execute(supertransaction);

// With condition - only execute if balance > 0
{
  type: "call",
  condition: {
    type: "balance",
    token: USDC_ADDRESS,
    operator: "gt",
    value: 0n
  },
  ...
}
AspectAggregationOrchestration
ScopeFinding best single routeCoordinating multiple operations
ExampleDEX aggregator finds best swapBridge + swap + deposit in one flow
ComplexitySingle operation optimizationMulti-step workflow management
Cross-chainUsually single chainNative multi-chain support
Orchestration uses aggregation for individual steps but adds coordination, dependencies, and cross-chain capabilities.
Using AbstractJS SDK:
import { createMeeClient, runtime } from "@biconomy/abstractjs";

const client = await createMeeClient({ account: smartAccount });

// Build orchestrated transaction
const quote = await client.getQuote({
  instructions: [
    mcUSDC.on(base.id).read.balanceOf(account.address),
    // More instructions...
  ],
  feeToken: mcUSDC.on(optimism.id)
});

// Execute with single signature
const result = await client.executeQuote(quote);
Using Supertransaction API:
# 1. Get quote for orchestrated operations
curl -X POST "https://api.biconomy.io/v1/quote" \
  -H "x-api-key: $API_KEY" \
  -d '{"instructions": [...], "feeToken": {...}}'

# 2. Execute with signature
curl -X POST "https://api.biconomy.io/v1/execute" \
  -H "x-api-key: $API_KEY" \
  -d '{"quote": {...}, "signature": "0x..."}'

​
Learn more about orchestration

Multi-Chain Execution

Execute across chains with one signature

Batched Transactions

Combine multiple operations efficiently