Build low-level custom instructions for your supertransaction

​
Overview

The /v1/instructions/build endpoint enables direct control over contract interactions by specifying exact function calls. Users provide ABI signatures and arguments to generate MEE instructions for precise contract execution.

​
How It Works

The build endpoint creates instructions by:
  1. Accepting function signatures - ABI-formatted function definitions
  2. Processing arguments - Supporting various data types and dynamic values
  3. Generating MEE instructions - Creates composable instructions for execution
This is the direct approach where users specify exactly what contracts to call and how, rather than expressing high-level intents.

​
Request Structure

POST /v1/instructions/build

​
Request Body

ParameterTypeRequiredDescription
functionSignaturestringYesFunction signature (e.g., function transfer(address to, uint256 amount))
argsarrayYesFunction arguments array
tostringYesTarget contract address (checksummed)
chainIdnumberYesChain ID where the transaction will be executed
valuestringNoNative token value in wei (default: “0”)
gasLimitstringNoGas limit for the transaction

​
Example Requests

curl -X POST https://api.biconomy.io/v1/instructions/build \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mee_2w3mXCuyt4xVXDRCZ5k5Lhgs" \
  -d '{
    "functionSignature": "function transfer(address to, uint256 amount)",
    "args": [
      "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a",
      "1000000000000000000"
    ],
    "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "chainId": 8453,
    "value": "0",
    "gasLimit": "50000"
  }'

​
Response

Returns an array of MEE instructions ready for execution: 
{
  "instructions": [
    {
      "calls": [
        {
          "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "value": "0",
          "functionSig": "transfer(address,uint256)",
          "inputParams": [
            {
              "fetcherType": 0,
              "paramData": "0x742d35C9a91B1D5b5D24Dc30e8F0dF8E84b5d1c4",
              "constraints": []
            },
            {
              "fetcherType": 0,
              "paramData": "0x0000000000000000000000000000000000000000000000000de0b6b3a7640000",
              "constraints": []
            }
          ],
          "outputParams": [
            {
              "fetcherType": 0,
              "paramData": "0x"
            }
          ]
        }
      ],
      "chainId": 8453,
      "isComposable": true
    }
  ]
}

​
Response Fields

FieldTypeDescription
instructionsarrayArray of MEE instruction objects
instructions[].callsarrayArray of contract calls within the instruction
instructions[].calls[].tostringTarget contract address
instructions[].calls[].valuestringNative token value in wei
instructions[].calls[].functionSigstringFunction signature without “function” keyword
instructions[].calls[].inputParamsarrayEncoded input parameters
instructions[].calls[].outputParamsarrayOutput parameter specifications
instructions[].chainIdnumberChain ID for execution
instructions[].isComposablebooleanWhether this instruction can be composed with others

​
Input Parameter Structure

Each input parameter contains:
FieldTypeDescription
fetcherTypenumberType of parameter fetcher (0 = static, 1 = dynamic)
paramDatastringEncoded parameter data
constraintsarrayOptional constraints for the parameter

​
Supported Argument Types

The args array supports various JavaScript/TypeScript types:
  • Address: Ethereum addresses (0x-prefixed, 40 hex characters) 
    "0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a"
  • Numbers: Can be passed as strings or numbers 
    "1000000000000000000"  // As string (recommended for large numbers)
1000000                 // As number
  • Boolean: Standard boolean values 
    true
false
  • Arrays: Nested arrays of any supported type 
    ["0xAddress1", "0xAddress2", "0xAddress3"]
  • Bytes: Hex-encoded byte arrays 
    "0x1234abcd"

​
Common Use Cases

​
ERC20 Token Transfer

{
  "functionSignature": "function transfer(address to, uint256 amount)",
  "args": ["0xRecipient", "1000000000000000000"],
  "to": "0xTokenContract",
  "chainId": 1
}

​
ERC20 Token Approval

{
  "functionSignature": "function approve(address spender, uint256 amount)",
  "args": ["0xSpenderContract", "115792089237316195423570985008687907853269984665640564039457584007913129639935"],
  "to": "0xTokenContract",
  "chainId": 1
}

​
Multi-Parameter Functions

{
  "functionSignature": "function swapExactTokensForTokens(uint256 amountIn, uint256 amountOutMin, address[] path, address to, uint256 deadline)",
  "args": [
    "1000000000000000000",
    "950000000000000000",
    ["0xToken1", "0xToken2"],
    "0xRecipient",
    "1700000000"
  ],
  "to": "0xRouterContract",
  "chainId": 1
}

​
Authentication

All requests require an API key to be passed in the header: 
X-API-Key: your_api_key_here

​
Error Responses

​
400 Bad Request

Returned when the request is malformed or contains invalid parameters: 
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "errors": [
    {
      "code": "INVALID_SIGNATURE",
      "path": ["functionSignature"],
      "message": "Invalid function signature format"
    }
  ]
}

​
500 Internal Server Error

Returned when the server encounters an unexpected error: 
{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "errors": [
    {
      "code": "SERVER_ERROR",
      "path": [],
      "message": "Internal server error"
    }
  ]
}

​
Best Practices

  1. Use string format for large numbers: To avoid JavaScript number precision issues, pass large numbers as strings
  2. Verify contract addresses: Ensure all addresses are checksummed and valid
  3. Test on testnets first: Always test your function calls on testnets before mainnet
  4. Set appropriate gas limits: Include a gasLimit parameter for complex operations
  5. Check function signatures: Ensure your function signature matches the target contract’s ABI exactly