Biconomy Instructions API

openapi: 3.2.0
info:
  title: Biconomy Instructions API
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: '1.0'
  description: 'Operations tagged instructions across 2 of this provider''s published API definitions: biconomy-supertransaction-api-0.6.12-openapi.json, biconomy-supertransaction-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.biconomy.io
  description: Production server
- url: https://api-staging.biconomy.io
  description: Staging server
tags:
- name: Instructions
paths:
  /v1/instructions/hyperliquid/deposit:
    post:
      description: Build instructions for depositing USDC from Arbitrum to Hyperliquid
      summary: Build Hyperliquid deposit instructions
      tags:
      - Instructions
      parameters: []
      operationId: hyperliquidDeposit
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              description: Object containing the Hyperliquid deposit request fields.
              type: object
              properties:
                ownerAddress:
                  type: string
                  example: '0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a'
                orchestratorAddressOverride:
                  type: string
                mode:
                  type: string
                  enum:
                  - smart-account
                sourceToken:
                  example: '0xaf88d065e77c8cc2239327c5edb3a432268e5831'
                sourceChainId:
                  example: 42161
                amount:
                  example: '10000000'
                feeToken:
                  type: object
                  properties:
                    address:
                      type: string
                    chainId:
                      type: number
                    gasRefundAddress:
                      type: string
                  required:
                  - address
                  - chainId
                  additionalProperties: false
                lowerBoundTimestamp:
                  type: number
                upperBoundTimestamp:
                  type: number
              required:
              - ownerAddress
              - mode
              - sourceToken
              - sourceChainId
              - amount
              additionalProperties: false
      responses:
        '200':
          description: Response schema for a Hyperliquid deposit quote.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ownerAddress:
                    type: string
                  fee:
                    type: object
                    properties:
                      amount:
                        type: string
                      token:
                        type: string
                      chainId:
                        type: number
                    required:
                    - amount
                    - token
                    - chainId
                  quoteType:
                    type: string
                    enum:
                    - permit
                    - onchain
                    - simple
                    - permit-sca
                    - mm-dtk
                  quote:
                    type: object
                  payloadToSign:
                    type: array
                    minItems: 1
                    items: {}
                required:
                - ownerAddress
                - fee
                - quoteType
                - quote
                - payloadToSign
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items: {}
                required:
                - code
                - message
                - errors
        '500':
          description: '500'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items: {}
                required:
                - code
                - message
                - errors
      security:
      - X-API-Key:
        - mee:*
        - instructions:*
    servers:
    - url: https://api.biconomy.io
      description: Production server
    - url: https://api-staging.biconomy.io
      description: Staging server
  /v1/instructions/build-ccip:
    post:
      description: Build CCIP token bridge instructions for your supertransaction
      summary: Build CCIP token bridge instructions
      tags:
      - Instructions
      parameters: []
      operationId: buildCcip
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              description: Object containing the CCIP token bridging field, including source/destination tokens and chains, user address, amount, execution mode, and slippage tolerance.
              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
                ownerAddress:
                  description: EOA wallet address which is going to be used as a owner of orchestrator account
                  type: string
                  example: '0x742d35cc6639cb8d4b5d1c5d7b8b5e2e7c0c7a8a'
                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
                mode:
                  type: string
                  enum:
                  - smart-account
                  - eoa
                  - eoa-7702
                gasLimit:
                  example: '50000'
                  description: Gas limit for the CCIP token bridging
                  type: string
              required:
              - srcToken
              - dstToken
              - srcChainId
              - dstChainId
              - ownerAddress
              - amount
              - mode
              additionalProperties: false
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  instructions:
                    description: Array of MEE instructions ready for execution
                    type: array
                    items:
                      description: Object representing a single MEE instruction, including the set of contract calls to execute, the target chain ID, and whether the instruction is composable with others in the same batch.
                      type: object
                      properties:
                        calls:
                          type: array
                          items:
                            anyOf:
                            - type: object
                              properties:
                                to:
                                  description: EVM address of the target smart contract to invoke for this call.
                                  type: string
                                  example: '0x1111111254EEB25477B68fb85Ed929f73A960582'
                                value:
                                  description: Amount of native token (in wei) to send with the contract call. Must be a non-negative integer.
                                  type: string
                                  example: '0'
                                functionSig:
                                  description: Function signature as a string, e.g. "transfer(address,uint256)". Must match the target contract ABI.
                                  type: string
                                  example: transfer(address,uint256)
                                inputParams:
                                  example:
                                  - fetcherType: 0
                                    paramData: '0x742d35C9a91B1D5b5D24Dc30e8F0dF8E84b5d1c4'
                                    constraints: []
                                  type: array
                                  items:
                                    example:
                                      fetcherType: 0
                                      paramData: '0x742d35C9a91B1D5b5D24Dc30e8F0dF8E84b5d1c4'
                                      constraints:
                                      - constraintType: 1
                                        referenceData: '500'
                                    type: object
                                    properties:
                                      fetcherType:
                                        type: number
                                        enum:
                                        - 0
                                        - 1
                                      paramData:
                                        description: String representing the input parameter data, such as ABI-encoded bytes or a direct value.
                                        type: string
                                        example: example string
                                      constraints:
                                        type: array
                                        items:
                                          example:
                                            constraintType: 0
                                            referenceData: '1000'
                                          type: object
                                          properties:
                                            constraintType:
                                              type: number
                                              enum:
                                              - 0
                                              - 1
                                              - 2
                                              - 3
                                            referenceData:
                                              description: String data used as the reference for the constraint, such as a literal value or ABI-encoded data.
                                              type: string
                                              example: example string
                                          required:
                                          - constraintType
                                          - referenceData
                                          additionalProperties: false
                                    required:
                                    - fetcherType
                                    - paramData
                                    - constraints
                                    additionalProperties: false
                                outputParams:
                                  example:
                                  - fetcherType: 0
                                    paramData: 0x
                                  type: array
                                  items:
                                    example:
                                      fetcherType: 0
                                      paramData: 0x
                                    type: object
                                    properties:
                                      fetcherType:
                                        type: number
                                        enum:
                                        - 0
                                        - 1
                                      paramData:
                                        description: String representing the output parameter data, such as ABI-encoded bytes or a result value.
                                        type: string
                                        example: example string
                                    required:
                                    - fetcherType
                                    - paramData
                                    additionalProperties: false
                                gasLimit:
                                  description: Gas limit for the contract call. Optional - if not provided, it will be estimated.
                                  type: string
                                  example: '100000'
                              required:
                              - to
                              - value
                              - functionSig
                              - inputParams
                              - outputParams
                              additionalProperties: false
                        chainId:
                          description: Chain ID on which this instruction should be executed. Must be a supported EVM chain ID.
                          type: number
                          example: 1
                        isComposable:
                          description: Indicates if this instruction is composable with others in the same execution batch.
                          type: boolean
                          example: true
                      required:
                      - calls
                      - chainId
                      additionalProperties: false
                  simulationTokenOverrides:
                    type: array
                    items:
                      type: object
                      properties:
                        tokenAddress:
                          description: Address of the token
                          type: string
                          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        accountAddress:
                          description: Address of the account
                          type: string
                          example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                        chainId:
                          description: Chain ID
                          type: number
                          example: 8453
                        balance:
                          description: Balance of the token
                          type: string
                          example: '12345678901234567890'
                      required:
                      - tokenAddress
                      - accountAddress
                      - chainId
                      - balance
                      additionalProperties: false
                required:
                - instructions
                additionalProperties: false
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        path:
                          type: array
                          items:
                            type: string
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                      additionalProperties: false
                required:
                - code
                - message
                - errors
                additionalProperties: false
        '500':
          description: '500'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        path:
                          type: array
                          items:
                            type: string
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                      additionalProperties: false
                required:
                - code
                - message
                - errors
                additionalProperties: false
      security:
      - X-API-Key:
        - mee:*
        - instructions:*
    servers:
    - url: https://api.biconomy.io
      description: Production server
    - url: https://api-staging.biconomy.io
      description: Staging server
components:
  securitySchemes:
    X-API-Key:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'API Key required to access Supertransaction API. Example: mee_2w3mXCuyt4xVXDRCZ5k5Lhgs'
x-refined-from:
- biconomy-supertransaction-api-0.6.12-openapi.json
- biconomy-supertransaction-api-openapi.yml