openapi: "3.0.0"
info:
  title: Hyperflow Bridge Aggregator APIs
  version: 1.0.0
servers:
  - url: https://bridge-ag-api.hyperflow.fun/v1
paths:
  /quote:
    get:
      tags: [Bridge]
      summary: Get quote details
      parameters:
        - name: fromChain
          in: query
          required: true
          description: "The source chain identifier (e.g., ethereum, arbitrum)."
          schema:
            type: string
            enum:
              [
                "hyperevm",
                "arbitrum",
                "optimism",
                "ethereum",
                "base",
                "unichain",
                "hypercore",
              ]
        - name: fromToken
          in: query
          required: true
          description: "The token address on the source chain. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native gas tokens."
          schema:
            type: string
            example: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
        - name: toChain
          in: query
          required: true
          description: "The destination chain identifier (e.g., hyperevm)."
          schema:
            type: string
            enum:
              [
                "hyperevm",
                "arbitrum",
                "optimism",
                "ethereum",
                "base",
                "unichain",
                "hypercore",
              ]
        - name: toToken
          in: query
          required: true
          description: "The token address on the destination chain. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native gas tokens."
          schema:
            type: string
            example: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
        - name: amount
          in: query
          required: true
          description: "The amount to transfer, represented as a string in the token’s smallest units (e.g., wei for ETH). Example: 1000000000000000000 = 1 ETH."
          schema:
            type: string
            example: "1000000000000000000"
        - name: protocols
          in: query
          required: true
          description:
            "Comma-separated list of protocols to consider. Supported values:
            `kyberswap`, `hyperflow`, `wrapnative`, `hypercore`, `layerzero`,
            `hyperunit`, `gaszip`, `relay`."
        - name: sender
          in: query
          required: false
          description: "The wallet address of the user initiating the transfer."
          schema:
            type: string
            example: "0x76FAA890edB90bE3066D3aCC3ae5252a477494E1"
        - name: receiver
          in: query
          required: false
          description: "The wallet address of the user receiving funds on the destination chain."
          schema:
            type: string
            example: "0x76FAA890edB90bE3066D3aCC3ae5252a477494E1"
        - name: slippage
          in: query
          required: false
          description: "The maximum slippage allowed, where 100 represents 1%. Defaults to 100."
          schema:
            type: string
            example: "100"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: "Status of the quote request."
                  data:
                    type: array
                    description: "List of available quotes matching the request parameters."
                    items:
                      $ref: "#/components/schemas/Quote"
                  requestId:
                    type: string
                    description: "Unique identifier for the quote, required for transaction encoding. Expires after 30s."

  /encode:
    post:
      summary: Encode tx transaction
      tags: [Bridge]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: "The request ID returned from /quote. Only valid within 30 seconds."
                quoteIdx:
                  type: number
                  format: integer
                  description: "The index of the selected quote from the list returned by /quote."
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TxRequest"
  /hyperbridge/orders:
    get:
      tags: [Bridge]
      summary: Get orders by source transaction
      parameters:
        - name: src_tx
          in: query
          required: true
          description: "The source transaction hash to look up related bridge orders."
          schema:
            type: string
            example: "0x018c5d48906f82ca16e3eb7e0198954770ea3d275d16bd30f8b4cabf60c1b664"
      responses:
        200:
          description: A list of orders found for the given `src_tx`. If no orders are found, an empty array is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    description: "List of matching bridge orders."
                    items:
                      $ref: "#/components/schemas/Order"
              example:
                orders:
                  - dst_amount: "1867414"
                    dst_chain: "hyperevm"
                    dst_min_amount: "1865895"
                    dst_token: "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"
                    dst_ts: 1757402388
                    dst_tx: "0xa1762a1b124eb32e6be6cc00768803434f10907df8b8789a7abf84a493f7e61e"
                    fee: "0"
                    id: "relay::0xfefc8882057aa8e4dd3432ba5280d8630a2771b4e2da38cdb93134829c6a613b"
                    recipient: "0xcf7633D5128f9d8ee98A50617430F2F38f212eff"
                    sender: "0xcf7633D5128f9d8ee98A50617430F2F38f212eff"
                    src_amount: "2000000"
                    src_chain: "base"
                    src_token: "0x102d758f688a4C1C5a80b116bD945d4455460282"
                    src_ts: 1757402385
                    src_tx: "0x018c5d48906f82ca16e3eb7e0198954770ea3d275d16bd30f8b4cabf60c1b664"
                    state: "done"
                    type: "relay"
