Biconomy Supertransaction API

openapi: 3.1.0
info:
  title: Biconomy Supertransaction API (MEE)
  version: '1.0'
  description: >-
    The Biconomy Supertransaction API exposes the Modular Execution Environment
    (MEE) over a small REST surface. /v1/quote composes a multichain execution
    plan and returns the signable payload(s); /v1/execute submits the signed
    quote and the MEE orchestrates cross-chain settlement. Three account modes
    are supported - eoa, smart-account (ERC-4337 / Nexus / ERC-7579), and
    eoa-7702 (EIP-7702 delegation).
  contact:
    name: Biconomy
    url: https://docs.biconomy.io
  license:
    name: Proprietary
servers:
  - url: https://api.biconomy.io
    description: Biconomy MEE production
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Project-scoped API key issued from dashboard.biconomy.io.
paths:
  /v1/quote:
    post:
      description: Compose instructions and retrieve a MEE quote in a single request.
      summary: Compose instructions and generate a quote
      tags: &ref_0
        - 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: >-
                 

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