Biconomy root API

openapi: 3.2.0
info:
  title: Supertransaction instructions Root API
  version: 0.4.0
  description: A comprehensive Supertransaction API documentation
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.biconomy.io
  description: Production server
- url: https://api-staging.biconomy.io
  description: Staging server
security:
- X-API-Key: []
tags:
- name: root
paths:
  /v1/quote:
    post:
      description: Compose instructions and retrieve a MEE quote in a single request.
      summary: Compose instructions and generate a quote
      tags:
      - root
      parameters: []
      operationId: quote
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              description: Combine compose flows with quote configuration to compose instructions and generate a quote in a single call.
              type: object
              properties:
                mode:
                  type: string
                  enum:
                  - smart-account
                  - eoa
                  - eoa-7702
                ownerAddress:
                  description: EOA wallet address which is used as owner of the orchestrator account
                  type: string
                  example: '0x0a7C906832544293a6018bA25280c7f7b0Bbf120'
                authorizations:
                  type: array
                  items:
                    description: Object containing the EIP-7702 authorization signature fields for delegation, including the signer address, chain ID, nonce, and ECDSA signature components (r, s, v/yParity). Used to prove delegation intent and validity.
                    type: object
                    properties:
                      address:
                        description: The EVM address of the delegation contract to which your EOA (Externally Owned Account) is being upgraded. Must be a valid checksummed Ethereum address.
                        type: string
                        example: '0x00000069E0Fb590E092Dd0E36FF93ac28ff11a3a'
                      chainId:
                        description: The chain ID for which this authorization is valid. Use 0 for multichain or specify a supported chain ID.
                        type: number
                        example: 8453
                      nonce:
                        description: Signature nonce
                        type: number
                        example: 38
                      r:
                        description: The "r" value of the ECDSA signature, as a 32-byte hex string prefixed with 0x.
                        type: string
                        example: '0x192a2503401595804c35cdc5b748fe35cceb77ef534bf5d670f7797376487ded'
                      s:
                        description: The "s" value of the ECDSA signature, as a 32-byte hex string prefixed with 0x.
                        type: string
                        example: '0x1fd3c8acd0b7c5f64a8d72c35c39988544fca961b838277ab11750041cccc3d1'
                      v:
                        example: '28'
                        description: The "v" value of the ECDSA signature (recovery id), as a string. Optional for EIP-2098 signatures.
                        type: string
                      yParity:
                        description: The y-parity value (EIP-2098) for the signature. Should be 0 or 1.
                        type: number
                        example: 1
                    required:
                    - address
                    - chainId
                    - nonce
                    - r
                    - s
                    - yParity
                    additionalProperties: false
                fundingTokens:
                  type: array
                  items:
                    description: Object containing the funding token deposit for MEE fusion execution.
                    type: object
                    properties:
                      tokenAddress:
                        description: Contract address of the token that will be deposited into the Nexus smart account.
                        type: string
                        example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                      chainId:
                        description: Chain ID where the funding token resides. Use a supported chain ID.
                        type: number
                        example: 1
                      amount:
                        description: Amount of funding token in wei/smallest unit to deposit.
                        type: string
                        example: '1000000000'
                    required:
                    - tokenAddress
                    - chainId
                    - amount
                    additionalProperties: false
                feeToken:
                  description: Optional fee token configuration. If not specified, sponsorship will be used.
                  type: object
                  properties:
                    address:
                      description: Contract address of the token used to pay MEE execution fees
                      type: string
                      example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                    chainId:
                      description: Chain ID where the fee token resides. Use a supported chain ID.
                      type: number
                      example: 1
                    gasRefundAddress:
                      example: '0x0a7C906832544293a6018bA25280c7f7b0Bbf120'
                      description: Custom gas refund address to receive remaining unspent gas. Defaults to owner address. Gas refunds are always in ETH and may be refunded on multiple chains depending on userOps involved.
                      type: string
                  required:
                  - address
                  - chainId
                  additionalProperties: false
                cleanUps:
                  description: Optional cleanup configurations for intermediate tokens
                  type: array
                  items:
                    description: Cleanup configuration for intermediate tokens that may remain after failed operations.
                    type: object
                    properties:
                      tokenAddress:
                        description: Address of the token to cleanup
                        type: string
                        example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                      chainId:
                        description: Chain ID where the token cleanup should occur
                        type: number
                        example: 1
                      recipientAddress:
                        description: Address to receive the cleanup tokens
                        type: string
                        example: '0x0a7C906832544293a6018bA25280c7f7b0Bbf120'
                      amount:
                        example: '1000000'
                        description: Amount to cleanup in wei. If not specified, uses runtime balance (entire balance).
                        type: string
                      gasLimit:
                        example: '150000'
                        description: Custom gas limit for cleanup userOp
                        type: string
                    required:
                    - tokenAddress
                    - chainId
                    - recipientAddress
                    additionalProperties: false
                gasLimit:
                  description: Optional gas limit override for the gas userop.
                  type: string
                  example: '12345678901234567890'
                lowerBoundTimestamp:
                  description: The lower bound timestamp for the user operation.
                  type: number
                  example: 1710000000
                upperBoundTimestamp:
                  description: The upper bound timestamp for the user operation.
                  type: number
                  example: 1710003600
                simulate:
                  type: boolean
                simulationOverrides:
                  type: object
                  properties:
                    tokenOverrides:
                      default: []
                      type: array
                      items:
                        type: object
                        properties:
                          tokenAddress:
                            description: Address of the token to override the balance for.
                            type: string
                            example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                          accountAddress:
                            example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                            description: Address of the account to override the balance for.
                            type: string
                          chainId:
                            description: Chain ID where the token override should occur
                            type: number
                            example: 1
                          balance:
                            description: Balance of the token to override the balance for, in wei/smallest unit.
                            type: string
                            example: '1000000000'
                        required:
                        - tokenAddress
                        - chainId
                        - balance
                        additionalProperties: false
                    customOverrides:
                      default: []
                      type: array
                      items:
                        type: object
                        properties:
                          contractAddress:
                            description: Address of the contract to override the storage slot for.
                            type: string
                            example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
                          storageSlot:
                            description: Storage slot to override the value for.
                            type: string
                            example: '0x1234567890123456789012345678901234567890123456789012345678901234'
                          chainId:
                            description: Chain ID where the storage slot override should occur
                            type: number
                            example: 1
                          value:
                            description: Value to override the storage slot for.
                            type: string
                            example: '0x1234567890123456789012345678901234567890'
                        required:
                        - contractAddress
                        - storageSlot
                        - chainId
                        - value
                        additionalProperties: false
                  required:
                  - tokenOverrides
                  - customOverrides
                  additionalProperties: false
                composeFlows:
                  minItems: 1
                  maxItems: 10
                  type: array
                  items:
                    description: This enable developers to specify a build, intent-simple, or intent operation
                    anyOf:
                    - type: object
                      properties:
                        type:
                          description: Compose flow for the "build" type to generate composable MEE instructions from a custom specification.
                          example: /instructions/build
                          type: string
                          const: /instructions/build
                        data:
                          description: Request to build composable instructions from ABI signature and arguments
                          type: object
                          properties:
                            to:
                              description: Target contract address
                              type: string
                              example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                            chainId:
                              description: Chain ID where the transaction will be executed
                              type: number
                              example: 8453
                            value:
                              example: '0'
                              description: Native token value in wei
                              type: string
                            gasLimit:
                              example: '50000'
                              description: Gas limit for the transaction
                              type: string
                            functionSignature:
                              description: Function signature string (e.g., "function approve(address spender, uint256 amount)")
                              type: string
                              example: function transfer(address to, uint256 amount)
                            args:
                              type: array
                              items: {}
                          required:
                          - to
                          - chainId
                          - functionSignature
                          - args
                          additionalProperties: false
                        batch:
                          description: Flag to enable or disable instructions batching. By default, batching is enabled
                          type: boolean
                          example: true
                      required:
                      - type
                      - data
                      additionalProperties: false
                    - type: object
                      properties:
                        type:
                          description: Compose flow for the "build-raw" type to generate composable MEE instructions from raw calldata.
                          example: /instructions/build-raw
                          type: string
                          const: /instructions/build-raw
                        data:
                          description: Request to build composable instructions from raw calldata
                          type: object
                          properties:
                            to:
                              description: Target contract address
                              type: string
                              example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                            chainId:
                              description: Chain ID where the transaction will be executed
                              type: number
                              example: 8453
                            value:
                              example: '0'
                              description: Native token value in wei
                              type: string
                            gasLimit:
                              example: '50000'
                              description: Gas limit for the transaction
                              type: string
                            data:
                              description: Raw calldata as hex string (e.g., "0x1234..." for encoded function call)
                              type: string
                              example: '0xa9059cbb0000000000000000000000001234567890123456789012345678901234567890000000000000000000000000000000000000000000000000000000000000000a'
                          required:
                          - to
                          - chainId
                          - data
                          additionalProperties: false
                        batch:
                          description: Flag to enable or disable instructions batching. By default, batching is enabled
                          type: boolean
                          example: true
                      required:
                      - type
                      - data
                      additionalProperties: false
                    - type: object
                      properties:
                        type:
                          description: Compose flow for the "build-ccip" type to generate composable MEE instructions for Chainlink CCIP token bridging
                          example: /instructions/build-ccip
                          type: string
                          const: /instructions/build-ccip
                        data:
                          type: object
                          properties:
                            srcToken:
                              description: Source token EVM address. Must be a valid checksummed Ethereum address.
                              type: string
                              example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                            dstToken:
                              description: Destination token EVM address. Must be a valid checksummed Ethereum address.
                              type: string
                              example: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58'
                            srcChainId:
                              description: The source chain ID for the swap or token bridging. Use a supported chain ID number.
                              type: number
                              example: 8453
                            dstChainId:
                              description: The destination chain ID for the swap or token bridging. Use a supported chain ID number.
                              type: number
                              example: 10
                            amount:
                              anyOf:
                              - example: '1000000'
                              - description: Schema for specifying a runtime ERC20 balance check, including the target address, token address, and optional constraints.
                                type: object
                                properties:
                                  type:
                                    example: runtimeErc20Balance
                                    type: string
                                    const: runtimeErc20Balance
                                  targetAddress:
                                    example: '0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a'
                                    description: The address whose ERC20 balance will be checked at runtime. If not provided, the balance will be checked for the smart account address derived from the owner address.
                                    type: string
                                  tokenAddress:
                                    example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                                  constraints:
                                    description: Constraints for runtime value checks. Specify one or more of gte, lte, or eq to restrict the value.
                                    type: object
                                    properties:
                                      gte:
                                        example: '1000000'
                                        description: Greater than or equal to
                                        type: string
                                      lte:
                                        example: '10000000'
                                        description: Less than or equal to
                                        type: string
                                      eq:
                                        example: '5000000'
                                        description: Equal to
                                        type: string
                                    additionalProperties: false
                                required:
                                - type
                                - tokenAddress
                                additionalProperties: false
                            gasLimit:
                              example: '50000'
                              description: Gas limit for the CCIP token bridging
                              type: string
                          required:
                          - srcToken
                          - dstToken
                          - srcChainId
                          - dstChainId
                          - amount
                          additionalProperties: false
                        batch:
                          description: Flag to enable or disable instructions batching. By default, batching is enabled
                          type: boolean
                          example: true
                      required:
                      - type
                      - data
                      additionalProperties: false
                    - type: object
                      properties:
                        type:
                          description: Compose flow for the "intent-simple" type for basic cross-chain swaps.
                          example: /instructions/intent-simple
                          type: string
                          const: /instructions/intent-simple
                        data:
                          type: object
                          properties:
                            srcToken:
                              description: Source token EVM address. Must be a valid checksummed Ethereum address.
                              type: string
                              example: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
                            dstToken:
                              description: Destination token EVM address. Must be a valid checksummed Ethereum address.
                              type: string
                              example: '0x94b008aa00579c1307b0ef2c499ad98a8ce58e58'
                            srcChainId:
                              description: The source chain ID for the swap or token bridging. Use a supported chain ID number.
                              type: number
                              example: 8453
                            dstChainId:
                              description: The destination chain ID for the swap or token bridging. Use a supported chain ID number.
                              type: number
                              example: 10
                            amount:
                              example: '1000000'
                            routeSelectionMode:
                              description: Swap route selection strategy. Use `cheap` (default) to evaluate every route and pick the highest output. Use `fast-quote` to return as soon as the first valid route is discovered. `fast-execution` is reserved for future use.
                              example: cheap
                              type: string
                              enum:
                              - cheap
                              - fast-quote
                              - fast-execution
                            allowSwapProviders:
                              example: lifi,gluex
                              description: Comma-separated list of allowed swap providers.
                              type: string
                            denySwapProviders:
                              example: ''
                              description: Comma-separated list of denied swap providers.
                              type: string
                            allowBridgeProviders:
                              example: across
                              description: Comma-separated list of allowed bridge providers.
                              type: string
                            denyBridgeProviders:
                              example: across
                              description: Comma-separated list of denied bridge providers.
                              type: string
                            slippage:
                              description: 'Slippage tolerance (0-1, default: 0.01 = 1%)'
                              example: 0.01
                              default: 0.01
                              type: number
                              minimum: 0
                              maximum: 1
                          required:
                          - srcToken
                          - dstToken
                          - srcChainId
                          - dstChainId
                          - amount
                          - slippage
                          additionalProperties: false
                        batch:
                          description: Flag to enable or disable instructions batching. By default, batching is enabled
                          type: boolean
                          example: true
                      required:
                      - type
                      - data
                      additionalProperties: false
                    - type: object
                      properties:
                        type:
                          description: Compose flow for the "intent" type for advanced multi-chain, multi-asset operations.
                          example: /instructions/intent
                          type: string
                          const: /instructions/intent
                        data:
                          type: object
                          properties:
                            slippage:
                              description: Slippage must be a number between 0 and 1 (inclusive)
                              example: 0.003
                              type: number
                              minimum: 0
                              maximum: 1
                            inputPositions:
                              minItems: 1
                              type: array
                              items:
                                description: Input position specifying the chain, token, and amount to be used as input for the intent request.
                                type: object
                                properties:
                                  chainToken:
                                    description: The chain and token for the input position. Must include a supported chainId and a valid EVM token address.
                                    example:
                                      chainId: 8453
                                      tokenAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                                    type: object
                                    properties:
                                      chainId:
                                        description: The chain and token for the input position. Must include a supported chainId and a valid EVM token address.
                                        type: number
                                        example: 8453
                                      tokenAddress:
                                        description: The chain and token for the input position. Must include a supported chainId and a valid EVM token address.
                                        type: string
                                        example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                                    required:
                                    - chainId
                                    - tokenAddress
                                    additionalProperties: false
                                  amount:
                                    example: '1000000'
                                required:
                                - chainToken
                                - amount
                                additionalProperties: false
                            targetPositions:
                              description: 'Target positions: target assets with their respective weights. Weights define the distribution of the output assets. Weights for all the entries must sum to 1'
                              minItems: 1
                              type: array
                              items:
                                description: Target position specifying the chain, token, and weight for the intent request.
                                type: object
                                properties:
                                  chainToken:
                                    description: The chain and token for the target position. Must include a supported chainId and a valid EVM token address.
                                    example:
                                      chainId: 8453
                                      tokenAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                                    type: object
                                    properties:
                                      chainId:
                                        description: The chain and token for the target position. Must include a supported chainId and a valid EVM token address.
                                        type: number
                                        example: 8453
                                      tokenAddress:
                                        description: The chain and token for the target position. Must include a supported chainId and a valid EVM token address.
                                        type: string
                                        example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                                    required:
                                    - chainId
                                    - tokenAddress
                                    additionalProperties: false
                                  weight:
                                    example: 0.5
                                required:
                                - chainToken
                                - weight
                                additionalProperties: false
                          required:
                          - slippage
                          - inputPositions
                          - targetPositions
                          additionalProperties: false
                        batch:
                          description: Flag to enable or disable instructions batching. By default, batching is enabled
                          type: boolean
                          example: true
                      required:
                      - type
                      - data
                      additionalProperties: false
              required:
              - mode
              - ownerAddress
              - composeFlows
              additionalProperties: false
      responses:
        '200':
          description: Combined response containing composed instructions and the resulting MEE quote.
          content:
            application/json:
              schema:
                description: Combined response containing composed instructions and the resulting MEE quote.
                type: object
                properties:
                  ownerAddress:
                    description: Owner wallet address which will be used as a owner of orchestrator account
                    type: string
                    example: '0x1234567890abcdef1234567890abcdef12345678'
                  fee:
                    description: 'Fee details: amount, token address, and chain ID.'
                    type: object
                    properties:
                      amount:
                        description: Fee amount for the quote in wei.
                        type: string
                        example: '10000000000000000'
                      token:
                        description: EVM address of the fee token (zero address for native ETH).
                        type: string
                        example: '0x0000000000000000000000000000000000000000'
                      chainId:
                        description: Chain ID where the fee token resides.
                        type: number
                        example: 8453
                    required:
                    - amount
                    - token
                    - chainId
                    additionalProperties: false
                  quoteType:
                    description: 'Type of MEE signature: permit, oncha

# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/biconomy/refs/heads/main/openapi/biconomy-root-api-openapi.yml