Build

This instruction type enables direct contract interaction by specifying exact function calls. Provide ABI signatures and arguments to call any EVM contract as part of your supertransaction.

How It Works

The build flow:

Accepts function signatures - ABI-formatted function definitions
Processes arguments - Supports static values and runtime balance injection
Generates instructions - Creates executable MEE instructions
Enables composition - Combines with other flow types seamlessly

Parameters

When using /instructions/build in your composeFlows array:

Parameter	Type	Required	Description
`functionSignature`	string	Yes	ABI function signature (e.g., `function transfer(address to, uint256 amount)`)
`args`	array	Yes	Function arguments array
`to`	string	Yes	Target contract address (checksummed)
`chainId`	number	Yes	Chain ID for execution
`value`	string	No	Native token value in wei (default: “0”)
`gasLimit`	string	No	Gas limit override

Runtime Balance Injection

The build flow type supports runtimeErc20Balance for dynamic amount calculations:

{
  type: 'runtimeErc20Balance',
  tokenAddress: '0x...',
  constraints: { gte: '1' }  // Optional: minimum balance required
}

Runtime balance is currently only supported for /instructions/build flow type. Support for other types coming in future updates.

Complete Workflow Examples

Token Transfer
With Runtime Balance
DeFi Operations
Native ETH Withdrawal

Simple ERC20 transfer

import { createWalletClient, http, parseUnits } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http()
});

// Step 1: Build quote request
const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function transfer(address to, uint256 value)',
        args: [
          '0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a', // recipient
          parseUnits('10', 6).toString() // 10 USDC
        ],
        to: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
        chainId: 8453
      }
    }
  ]
};

// Step 2: Get quote
const quote = await fetch('https://api.biconomy.io/v1/quote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(quoteRequest)
}).then(r => r.json());

// Then sign and POST to /v1/execute

Transfer entire balance dynamically

const quoteRequest = {
  mode: 'eoa',
  ownerAddress: account.address,
  fundingTokens: [{
    tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    chainId: 8453,
    amount: parseUnits('100', 6).toString()
  }],
  composeFlows: [
    // Swap first
    {
      type: '/instructions/intent-simple',
      data: {
        srcChainId: 8453,
        dstChainId: 10,
        srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
        dstToken: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
        amount: parseUnits('100', 6).toString(),
        slippage: 0.01
      }
    },
    // Transfer resulting balance
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function transfer(address to, uint256 value)',
        args: [
          account.address,
          {
            type: 'runtimeErc20Balance',
            tokenAddress: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
            constraints: { gte: '1' } // Ensure at least 1 wei
          }
        ],
        to: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58',
        chainId: 10
      }
    }
  ]
};

// Then quote → sign → execute

Approve and supply to Aave

const quoteRequest = {
  mode: 'smart-account',
  ownerAddress: account.address,
  composeFlows: [
    // Step 1: Swap USDC → WETH
    {
      type: '/instructions/intent-simple',
      data: {
        srcChainId: 8453,
        dstChainId: 8453,
        srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
        dstToken: '0x4200000000000000000000000000000000000006',
        amount: parseUnits('100', 6).toString(),
        slippage: 0.01
      }
    },
    // Step 2: Approve Aave pool
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function approve(address spender, uint256 amount)',
        args: [
          '0x...aavePoolAddress',
          {
            type: 'runtimeErc20Balance',
            tokenAddress: '0x4200000000000000000000000000000000000006'
          }
        ],
        to: '0x4200000000000000000000000000000000000006',
        chainId: 8453,
        gasLimit: '80000'
      }
    },
    // Step 3: Supply to Aave
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)',
        args: [
          '0x4200000000000000000000000000000000000006',
          {
            type: 'runtimeErc20Balance',
            tokenAddress: '0x4200000000000000000000000000000000000006'
          },
          account.address, // Or Nexus address
          0
        ],
        to: '0x...aavePoolAddress',
        chainId: 8453,
        gasLimit: '350000'
      }
    }
  ]
};

