openapi: 3.0.0
info:
  title: Enso ccip relay API
  description: '#### Enso API

    - Find detailed documentation on [docs.enso.finance](https://docs.enso.finance).

    - To use the API, **you must include your API Key in the Authorization header** (Bearer format).

    - For testing, Swagger pre-authorizes you using the key: `1e02632d-6feb-4a75-a157-documentation` (1rps).

    - Get your own API Key at [enso.finance/developers](https://developers.enso.build/).'
  version: '1.0'
  contact: {}
servers:
- url: https://api.enso.finance
security:
- bearer: []
tags:
- name: relay
paths:
  /api/v1/relay/bridge/check:
    get:
      operationId: RelayController_checkBridgeTransaction
      summary: Check Relay bridge transaction status
      description: Returns comprehensive information about a cross-chain Relay bridge transaction, including Relay message parameters, on-chain events, and transaction data from Enso.
      parameters:
      - name: chainId
        required: true
        in: query
        description: Chain ID of the source transaction
        schema:
          example: 1
          type: number
      - name: txHash
        required: true
        in: query
        description: Transaction hash of the Relay bridge transaction on source chain
        schema:
          example: '0x94e5ea92d395fc8969b3253395ce58d51b27781c7305376d494f0804b109a8b5'
          type: string
      responses:
        '200':
          description: Bridge transaction status and details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelayBridgeTransactionResponse'
        '429':
          description: Rate limit exceeded
      tags:
      - relay
components:
  schemas:
    RelayRequestData:
      type: object
      properties:
        status:
          type: string
          description: Relay request status
          example: success
          enum:
          - success
          - failure
          - refund
          - pending
          - depositing
          - waiting
        user:
          type: string
          description: User address that initiated the bridge
          example: '0x1234567890123456789012345678901234567890'
        recipient:
          type: string
          description: Recipient address on destination chain
          example: '0x1234567890123456789012345678901234567890'
        inTxs:
          description: Source chain transactions
          type: array
          items:
            $ref: '#/components/schemas/RelayTx'
        outTxs:
          description: Destination chain transactions
          type: array
          items:
            $ref: '#/components/schemas/RelayTx'
        currency:
          description: Currency being bridged
          allOf:
          - $ref: '#/components/schemas/RelayCurrencyInfo'
        fees:
          description: Fee breakdown in wei
          allOf:
          - $ref: '#/components/schemas/RelayFees'
        feesUsd:
          description: Fee breakdown in USD
          allOf:
          - $ref: '#/components/schemas/RelayFees'
        failReason:
          type: string
          description: Reason for failure if the bridge failed
          example: EXECUTION_REVERTED
        createdAt:
          type: string
          description: When the relay request was created
          example: '2024-01-15T12:00:00Z'
        updatedAt:
          type: string
          description: When the relay request was last updated
          example: '2024-01-15T12:05:00Z'
      required:
      - status
    RelayBridgeTransactionResponse:
      type: object
      properties:
        sourceChainId:
          type: number
          description: Source chain ID where the Relay message was sent from
          example: 1
        sourceTxHash:
          type: string
          description: Source chain transaction hash
          example: '0x80f1faf0652a5618ea1de0fc5142418e380676b3c6c74d482cfac1237638d6d4'
        destinationChainId:
          type: number
          description: Destination chain ID where the Relay message was delivered
          example: 8453
        destinationTxHash:
          type: string
          description: Destination chain transaction hash (if message was delivered)
          example: '0x9a3e6a8a52b82a1f4b523b0d50be133df0ad9407814b32e42d67119e1ae1947d'
        status:
          type: string
          description: Overall bridge status
          enum:
          - pending
          - inflight
          - delivered
          - failed
          - unknown
        relayRequest:
          description: Relay API request data with fee breakdown and status details
          allOf:
          - $ref: '#/components/schemas/RelayRequestData'
        ensoSourceEvent:
          description: Enso shortcut event from source chain (ShortcutExecuted + execution result). Null if not found.
          nullable: true
          allOf:
          - $ref: '#/components/schemas/EnsoEvent'
        ensoDestinationEvent:
          description: Enso shortcut event from destination chain (ShortcutExecuted + execution result). Null if not found.
          nullable: true
          allOf:
          - $ref: '#/components/schemas/EnsoEvent'
        error:
          type: string
          description: Error message if the API request failed (e.g., transaction not found, API errors)
          example: Transaction receipt not found for 0x...
      required:
      - sourceChainId
      - sourceTxHash
      - status
    RelayCurrencyInfo:
      type: object
      properties:
        chainId:
          type: number
          description: Chain ID of the currency
          example: 1
        address:
          type: string
          description: Token contract address
          example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
        symbol:
          type: string
          description: Token symbol
          example: USDC
        name:
          type: string
          description: Token name
          example: USD Coin
        decimals:
          type: number
          description: Token decimals
          example: 6
      required:
      - chainId
      - address
      - symbol
      - name
      - decimals
    RelayTx:
      type: object
      properties:
        hash:
          type: string
          description: Transaction hash
          example: '0x80f1faf0652a5618ea1de0fc5142418e380676b3c6c74d482cfac1237638d6d4'
        chainId:
          type: number
          description: Chain ID
          example: 8453
        block:
          type: number
          description: Block number
          example: 12345678
        timestamp:
          type: number
          description: Transaction timestamp (unix seconds)
          example: 1700000000
        status:
          type: string
          description: Transaction status
          example: success
      required:
      - hash
      - chainId
    EnsoEvent:
      type: object
      properties:
        accountId:
          type: string
          description: Account ID from ShortcutExecuted event
        requestId:
          type: string
          description: Request ID from ShortcutExecuted event
        blockNumber:
          type: number
          description: Block number where the event was emitted
        transactionHash:
          type: string
          description: Transaction hash
        chainId:
          type: number
          description: Chain ID where the event was emitted
        success:
          type: boolean
          description: Whether the shortcut execution was successful
        error:
          type: string
          description: Error data if execution failed
        refundDetails:
          description: Refund details if execution failed and funds were returned
          allOf:
          - $ref: '#/components/schemas/RefundDetails'
      required:
      - blockNumber
      - transactionHash
      - chainId
      - success
    RelayFees:
      type: object
      properties:
        gas:
          type: string
          description: Estimated gas cost in wei
          example: '50000000000000'
        fixed:
          type: string
          description: Fixed fee in wei
          example: '0'
        price:
          type: string
          description: Dynamic fee from chain and amount in wei
          example: '100000'
        gateway:
          type: string
          description: Fee taken by API gateway in wei
          example: '0'
      required:
      - gas
      - fixed
      - price
    RefundDetails:
      type: object
      properties:
        token:
          type: string
          description: Token address (0xeee... for native token)
        amount:
          type: string
          description: Amount refunded
        recipient:
          type: string
          description: Recipient address
        isNative:
          type: boolean
          description: Whether the refund is in native token
      required:
      - token
      - amount
      - recipient
      - isNative
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: apiKey
      type: http