components:
  schemas:
    Quote:
      type: object
      properties:
        fromToken:
          allOf:
            - $ref: "#/components/schemas/Token"
            - description: "The token being swapped/bridged from the source chain."
        toToken:
          allOf:
            - $ref: "#/components/schemas/Token"
            - description: "The token being received on the destination chain."
        amountIn:
          type: string
          description: "The input amount in token’s smallest units."
        amountOut:
          type: string
          description: "The expected output amount in token’s smallest units."
        amountOutUsd:
          type: string
          description: "The expected output amount converted to USD."
        crossChain:
          type: boolean
          description: "Whether the quote involves a cross-chain transfer."
        crossProtocol:
          allOf:
            - $ref: "#/components/schemas/Protocol"
            - description: "The bridging protocol used in the cross-chain step."
        fees:
          allOf:
            - $ref: "#/components/schemas/Fee"
            - description: "Fee information for this quote."
        steps:
          type: array
          description: "Breakdown of individual steps in the swap/bridge route."
          items:
            $ref: "#/components/schemas/Step"

    TxRequest:
      type: object
      properties:
        to:
          type: string
          example: "0x0000000000000000000000000000000000000000"
          description: "The destination contract address for the transaction."
        value:
          type: string
          example: "1000000000000000000"
          description: "The amount of native token to send, in smallest units."
        data:
          type: string
          example: "0x123..."
          description: "The encoded transaction data payload."
        requestId:
          type: string
          description: "The request ID corresponding to the original quote."

    Token:
      type: object
      properties:
        address:
          type: string
          description: "The token contract address (or 0xEeee... for native tokens)."
        chainId:
          type: string
          description: "The chain ID where this token resides."
        symbol:
          type: string
          description: "The short symbol of the token (e.g., ETH, USDC)."
        name:
          type: string
          description: "The full name of the token."
        decimals:
          type: number
          format: integer
          description: "The number of decimals used by the token."
        cgkId:
          type: string
          description: "CoinGecko ID for the token (used for pricing)."

    Protocol:
      type: object
      properties:
        id:
          type: string
          description: "The unique identifier of the protocol."
        name:
          type: string
          description: "The human-readable name of the protocol."
        type:
          type: string
          description: "The type of protocol (e.g., bridge, dex)."
        logo:
          type: string
          description: "URL of the protocol’s logo."

    Fee:
      type: object
      properties:
        usd:
          type: number
          format: float
          description: "The total fee amount expressed in USD."

    Step:
      type: object
      properties:
        fromToken:
          allOf:
            - $ref: "#/components/schemas/Token"
            - description: "Token being swapped or bridged from the source chain."
        toToken:
          allOf:
            - $ref: "#/components/schemas/Token"
            - description: "Token received on the destination chain."
        crossChain:
          type: boolean
          description: "Whether this step is cross-chain."
        protocol:
          allOf:
            - $ref: "#/components/schemas/Protocol"
            - description: "The protocol used in this step."
        amountIn:
          type: string
          description: "Input amount for this step in smallest units."
        amountOut:
          type: string
          description: "Output amount for this step in smallest units."
        amountOutUsd:
          type: string
          description: "Output amount in USD for this step."
        fees:
          allOf:
            - $ref: "#/components/schemas/Fee"
            - description: "Fee details for this step."
        duration:
          type: string
          description: "Estimated time for this step to complete."
        metadata:
          type: object
          description: "Additional metadata or step-specific details."
        internalSteps:
          type: array
          description: "Nested sub-steps within this step (if any)."
          items:
            $ref: "#/components/schemas/Step"
    Order:
      type: object
      properties:
        id:
          type: string
          description: "Unique identifier of the order, typically includes protocol name and hash."
        type:
          type: string
          description: "The type of bridge or protocol (e.g., relay, mayan)."
        state:
          type: string
          description: "The current state of the order."
          enum: [pending, done, failed, refunded]
        sender:
          type: string
          description: "The address of the user initiating the transaction."
        recipient:
          type: string
          description: "The address receiving the funds on the destination chain."
        src_tx:
          type: string
          description: "The source chain transaction hash."
        src_chain:
          type: string
          description: "The source blockchain identifier."
        src_token:
          type: string
          description: "The token address on the source chain."
        src_amount:
          type: string
          description: "The source token amount in smallest units."
        src_ts:
          type: integer
          description: "The timestamp of the source transaction."
        dst_tx:
          type: string
          nullable: true
          description: "The destination chain transaction hash. Only present when `state` = done."
        dst_chain:
          type: string
          description: "The destination blockchain identifier."
        dst_token:
          type: string
          description: "The token address on the destination chain."
        dst_amount:
          type: string
          nullable: true
          description: "The destination token amount in smallest units. Only present when `state` = done."
        dst_min_amount:
          type: string
          nullable: true
          description: "The minimum guaranteed destination token amount in smallest units. Optional field."
        dst_ts:
          type: integer
          nullable: true
          description: "The timestamp of the destination transaction. Only present when `state` = done."
        fee:
          type: string
          description: "The fee charged for the transaction, in smallest units."