// Then quote → sign → execute

Withdraw native ETH using ETH Forwarder

Important: When withdrawing native ETH/tokens (not ERC20), you cannot use the standard ERC20 transfer() function. Use the ETH Forwarder contract instead.

import { parseUnits, zeroAddress } from 'viem';

const quoteRequest = {
  mode: 'eoa',
  ownerAddress: account.address,
  fundingTokens: [{
    tokenAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
    chainId: 8453,
    amount: parseUnits('100', 6).toString()
  }],
  feeToken: {
    address: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    chainId: 8453
  },
  composeFlows: [
    // Step 1: Swap USDC → Native ETH
    {
      type: '/instructions/intent-simple',
      data: {
        srcChainId: 8453,
        dstChainId: 8453,
        srcToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC
        dstToken: zeroAddress, // Native ETH (0x0000...0000)
        amount: parseUnits('100', 6).toString(),
        slippage: 0.01
      }
    },
    // Step 2: Withdraw native ETH to EOA using ETH Forwarder
    {
      type: '/instructions/build',
      data: {
        functionSignature: 'function forward(address recipient)',
        args: [
          account.address  // Recipient (your EOA)
        ],
        to: '0x000000Afe527A978Ecb761008Af475cfF04132a1',  // ETH Forwarder contract
        chainId: 8453,
        value: parseUnits('0.035', 18).toString(),  // Amount in wei to forward (~$100 worth)
        gasLimit: '300000'
      }
    }
  ]
};

// Then quote → sign → execute

Key Points:

Native tokens are represented using zeroAddress (0x0000000000000000000000000000000000000000)
ETH Forwarder contract: 0x000000Afe527A978Ecb761008Af475cfF04132a1
Use the value field to specify the amount of native tokens to forward
Works for ETH, MATIC, BNB, and all other native tokens
Same forwarder address across all supported chains

Argument Types

The args array supports various data types:

Static Values

args: [
  '0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a',  // address
  '1000000',                                         // uint256 as string
  true,                                              // boolean
  ['0x...', '0x...']                                // address[] array
]

Runtime Balance (Dynamic)

args: [
  recipient,
  {
    type: 'runtimeErc20Balance',
    tokenAddress: '0x...',
    constraints: { gte: '1' } // Optional minimum
  }
]

Complex Types

// Struct arguments
args: [
  {
    token: '0x...',
    amount: '1000000',
    recipient: '0x...'
  }
]

// Nested arrays
args: [
  [
    ['0x...', '100'],
    ['0x...', '200']
  ]
]

Best Practices

Use Runtime Balance for Withdrawals

Always use runtime balance when withdrawing after swaps (for EOA mode):

{
  type: '/instructions/build',
  data: {
    functionSignature: 'function transfer(address to, uint256 value)',
    args: [
      ownerAddress,
      {
        type: 'runtimeErc20Balance',
        tokenAddress: resultToken,
        constraints: { gte: '1' }
      }
    ],
    to: resultToken,
    chainId: dstChainId
  }
}

Set Appropriate Gas Limits

Override gas limits for complex operations:

// Simple transfer
gasLimit: '50000'

// DeFi protocol interactions
gasLimit: '350000'

// Complex multi-step operations
gasLimit: '500000'

Batch Same-Chain Operations

Same-chain build instructions are automatically batched:

composeFlows: [
  {
    type: '/instructions/build',
    // batch: true (default)
    data: { chainId: 8453, ... }
  },
  {
    type: '/instructions/build',
    // Automatically batched with above
    data: { chainId: 8453, ... }
  }
]

Validate Function Signatures

Ensure function signatures match the ABI exactly:

// ✅ Correct
functionSignature: 'function transfer(address to, uint256 value)'

// ❌ Wrong (missing 'function' keyword)
functionSignature: 'transfer(address to, uint256 value)'

// ❌ Wrong (incorrect parameter names - doesn't matter but be consistent)
functionSignature: 'function transfer(address recipient, uint256 amt)'

Use ETH Forwarder for Native Tokens

When withdrawing or transferring native tokens (ETH, MATIC, BNB, etc.), always use the ETH Forwarder contract:

import { zeroAddress } from 'viem';

// ❌ Bad - Cannot use ERC20 transfer for native tokens
{
  type: '/instructions/build',
  data: {
    functionSignature: 'function transfer(address to, uint256 value)',
    args: [ownerAddress, parseUnits('0.1', 18).toString()],
    to: zeroAddress,  // Native ETH - transfer() won't work
    chainId: 8453
  }
}

// ✅ Good - Use ETH forwarder for native tokens
{
  type: '/instructions/build',
  data: {
    functionSignature: 'function forward(address recipient)',
    args: [ownerAddress],
    to: '0x000000Afe527A978Ecb761008Af475cfF04132a1',  // ETH forwarder
    chainId: 8453,
    value: parseUnits('0.1', 18).toString(),  // Amount to forward
    gasLimit: '300000'
  }
}

Common Use Cases

Withdraw from DeFi Protocol

{
  type: '/instructions/build',
  data: {
    functionSignature: 'function withdraw(address asset, uint256 amount, address to)',
    args: [
      '0x...tokenAddress',
      parseUnits('100', 18).toString(),
      account.address
    ],
    to: '0x...aavePoolAddress',
    chainId: 8453,
    gasLimit: '300000'
  }
}

NFT Transfer

{
  type: '/instructions/build',
  data: {
    functionSignature: 'function safeTransferFrom(address from, address to, uint256 tokenId)',
    args: [
      account.address,
      '0x...recipientAddress',
      '42' // NFT token ID
    ],
    to: '0x...nftContractAddress',
    chainId: 8453
  }
}

Custom DEX Swap

{
  type: '/instructions/build',
  data: {
    functionSignature: 'function swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline)',
    args: [
      parseUnits('100', 6).toString(),
      parseUnits('95', 6).toString(),
      ['0x...tokenA', '0x...tokenB'],
      account.address,
      Math.floor(Date.now() / 1000) + 3600 // 1 hour deadline
    ],
    to: '0x...routerAddress',
    chainId: 8453,
    gasLimit: '200000'
  }
}

Troubleshooting

Invalid function signature

Ensure your signature exactly matches the contract ABI:

Include the function keyword
Use correct parameter types (e.g., uint256, not uint)
Match parameter names (though names don’t affect encoding)

Transaction reverted

Common causes:

Insufficient balance for operation
Missing token approvals (add approve instruction first)
Gas limit too low (increase gasLimit)
Contract-specific requirements not met

Runtime balance not working

Runtime balance is only supported for /instructions/build:

Cannot use in /instructions/intent-simple
Cannot use in /instructions/intent
Must be in the args array, not other parameters

About Supertransaction API

Building Workflow Instructions

Executing Workflows

Account Versioning

API Reference

How It Works

Parameters

Runtime Balance Injection

Complete Workflow Examples

Argument Types

Static Values

Runtime Balance (Dynamic)

Complex Types

Best Practices

Common Use Cases

Withdraw from DeFi Protocol

NFT Transfer

Custom DEX Swap

Troubleshooting

About Supertransaction API

Building Workflow Instructions

Executing Workflows

Account Versioning

API Reference

​How It Works

​Parameters

​Runtime Balance Injection

​Complete Workflow Examples

​Argument Types

​Static Values

​Runtime Balance (Dynamic)

​Complex Types

​Best Practices

​Common Use Cases

​Withdraw from DeFi Protocol

​NFT Transfer

​Custom DEX Swap

​Troubleshooting

How It Works

Parameters

Runtime Balance Injection

Complete Workflow Examples

Argument Types

Static Values

Runtime Balance (Dynamic)

Complex Types

Best Practices

Common Use Cases

Withdraw from DeFi Protocol

NFT Transfer

Custom DEX Swap

Troubleshooting