openapi: 3.1.1
info:
  title: Delora API
  description: Delora API
  version: 1.0.0
servers:
  - url: https://api.delora.build
security: []
paths:
  /v1/quotes:
    get:
      operationId: getQuote
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: senderAddress
          required: true
          in: query
          description: Sender wallet address on the origin chain.
          schema:
            example: '0x1111111111111111111111111111111111111111'
            type: string
        - name: receiverAddress
          required: false
          in: query
          description: Receiver wallet address. Defaults to `senderAddress` for same chain-type routes (`EVM -> EVM` or `SVM -> SVM`) and is required when crossing chain types (`EVM -> SVM` or `SVM -> EVM`).
          schema:
            example: '0x2222222222222222222222222222222222222222'
            type: string
        - name: originChainId
          required: true
          in: query
          description: Origin chain ID.
          schema:
            example: 8453
            type: number
        - name: destinationChainId
          required: true
          in: query
          description: Destination chain ID.
          schema:
            example: 8453
            type: number
        - name: amount
          required: true
          in: query
          description: Exact input amount in token base units as a positive integer string, before Delora and integrator fees.
          schema:
            example: '1000000'
            type: string
        - name: originCurrency
          required: true
          in: query
          description: Origin token address, or native asset marker supported by the backend.
          schema:
            example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            type: string
        - name: destinationCurrency
          required: true
          in: query
          description: Destination token address, or native asset marker supported by the backend.
          schema:
            example: '0x4200000000000000000000000000000000000006'
            type: string
        - name: integrator
          required: false
          in: query
          description: Integrator identifier used for fee attribution. Required when `fee` is provided.
          schema:
            example: partner-app
            type: string
        - name: fee
          required: false
          in: query
          description: Optional integrator fee fraction taken from the input amount. `0.01` means 1%. Must be between `0` and `0.1` inclusive and can be provided only with `integrator`.
          schema:
            minimum: 0
            maximum: 0.1
            example: 0.01
            type: number
        - name: slippage
          required: false
          in: query
          description: Optional slippage fraction. `0.005` means 0.5%.
          schema:
            minimum: 0
            maximum: 1
            example: 0.005
            type: number
        - name: includeBridges
          required: false
          in: query
          description: Comma-separated bridge adapter keys from `/v1/tools` to include, for example `RELAY,ACROSS`. Only bridge-capable or multi-capability adapters are valid.
          schema:
            example: RELAY,ACROSS
            type: string
        - name: includeExchanges
          required: false
          in: query
          description: Comma-separated exchange adapter keys from `/v1/tools` to include, for example `OPENOCEAN,OKX`. Only exchange-capable or multi-capability adapters are valid.
          schema:
            example: OPENOCEAN,OKX
            type: string
        - name: excludeBridges
          required: false
          in: query
          description: Comma-separated bridge adapter keys from `/v1/tools` to exclude, for example `RELAY,ACROSS`. Only bridge-capable or multi-capability adapters are valid.
          schema:
            example: RELAY,ACROSS
            type: string
        - name: excludeExchanges
          required: false
          in: query
          description: Comma-separated exchange adapter keys from `/v1/tools` to exclude, for example `OPENOCEAN,OKX`. Only exchange-capable or multi-capability adapters are valid.
          schema:
            example: OPENOCEAN,OKX
            type: string
      responses:
        '200':
          description: Best executable quote response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponseDto'
              examples:
                success:
                  summary: Executable quote response
                  value:
                    inputAmount: '1000000'
                    outputAmount: '997321'
                    minOutputAmount: '992334'
                    adapter: OPENOCEAN
                    calldata:
                      to: '0x1111111111111111111111111111111111111111'
                      value: '0x0'
                      data: '0xabcdef'
                    fees:
                      total:
                        amount: '2679'
                        currencySymbol: USDC
                        currencyAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        chainId: 8453
                        decimals: 6
                      breakdown:
                        - type: gas
                          amount: '2679'
                          currencySymbol: USDC
                          currencyAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                          chainId: 8453
                          decimals: 6
                          amountUsd: '0.01'
                      totalUsd: '0.01'
                    gas:
                      gasPrice: '0x3b9aca00'
                      maxFeePerGas: '0x59682f00'
                      maxPriorityFeePerGas: '0x3b9aca00'
                    warnings:
                      - code: SOLANA_INSUFFICIENT_BALANCE
                        message: Solana simulation reported insufficient balance.
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                validationErrors:
                  summary: Validation errors
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Invalid request parameters
                    details:
                      message:
                        - senderAddress should not be empty
                        - senderAddress must be a string
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
      summary: Get the best executable quote
      tags:
        - V1
      description: Returns the best available route for an exact-input transfer or swap, including estimated output, executable calldata, fee breakdown, optional gas data, and non-blocking warnings.
  /v1/advanced/routes:
    post:
      operationId: getAdvancedRoutes
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvancedRoutesRequestDto'
            examples:
              routeDiscovery:
                summary: Discover advanced routes
                value:
                  senderAddress: '0x1111111111111111111111111111111111111111'
                  receiverAddress: '0x2222222222222222222222222222222222222222'
                  originChainId: 8453
                  destinationChainId: 42161
                  amount: '1000000'
                  originCurrency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                  destinationCurrency: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                  includeBridges: RELAY
                  maxRoutes: 2
      responses:
        '200':
          description: Ranked advanced route plans.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvancedRoutesResponseDto'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '422':
          description: No advanced route could be built for the requested transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/advanced/routes
      summary: Discover advanced route plans
      tags:
        - Advanced
      description: Returns ranked route plans with explicit steps. These routes are estimates; call `/v1/advanced/stepTransaction` for each selected step to get live executable transaction data.
  /v1/advanced/stepTransaction:
    post:
      operationId: getAdvancedStepTransaction
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdvancedStepTransactionRequestDto'
            examples:
              firstStep:
                summary: Populate a selected route step
                value:
                  step:
                    id: advanced-route:0
                    routeId: advanced-route
                    type: bridge
                    tool: RELAY
                    action:
                      fromChainId: 8453
                      toChainId: 42161
                      fromToken:
                        address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        symbol: USDC
                        decimals: 6
                        chainId: 8453
                      toToken:
                        address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
                        symbol: USDC
                        decimals: 6
                        chainId: 42161
                      fromAmount: '1000000'
                    estimate:
                      fromAmount: '1000000'
                      toAmount: '997321'
                      toAmountMin: '992334'
                      fees:
                        total:
                          amount: '0'
                          currencySymbol: USDC
                          currencyAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                          chainId: 8453
                        breakdown: []
                    execution:
                      applyFee: true
                  context:
                    senderAddress: '0x1111111111111111111111111111111111111111'
                    receiverAddress: '0x2222222222222222222222222222222222222222'
      responses:
        '200':
          description: Populated advanced step with executable transaction data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulatedAdvancedStepDto'
        '400':
          description: Invalid step payload or no quote for the selected step.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/advanced/stepTransaction
      summary: Populate an advanced route step transaction
      tags:
        - Advanced
      description: Re-quotes the selected step and returns executable transaction data. For later steps, pass the actual previous step output as `context.previousStepReceivedAmount`.
  /v1/chains:
    get:
      operationId: getChains
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: chainTypes
          required: false
          in: query
          description: 'Comma-separated chain types to include. Supported values: EVM, SVM.'
          schema:
            example: EVM,SVM
            type: string
      responses:
        '200':
          description: Supported chains response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainsResponseDto'
              examples:
                success:
                  summary: Supported chains response
                  value:
                    chains:
                      - key: base
                        name: Base
                        chainType: EVM
                        id: 8453
                        idHex: '0x2105'
                        mainnet: true
                        logoURI: https://example.com/base.png
                        tokenlistUrl: https://tokens.example.com/base.json
                        multicallAddress: '0xcA11bde05977b3631167028862bE2a173976CA11'
                        rpcUrls:
                          - https://mainnet.base.org
                        blockExplorerUrls: https://basescan.org
                        nativeToken:
                          address: '0x0000000000000000000000000000000000000000'
                          decimals: 18
                          symbol: ETH
                          chainId: 8453
                          coinKey: ETH
                          name: Ether
                          logoURI: https://example.com/eth.png
                        DeloraDiamond: '0x1111111111111111111111111111111111111111'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                validationErrors:
                  summary: Validation errors
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Invalid request parameters
                    details:
                      message:
                        - senderAddress should not be empty
                        - senderAddress must be a string
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
                invalidChainTypes:
                  summary: Invalid chainTypes filter
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: 'Invalid "chainTypes" query parameter. Allowed values: EVM, SVM.'
                    details:
                      message: 'Invalid "chainTypes" query parameter. Allowed values: EVM, SVM.'
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/tokens?chainTypes=aaa
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
      summary: List supported chains
      tags:
        - V1
      description: Returns the chains supported by Delora. Use the optional chainTypes query parameter to filter by EVM or SVM networks.
  /v1/tools:
    get:
      operationId: getTools
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: chains
          required: false
          in: query
          description: Comma-separated chain IDs used to filter supported tools.
          schema:
            example: 1,8453
      responses:
        '200':
          description: Supported tools response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolsResponseDto'
              examples:
                success:
                  summary: Supported tools response
                  value:
                    exchanges:
                      - key: OPENOCEAN
                        name: OpenOcean
                        logoURI: https://example.com/openocean.png
                        supportedChains:
                          - '1'
                          - '8453'
                    bridges:
                      - key: RELAY
                        name: Relay
                        logoURI: https://example.com/relay.png
                        supportedChains:
                          - '1'
                          - '8453'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                validationErrors:
                  summary: Validation errors
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Invalid request parameters
                    details:
                      message:
                        - senderAddress should not be empty
                        - senderAddress must be a string
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
      summary: List supported bridge and exchange tools
      tags:
        - V1
      description: Returns supported bridge and exchange adapters, grouped by type. Use the optional chains query parameter to filter tools by supported chain IDs.
  /v1/tokens:
    get:
      operationId: getTokens
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: chains
          required: false
          in: query
          description: Comma-separated chain IDs used to filter tokens.
          schema:
            example: 8453,1
            type: string
        - name: chainTypes
          required: false
          in: query
          description: 'Comma-separated chain types to include. Supported values: EVM, SVM.'
          schema:
            example: EVM,SVM
            type: string
      responses:
        '200':
          description: Tokens grouped by chain ID.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/TokenDto'
                example:
                  '8453':
                    - address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                      symbol: USDC
                      decimals: 6
                      chainId: 8453
                      name: USD Coin
                      coinKey: USDC
              examples:
                success:
                  summary: Tokens grouped by chain ID
                  value:
                    '8453':
                      - address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        symbol: USDC
                        decimals: 6
                        chainId: 8453
                        name: USD Coin
                        coinKey: USDC
                        priceUSD: '1.00'
                        priceUpdatedAt: '2026-06-22T12:00:00.000Z'
                        priceSource: dexscreener
                        priceStale: false
                        priceTier: cold
                        logoURI: https://example.com/usdc.png
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                validationErrors:
                  summary: Validation errors
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Invalid request parameters
                    details:
                      message:
                        - senderAddress should not be empty
                        - senderAddress must be a string
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
                invalidChainTypes:
                  summary: Invalid chainTypes filter
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: 'Invalid "chainTypes" query parameter. Allowed values: EVM, SVM.'
                    details:
                      message: 'Invalid "chainTypes" query parameter. Allowed values: EVM, SVM.'
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/tokens?chainTypes=aaa
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
      summary: List supported tokens grouped by chain ID
      tags:
        - V1
      description: Returns supported tokens grouped by chain ID. Use chains to limit the response to specific chain IDs and chainTypes to filter by EVM or SVM networks.
  /v1/prices:
    get:
      operationId: getPrices
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: chainId
          required: false
          in: query
          description: Chain ID for a single token price lookup. Required with `token` when `tokens` is not provided.
          schema:
            example: '8453'
            type: string
        - name: token
          required: false
          in: query
          description: Token address or symbol for a single token price lookup. Required with `chainId` when `tokens` is not provided.
          schema:
            example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            type: string
        - name: tokens
          required: false
          in: query
          description: Comma-separated batch of `chainId:token` entries. Maximum 50 requested entries. When provided, `tokens` is used instead of the single-token `chainId` and `token` parameters.
          schema:
            example: '8453:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913,1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
            type: string
      responses:
        '200':
          description: Token price snapshot response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPricesResponseDto'
              examples:
                success:
                  summary: Token price snapshots
                  value:
                    prices:
                      - chainId: 8453
                        token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                        priceUSD: '1.00'
                        source: dexscreener
                        updatedAt: '2026-06-22T12:00:00.000Z'
                        stale: false
                        tier: hot
                        refreshing: false
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                missingTokenRequest:
                  summary: Missing token request
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Either tokens=chainId:token,... or both chainId and token are required.
                    details:
                      message: Either tokens=chainId:token,... or both chainId and token are required.
                    timestamp: '2026-06-22T12:00:00.000Z'
                    path: /v1/prices
                tooManyTokens:
                  summary: Too many token price requests
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Too many token price requests. Max is 50.
                    details:
                      message: Too many token price requests. Max is 50.
                    timestamp: '2026-06-22T12:00:00.000Z'
                    path: /v1/prices
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/prices
      summary: Get token price snapshots
      tags:
        - V1
      description: Returns cached token price snapshots for one token or up to 50 requested token entries. Stale prices are returned immediately and marked with `stale` and `refreshing` metadata when a background refresh is scheduled.
  /v1/token:
    get:
      operationId: getToken
      parameters:
        - name: x-api-key
          in: header
          description: Optional API key for higher rate limits and fee rules.
          required: false
          schema:
            type: string
        - name: chain
          required: true
          in: query
          description: Chain ID or chain key, for example `8453` or `sol`.
          schema:
            example: '8453'
            type: string
        - name: token
          required: true
          in: query
          description: Token address or symbol.
          schema:
            example: USDC
            type: string
      responses:
        '200':
          description: Token metadata response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDto'
              examples:
                success:
                  summary: Token metadata response
                  value:
                    address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
                    symbol: USDC
                    decimals: 6
                    chainId: 8453
                    name: USD Coin
                    coinKey: USDC
                    priceUSD: '1.00'
                    priceUpdatedAt: '2026-06-22T12:00:00.000Z'
                    priceSource: dexscreener
                    priceStale: false
                    priceTier: cold
                    logoURI: https://example.com/usdc.png
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                validationErrors:
                  summary: Validation errors
                  value:
                    statusCode: 400
                    code: VALIDATION_ERROR
                    message: Invalid request parameters
                    details:
                      message:
                        - senderAddress should not be empty
                        - senderAddress must be a string
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
        '404':
          description: Token was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                tokenNotFound:
                  summary: Token not found
                  value:
                    statusCode: 404
                    code: NOT_FOUND
                    message: Requested resource was not found
                    details:
                      message: Requested resource was not found
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/token?chain=8453&token=UNKNOWN
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
              examples:
                rateLimitExceeded:
                  summary: Rate limit exceeded
                  value:
                    statusCode: 429
                    code: RATE_LIMIT
                    message: Rate limit exceeded. Please try again later.
                    details:
                      message: Rate limit exceeded. Please try again later.
                    timestamp: '2026-05-15T16:58:45.603Z'
                    path: /v1/quotes
      summary: Find one token by chain and address or symbol
      tags:
        - V1
      description: Returns metadata for a single token on a specific chain. The token query parameter can be a token address or symbol.
  /v1/transactions:
    get:
      operationId: listTransactions
      summary: List tracked transactions for the authenticated integrator
      description: Returns an asynchronously materialized transaction-tracking page. The API key determines the integrator scope; the optional integrator parameter is only a same-scope assertion.
      tags:
        - Transaction Tracking
      security:
        - api-key: []
      parameters:
        - name: x-api-key
          in: header
          required: true
          description: Customer API key. Required for Transaction Tracking endpoints.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          description: Opaque cursor returned by a prior response. Pass it through unchanged.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            example: 50
        - name: integrator
          in: query
          required: false
          description: Optional assertion of the integrator associated with the API key. It cannot be used to select another integrator.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by current tracking status.
          schema:
            $ref: '#/components/schemas/ScannerStatus'
        - name: routeType
          in: query
          required: false
          description: Filter by route type.
          schema:
            $ref: '#/components/schemas/ScannerRouteType'
        - name: sourceChainId
          in: query
          required: false
          description: Filter by canonical source chain ID.
          schema:
            type: integer
            example: 8453
        - name: destChainId
          in: query
          required: false
          description: Filter by canonical destination chain ID.
          schema:
            type: integer
            example: 42161
      responses:
        '200':
          description: A page of transactions ordered newest first by source timestamp.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerTransactionListResponseDto'
        '400':
          description: Invalid list parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '403':
          description: The optional integrator parameter is outside the API key scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '503':
          description: Transaction Tracking service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
  /v1/transactions/{lookupKey}:
    get:
      operationId: getTransactionByLookupKey
      summary: Get one tracked transaction by transaction ID or hash
      description: Finds a transaction by Delora transactionId, source hash, or destination hash within the integrator associated with the API key.
      tags:
        - Transaction Tracking
      security:
        - api-key: []
      parameters:
        - name: x-api-key
          in: header
          required: true
          description: Customer API key. Required for Transaction Tracking endpoints.
          schema:
            type: string
        - name: lookupKey
          in: path
          required: true
          description: Delora transactionId, source transaction hash, or destination transaction hash.
          schema:
            type: string
            example: '0x596a6d35655f3d2d334abcffb6b69999b82d5661f18692ea24174589894a7d30'
      responses:
        '200':
          description: Tracked transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerTransactionResponseDto'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '404':
          description: No transaction is available for the lookup key in the current integrator scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '503':
          description: Transaction Tracking service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
  /v1/transactions/{lookupKey}/status:
    get:
      operationId: getTransactionStatus
      summary: Get the lightweight current status of a tracked transaction
      description: Returns the latest status stored by Delora's asynchronous tracking workers. It does not trigger an on-demand provider lookup.
      tags:
        - Transaction Tracking
      security:
        - api-key: []
      parameters:
        - name: x-api-key
          in: header
          required: true
          description: Customer API key. Required for Transaction Tracking endpoints.
          schema:
            type: string
        - name: lookupKey
          in: path
          required: true
          description: Delora transactionId, source transaction hash, or destination transaction hash.
          schema:
            type: string
            example: '0x596a6d35655f3d2d334abcffb6b69999b82d5661f18692ea24174589894a7d30'
      responses:
        '200':
          description: Lightweight transaction status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScannerTransactionStatusResponseDto'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '404':
          description: No transaction is available for the lookup key in the current integrator scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
        '503':
          description: Transaction Tracking service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponseDto'
  /health:
    get:
      operationId: health
      parameters: []
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponseDto'
              examples:
                ok:
                  summary: Healthy service
                  value:
                    status: ok
      summary: Health check
      tags:
        - Health
      description: Returns the current service health status.
tags:
  - name: Health
    description: Service health endpoints.
  - name: V1
    description: Routing and metadata endpoints.
  - name: Transaction Tracking
    description: Read-only, integrator-scoped transaction tracking.
components:
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Delora API key. Required by Transaction Tracking endpoints and optional for most routing endpoints.
  schemas:
    TokenDto:
      type: object
      properties:
        address:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        symbol:
          type: string
          example: USDC
        decimals:
          type: number
          example: 6
        chainId:
          type: number
          example: 8453
        name:
          type: string
          example: USD Coin
        coinKey:
          type: string
          example: USDC
        priceUSD:
          type: string
          example: '1.00'
          description: Cached USD price as a decimal string, when available.
        priceUpdatedAt:
          type: string
          example: '2026-06-22T12:00:00.000Z'
          description: Timestamp of the cached token price, when available.
        priceSource:
          type: string
          example: dexscreener
          description: Price source used for the cached token price, when available.
        priceStale:
          type: boolean
          example: false
          description: Whether the cached token price is outside Delora's freshness window.
        priceTier:
          type: string
          enum:
            - hot
            - cold
          example: cold
          description: Price refresh tier. `hot` tokens are prioritized for fresher cached prices; `cold` tokens refresh less aggressively.
        logoURI:
          type: string
          example: https://example.com/usdc.png
      required:
        - address
        - symbol
        - decimals
        - chainId
        - name
        - coinKey
    QuoteCalldataDto:
      type: object
      properties:
        to:
          type: string
          example: '0x1111111111111111111111111111111111111111'
        value:
          type: string
          example: '0x0'
        data:
          type: string
          example: '0xabcdef'
      required:
        - to
        - value
        - data
    ParsedFeesTotalCurrencyDto:
      type: object
      properties:
        amount:
          type: string
          example: '2679'
        currencySymbol:
          type: string
          example: USDC
        currencyAddress:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        chainId:
          type: number
          example: 8453
        decimals:
          type: number
          example: 6
      required:
        - amount
        - currencySymbol
        - currencyAddress
        - chainId
    ParsedFeesBreakdownItemDto:
      type: object
      properties:
        amount:
          type: string
          example: '2679'
        currencySymbol:
          type: string
          example: USDC
        currencyAddress:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        chainId:
          type: number
          example: 8453
        decimals:
          type: number
          example: 6
        type:
          type: string
          enum:
            - gas
            - relayer
            - relayerGas
            - relayerService
            - capital
            - lp
            - app
            - total
          example: gas
        amountUsd:
          type: string
          example: '0.01'
      required:
        - amount
        - currencySymbol
        - currencyAddress
        - chainId
        - type
    ParsedFeesDto:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/ParsedFeesTotalCurrencyDto'
        breakdown:
          type: array
          items:
            $ref: '#/components/schemas/ParsedFeesBreakdownItemDto'
        totalUsd:
          type: string
          example: '0.01'
      required:
        - total
        - breakdown
    GasEstimationDto:
      type: object
      properties:
        gasPrice:
          type: string
          example: '0x3b9aca00'
        maxFeePerGas:
          type: string
          example: '0x59682f00'
        maxPriorityFeePerGas:
          type: string
          example: '0x3b9aca00'
    QuoteWarningDto:
      type: object
      properties:
        code:
          type: string
          enum:
            - INTEGRATOR_SOLANA_WALLET_NOT_ACTIVATED_FEE_SKIPPED
            - INTEGRATOR_WALLET_NOT_CONFIGURED_FEE_SKIPPED
            - SOLANA_SYSTEM_ACCOUNT_SKIPPED
            - SOLANA_INSUFFICIENT_BALANCE
            - SOLANA_SIMULATION_FAILED
          example: SOLANA_INSUFFICIENT_BALANCE
        message:
          type: string
          example: Solana simulation reported insufficient balance.
      required:
        - code
        - message
    TokenPriceResultDto:
      type: object
      properties:
        chainId:
          type: number
          example: 8453
        token:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        priceUSD:
          type: string
          example: '1.00'
          description: Cached USD price as a decimal string, when available.
        source:
          type: string
          example: dexscreener
          description: Price source used for this cached value, when available.
        updatedAt:
          type: string
          example: '2026-06-22T12:00:00.000Z'
          description: Timestamp of the cached token price, when available.
        stale:
          type: boolean
          example: false
          description: Whether this cached value is outside Delora's freshness window.
        tier:
          type: string
          enum:
            - hot
            - cold
          example: hot
          description: Price refresh tier. `hot` entries are prioritized for fresher cached prices; `cold` entries refresh less aggressively.
        refreshing:
          type: boolean
          example: false
          description: Whether a background refresh for this price is scheduled or already running.
      required:
        - chainId
        - token
        - stale
        - tier
        - refreshing
    TokenPricesResponseDto:
      type: object
      properties:
        prices:
          type: array
          items:
            $ref: '#/components/schemas/TokenPriceResultDto'
      required:
        - prices
    QuoteUsdPricesDto:
      type: object
      properties:
        originCurrency:
          $ref: '#/components/schemas/TokenPriceResultDto'
        destinationCurrency:
          $ref: '#/components/schemas/TokenPriceResultDto'
      required:
        - originCurrency
        - destinationCurrency
    SimulationDeviationDto:
      type: object
      properties:
        absolute:
          type: string
          example: '-1200'
          description: Simulated output minus advertised output in raw units.
        bps:
          type: number
          example: -12
          description: Signed basis points. Negative means the adapter overstated output.
        percent:
          type: string
          example: '-0.12%'
      required:
        - absolute
        - bps
        - percent
    SimulationProviderResultDto:
      type: object
      properties:
        source:
          type: string
          enum:
            - TENDERLY
            - RPC
            - SOLANA_RUNTIME
            - NONE
          example: TENDERLY
        executionStatus:
          type: string
          enum:
            - SUCCESS
            - REVERTED
            - TIMEOUT
            - SKIPPED
            - UNSUPPORTED
            - ERROR
          example: SUCCESS
        outputValidation:
          type: string
          enum:
            - VERIFIED
            - UNVERIFIABLE
            - NOT_SIMULATED
          example: VERIFIED
        simulatedOutputAmount:
          type: string
          example: '996100'
        deviation:
          $ref: '#/components/schemas/SimulationDeviationDto'
        gasUsed:
          type: string
          example: '142331'
        reason:
          type: string
          example: Exceeded 700ms
        latencyMs:
          type: number
          example: 312
      required:
        - source
        - executionStatus
        - outputValidation
        - latencyMs
    SimulationDto:
      type: object
      properties:
        source:
          type: string
          enum:
            - TENDERLY
            - RPC
            - SOLANA_RUNTIME
            - NONE
          example: TENDERLY
        executionStatus:
          type: string
          enum:
            - SUCCESS
            - REVERTED
            - TIMEOUT
            - SKIPPED
            - UNSUPPORTED
            - ERROR
          example: SUCCESS
        outputValidation:
          type: string
          enum:
            - VERIFIED
            - UNVERIFIABLE
            - NOT_SIMULATED
          example: VERIFIED
        simulatedOutputAmount:
          type: string
          example: '996100'
        advertisedOutputAmount:
          type: string
          example: '997321'
        deviation:
          $ref: '#/components/schemas/SimulationDeviationDto'
        gasUsed:
          type: string
          example: '142331'
        reason:
          type: string
          example: Simulation exceeded budget
        latencyMs:
          type: number
          example: 712
        providerResults:
          type: array
          items:
            $ref: '#/components/schemas/SimulationProviderResultDto'
      required:
        - source
        - executionStatus
        - outputValidation
        - advertisedOutputAmount
        - latencyMs
        - providerResults
    QuoteResponseDto:
      type: object
      properties:
        inputAmount:
          type: string
          example: '1000000'
        outputAmount:
          type: string
          example: '997321'
        minOutputAmount:
          type: string
          example: '992334'
        estimatedTimeSec:
          type: number
          example: 120
          description: Estimated bridge completion time in seconds. Returned only for bridge routes.
        adapter:
          enum:
            - ACROSS
            - RELAY
            - GASZIP
            - OPENOCEAN
            - JUPITER
            - SYMBIOSIS
            - MAYAN
            - MAYAN_WORMHOLE
            - MAYAN_SWIFT
            - MAYAN_MCTP
            - MAYAN_FAST_MCTP
            - OKX
            - RISE
            - NORDSTERN
            - KYBERSWAP
            - DFLOW
            - NEAR_INTENTS
          type: string
          example: OPENOCEAN
        calldata:
          $ref: '#/components/schemas/QuoteCalldataDto'
        fees:
          $ref: '#/components/schemas/ParsedFeesDto'
        gas:
          $ref: '#/components/schemas/GasEstimationDto'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/QuoteWarningDto'
        approvalAddress:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: Approval spender address for EVM-origin routes.
        transactionSize:
          type: object
          properties:
            raw:
              type: number
              example: 812
            encoded:
              type: number
              example: 1084
          description: Serialized Solana transaction size when available.
        bridgeScan:
          $ref: '#/components/schemas/BridgeScanMetadataDto'
          description: Bridge tracking metadata returned when the selected bridge adapter provides it.
        simulation:
          $ref: '#/components/schemas/SimulationDto'
          description: Best-effort transaction simulation metadata returned when simulation is enabled for the selected route.
        usd:
          $ref: '#/components/schemas/QuoteUsdPricesDto'
          description: Cached USD price snapshots for the origin and destination quote tokens.
      required:
        - inputAmount
        - outputAmount
        - adapter
        - calldata
        - fees
    AdvancedRoutesRequestDto:
      type: object
      properties:
        senderAddress:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: Sender wallet address on the origin chain.
        receiverAddress:
          type: string
          example: '0x2222222222222222222222222222222222222222'
          description: Receiver wallet address. Defaults to `senderAddress` for same chain-type routes (`EVM -> EVM` or `SVM -> SVM`) and is required when crossing chain types (`EVM -> SVM` or `SVM -> EVM`).
        originChainId:
          type: number
          example: 8453
          description: Origin chain ID.
        destinationChainId:
          type: number
          example: 42161
          description: Destination chain ID.
        amount:
          type: string
          example: '1000000'
          description: Exact input amount in token base units as a positive integer string, before Delora and integrator fees.
        originCurrency:
          type: string
          example: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
          description: Origin token address, or native asset marker supported by the backend.
        destinationCurrency:
          type: string
          example: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831'
          description: Destination token address, or native asset marker supported by the backend.
        integrator:
          type: string
          example: partner-app
          description: Integrator identifier used for fee attribution. Required when `fee` is provided.
        fee:
          type: number
          minimum: 0
          maximum: 0.1
          example: 0.01
          description: Optional integrator fee fraction taken from the input amount. `0.01` means 1%. Must be between `0` and `0.1` inclusive and can be provided only with `integrator`.
        slippage:
          type: number
          minimum: 0
          maximum: 1
          example: 0.005
          description: Optional slippage fraction. `0.005` means 0.5%.
        includeBridges:
          type: string
          description: Comma-separated bridge adapter keys from `/v1/tools` to include. Only bridge-capable or multi-capability adapters are valid.
          example: RELAY,ACROSS
        includeExchanges:
          type: string
          description: Comma-separated exchange adapter keys from `/v1/tools` to include. Only exchange-capable or multi-capability adapters are valid.
          example: OPENOCEAN,OKX
        excludeBridges:
          type: string
          description: Comma-separated bridge adapter keys from `/v1/tools` to exclude. Only bridge-capable or multi-capability adapters are valid.
          example: MAYAN_FAST_MCTP
        excludeExchanges:
          type: string
          description: Comma-separated exchange adapter keys from `/v1/tools` to exclude. Only exchange-capable or multi-capability adapters are valid.
          example: OKX
        maxRoutes:
          type: number
          minimum: 1
          example: 2
          description: Maximum number of ranked advanced routes to return.
      required:
        - senderAddress
        - originChainId
        - destinationChainId
        - amount
        - originCurrency
        - destinationCurrency
    AdvancedTokenRefDto:
      type: object
      properties:
        address:
          type: string
        symbol:
          type: string
        decimals:
          type: number
        chainId:
          type: number
      required:
        - address
        - symbol
        - decimals
        - chainId
    AdvancedStepActionDto:
      type: object
      properties:
        fromChainId:
          type: number
        toChainId:
          type: number
        fromToken:
          $ref: '#/components/schemas/AdvancedTokenRefDto'
        toToken:
          $ref: '#/components/schemas/AdvancedTokenRefDto'
        fromAmount:
          type: string
        slippage:
          type: number
        fromAddress:
          type: string
        toAddress:
          type: string
      required:
        - fromChainId
        - toChainId
        - fromToken
        - toToken
        - fromAmount
    AdvancedStepEstimateDto:
      type: object
      properties:
        fromAmount:
          type: string
        quoteFromAmount:
          type: string
        toAmount:
          type: string
        toAmountMin:
          type: string
        estimatedTimeSec:
          type: number
        fees:
          $ref: '#/components/schemas/ParsedFeesDto'
        approvalAddress:
          type: string
        simulatedToAmount:
          type: string
        simulation:
          $ref: '#/components/schemas/SimulationDto'
      required:
        - fromAmount
        - toAmount
        - toAmountMin
        - fees
    AdvancedStepExecutionOptionsDto:
      type: object
      properties:
        applyFee:
          type: boolean
        requiresPreviousStepAmount:
          type: boolean
        quoteRequest:
          type: object
          additionalProperties: true
        routeRequest:
          type: object
          additionalProperties: true
      required:
        - applyFee
    BridgeScanMetadataDto:
      type: object
      additionalProperties: true
    AdvancedTransactionRequestDto:
      type: object
      properties:
        to:
          type: string
        data:
          type: string
        value:
          type: string
        gas:
          $ref: '#/components/schemas/GasEstimationDto'
        transactionSize:
          type: object
          properties:
            raw:
              type: number
            encoded:
              type: number
      required:
        - to
        - value
    AdvancedRouteStepDto:
      type: object
      properties:
        id:
          type: string
        routeId:
          type: string
        type:
          type: string
          enum:
            - swap
            - bridge
        tool:
          type: string
          example: RELAY
        action:
          $ref: '#/components/schemas/AdvancedStepActionDto'
        estimate:
          $ref: '#/components/schemas/AdvancedStepEstimateDto'
          description: Estimated result for this route step. Treat it as planning data; call `POST /v1/advanced/stepTransaction` before execution.
        integrator:
          type: string
        fee:
          type: number
        execution:
          $ref: '#/components/schemas/AdvancedStepExecutionOptionsDto'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/QuoteWarningDto'
        bridgeScan:
          $ref: '#/components/schemas/BridgeScanMetadataDto'
          description: Bridge tracking metadata returned when the selected bridge adapter provides it.
        transactionRequest:
          $ref: '#/components/schemas/AdvancedTransactionRequestDto'
          description: Executable transaction payload returned on a populated step from `POST /v1/advanced/stepTransaction`.
      required:
        - id
        - routeId
        - type
        - tool
        - action
        - estimate
        - execution
    AdvancedRouteDto:
      type: object
      properties:
        id:
          type: string
        routeKind:
          type: string
          enum:
            - single-step
            - multistep
        inputAmount:
          type: string
        outputAmount:
          type: string
        minOutputAmount:
          type: string
        estimatedTimeSec:
          type: number
        fees:
          $ref: '#/components/schemas/ParsedFeesDto'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/QuoteWarningDto'
        adapter:
          type: string
          example: RELAY
        isMultistep:
          type: boolean
        steps:
          type: array
          description: Ordered route steps. Pass the selected step to `POST /v1/advanced/stepTransaction` immediately before signing.
          items:
            $ref: '#/components/schemas/AdvancedRouteStepDto'
        simulation:
          $ref: '#/components/schemas/SimulationDto'
      required:
        - id
        - routeKind
        - inputAmount
        - outputAmount
        - minOutputAmount
        - fees
        - adapter
        - isMultistep
        - steps
    AdvancedRoutesResponseDto:
      type: object
      properties:
        routes:
          type: array
          description: Ranked route plans. Each route contains one or more estimated steps.
          items:
            $ref: '#/components/schemas/AdvancedRouteDto'
      required:
        - routes
    AdvancedExecutionContextDto:
      type: object
      properties:
        senderAddress:
          type: string
          description: Wallet address that signs and submits this step.
        receiverAddress:
          type: string
          description: Final receiver wallet address for the route.
        amountOverride:
          type: string
          description: Optional manual input amount override for this live step quote.
        previousStepReceivedAmount:
          type: string
          description: Actual output amount received from the previous step, in token base units. Use this for second and later steps so the next step is hydrated with the live received amount.
        slippage:
          type: number
          minimum: 0
          maximum: 1
          description: Optional slippage override for this live step quote. `0.005` means 0.5%.
      required:
        - senderAddress
        - receiverAddress
    AdvancedStepTransactionRequestDto:
      type: object
      properties:
        step:
          $ref: '#/components/schemas/AdvancedRouteStepDto'
          description: Step object from a route returned by `POST /v1/advanced/routes`.
        context:
          $ref: '#/components/schemas/AdvancedExecutionContextDto'
          description: Runtime wallet and amount context used to re-quote and populate the selected step.
      required:
        - step
        - context
    PopulatedAdvancedStepDto:
      allOf:
        - $ref: '#/components/schemas/AdvancedRouteStepDto'
        - type: object
          properties:
            transactionRequest:
              $ref: '#/components/schemas/AdvancedTransactionRequestDto'
          required:
            - transactionRequest
    ScannerStatus:
      type: string
      enum:
        - success
        - recovered
        - bridge_pending
        - refund_pending
        - refunded
        - bridge_failed
        - unknown
      description: Current asynchronous tracking status.
    ScannerRouteType:
      type: string
      enum:
        - bridge
        - swap
        - bridge_swap
        - unknown
      description: Delora route classification.
    ScannerStatusSource:
      type: string
      enum:
        - analytics
        - receipt
        - bridge_api
        - mixed
        - unknown
      description: Source or combination of sources used for the current status.
    ScannerProtocolRawChainId:
      oneOf:
        - type: integer
        - type: string
        - type: 'null'
      description: Provider-specific chain identifier preserved for diagnostics.
    ScannerTokenAmountDto:
      type: object
      properties:
        chainId:
          type:
            - integer
            - 'null'
          description: Canonical token chain ID when available.
        address:
          type:
            - string
            - 'null'
        symbol:
          type:
            - string
            - 'null'
        amountRaw:
          type: string
          description: Token amount in base units, represented as a decimal string.
          example: '1000000'
        amountFormatted:
          type:
            - string
            - 'null'
          description: Human-readable token amount when decimals are available.
        decimals:
          type:
            - integer
            - 'null'
        amountUsd:
          type:
            - string
            - 'null'
          description: Best-effort USD value as a decimal string.
      required:
        - chainId
        - address
        - symbol
        - amountRaw
        - amountFormatted
        - decimals
        - amountUsd
    ScannerFeeAmountDto:
      type: object
      properties:
        token:
          type:
            - string
            - 'null'
        amountRaw:
          type: string
          description: Fee amount in base units, represented as a decimal string.
          example: '21000000000000'
        amountFormatted:
          type:
            - string
            - 'null'
        decimals:
          type:
            - integer
            - 'null'
        amountUsd:
          type:
            - string
            - 'null'
          description: Best-effort USD value as a decimal string.
      required:
        - token
        - amountRaw
        - amountFormatted
        - decimals
        - amountUsd
    ScannerProviderDiagnosticDto:
      description: Provider-specific diagnostic payload. Its shape is not a stable public contract.
      oneOf:
        - type: object
          additionalProperties: true
        - type: array
          items: {}
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
    ScannerTransactionResponseDto:
      type: object
      description: A read-only transaction-tracking record. Nullable enrichment fields mean unavailable or not yet enriched, not zero.
      properties:
        id:
          type: string
          description: Delora tracking record ID.
          example: '123'
        transactionId:
          type:
            - string
            - 'null'
          description: Delora transaction identifier when available.
        sourceTxHash:
          type: string
        destTxHash:
          type:
            - string
            - 'null'
        sourceBlockNumber:
          type:
            - integer
            - 'null'
        sourceLogIndex:
          type:
            - integer
            - 'null'
        sourceChainId:
          type: integer
          description: Source chain ID stored for the transaction.
        destChainId:
          type:
            - integer
            - 'null'
          description: Normalized destination chain ID when available.
        canonicalSourceChainId:
          type: integer
          description: Canonical source chain ID used for filtering.
        canonicalDestChainId:
          type:
            - integer
            - 'null'
          description: Canonical destination chain ID used for filtering.
        protocolRawSourceChainId:
          $ref: '#/components/schemas/ScannerProtocolRawChainId'
        protocolRawDestChainId:
          $ref: '#/components/schemas/ScannerProtocolRawChainId'
        sourceNetwork:
          type: string
        destNetwork:
          type:
            - string
            - 'null'
        date:
          type: string
          format: date-time
          description: Legacy alias of sourceBlockTimestamp.
        sourceBlockTimestamp:
          type: string
          format: date-time
        destinationBlockTimestamp:
          type:
            - string
            - 'null'
          format: date-time
        sender:
          type:
            - string
            - 'null'
        receiver:
          type:
            - string
            - 'null'
        integrator:
          type:
            - string
            - 'null'
        protocol:
          type: string
          description: Normalized bridge adapter or GENERIC_SWAP. Treat unknown values as forward-compatible.
          example: RELAY
        routeType:
          $ref: '#/components/schemas/ScannerRouteType'
        hasDestCall:
          type: boolean
        inputToken:
          oneOf:
            - $ref: '#/components/schemas/ScannerTokenAmountDto'
            - type: 'null'
        outputToken:
          oneOf:
            - $ref: '#/components/schemas/ScannerTokenAmountDto'
            - type: 'null'
        sourceGasFee:
          oneOf:
            - $ref: '#/components/schemas/ScannerFeeAmountDto'
            - type: 'null'
        destinationGasFee:
          oneOf:
            - $ref: '#/components/schemas/ScannerFeeAmountDto'
            - type: 'null'
        integratorFee:
          oneOf:
            - $ref: '#/components/schemas/ScannerFeeAmountDto'
            - type: 'null'
        deloraFee:
          oneOf:
            - $ref: '#/components/schemas/ScannerFeeAmountDto'
            - type: 'null'
        status:
          $ref: '#/components/schemas/ScannerStatus'
        substatus:
          type:
            - string
            - 'null'
          description: Provider-specific supplementary status. Not a stable enum.
        statusSource:
          $ref: '#/components/schemas/ScannerStatusSource'
        bridgeScanUrl:
          type:
            - string
            - 'null'
          format: uri
        rawBridgeStatus:
          $ref: '#/components/schemas/ScannerProviderDiagnosticDto'
        lastReceiptCheckedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of the scanner's most recent receipt-check attempt. Diagnostic only; it does not prove settlement or finality.
        lastBridgeCheckedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of the scanner's most recent bridge-status check attempt. Diagnostic only; it does not prove settlement or finality.
        lastBridgeSuccessCheckedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of a non-unknown bridge-provider result. Despite its name, it does not by itself mean the bridge settled successfully.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - transactionId
        - sourceTxHash
        - destTxHash
        - sourceBlockNumber
        - sourceLogIndex
        - sourceChainId
        - destChainId
        - canonicalSourceChainId
        - canonicalDestChainId
        - protocolRawSourceChainId
        - protocolRawDestChainId
        - sourceNetwork
        - destNetwork
        - date
        - sourceBlockTimestamp
        - destinationBlockTimestamp
        - sender
        - receiver
        - integrator
        - protocol
        - routeType
        - hasDestCall
        - inputToken
        - outputToken
        - sourceGasFee
        - destinationGasFee
        - integratorFee
        - deloraFee
        - status
        - substatus
        - statusSource
        - bridgeScanUrl
        - rawBridgeStatus
        - lastReceiptCheckedAt
        - lastBridgeCheckedAt
        - lastBridgeSuccessCheckedAt
        - createdAt
        - updatedAt
    ScannerTransactionListResponseDto:
      type: object
      properties:
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/ScannerTransactionResponseDto'
        nextCursor:
          type:
            - string
            - 'null'
          description: Opaque cursor for the next page, or null when there are no more records.
      required:
        - transactions
        - nextCursor
    ScannerTransactionStatusResponseDto:
      type: object
      properties:
        id:
          type: string
        transactionId:
          type:
            - string
            - 'null'
        sourceTxHash:
          type: string
        destTxHash:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/ScannerStatus'
        substatus:
          type:
            - string
            - 'null'
        statusSource:
          $ref: '#/components/schemas/ScannerStatusSource'
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - transactionId
        - sourceTxHash
        - destTxHash
        - status
        - substatus
        - statusSource
        - updatedAt
    StandardErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        code:
          enum:
            - NO_AVAILABLE_QUOTES
            - AMOUNT_TOO_LOW
            - WRONG_ADDRESS
            - RATE_LIMIT
            - SLIPPAGE_EXCEEDED
            - ADAPTER_BAD_REQUEST
            - ADAPTER_UNAUTHORIZED
            - ADAPTER_INTERNAL
            - VALIDATION_ERROR
            - NOT_FOUND
            - UNKNOWN
          type: string
          description: |-
            Machine-readable Delora error code.
            - NO_AVAILABLE_QUOTES: No bridge or exchange adapter returned an executable quote for the requested transfer.
            - AMOUNT_TOO_LOW: The requested input amount is below the minimum supported by the available bridge route.
            - WRONG_ADDRESS: A wallet address is missing, malformed, or incompatible with the requested chain type.
            - RATE_LIMIT: The request exceeded the configured rate limit.
            - SLIPPAGE_EXCEEDED: The expected output amount fell below the route's permitted minimum.
            - ADAPTER_BAD_REQUEST: An upstream bridge or exchange adapter rejected the request as invalid.
            - ADAPTER_UNAUTHORIZED: An upstream bridge or exchange adapter rejected the request because credentials are missing or invalid.
            - ADAPTER_INTERNAL: An upstream bridge or exchange adapter failed with an internal error.
            - VALIDATION_ERROR: The request failed Delora API validation, including invalid query parameters, body fields, or address formats.
            - NOT_FOUND: The requested chain, token, or resource was not found.
            - UNKNOWN: The request failed with an unexpected error that does not map to a more specific code.
          x-enumDescriptions:
            - No bridge or exchange adapter returned an executable quote for the requested transfer.
            - The requested input amount is below the minimum supported by the available bridge route.
            - A wallet address is missing, malformed, or incompatible with the requested chain type.
            - The request exceeded the configured rate limit.
            - The expected output amount fell below the route's permitted minimum.
            - An upstream bridge or exchange adapter rejected the request as invalid.
            - An upstream bridge or exchange adapter rejected the request because credentials are missing or invalid.
            - An upstream bridge or exchange adapter failed with an internal error.
            - The request failed Delora API validation, including invalid query parameters, body fields, or address formats.
            - The requested chain, token, or resource was not found.
            - The request failed with an unexpected error that does not map to a more specific code.
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid request parameters
        details:
          description: Optional error details. When details is an object, `message` can be either a string or an array of strings.
          oneOf:
            - type: object
              additionalProperties: true
              properties:
                message:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                  description: Human-readable details. Validation errors may return multiple messages.
                errorCode:
                  type: string
                code:
                  oneOf:
                    - type: string
                    - type: number
                status:
                  oneOf:
                    - type: string
                    - type: number
            - type: string
            - type: array
              items:
                type: string
          example:
            message:
              - One or more request parameters are invalid.
        timestamp:
          type: string
          example: '2026-05-13T18:00:00.000Z'
        path:
          type: string
          example: /v1/...
      required:
        - statusCode
        - code
        - message
        - timestamp
    NativeTokenDto:
      type: object
      properties:
        address:
          type: string
          example: '0x0000000000000000000000000000000000000000'
        decimals:
          type: number
          example: 18
        symbol:
          type: string
          example: ETH
        chainId:
          type: number
          example: 8453
        coinKey:
          type: string
          example: ETH
        name:
          type: string
          example: Ether
        logoURI:
          type: string
          example: https://example.com/eth.png
      required:
        - address
        - decimals
        - symbol
        - chainId
        - coinKey
        - name
        - logoURI
    ChainInfoDto:
      type: object
      properties:
        key:
          type: string
          example: base
        name:
          type: string
          example: Base
        chainType:
          type: string
          enum:
            - EVM
            - SVM
          example: EVM
        id:
          type: number
          example: 8453
        idHex:
          type: string
          example: '0x2105'
        mainnet:
          type: boolean
          example: true
        logoURI:
          type: string
          example: https://example.com/base.png
        tokenlistUrl:
          type: string
          example: https://tokens.example.com/base.json
        multicallAddress:
          type: string
          example: '0xcA11bde05977b3631167028862bE2a173976CA11'
        rpcUrls:
          example:
            - https://mainnet.base.org
          type: array
          items:
            type: string
        blockExplorerUrls:
          type: string
          example: https://basescan.org
        nativeToken:
          $ref: '#/components/schemas/NativeTokenDto'
        DeloraDiamond:
          type: string
          example: '0x1111111111111111111111111111111111111111'
      required:
        - key
        - name
        - chainType
        - id
        - idHex
        - mainnet
        - logoURI
        - rpcUrls
        - blockExplorerUrls
        - nativeToken
    ChainsResponseDto:
      type: object
      properties:
        chains:
          type: array
          items:
            $ref: '#/components/schemas/ChainInfoDto'
      required:
        - chains
    ToolInfoDto:
      type: object
      properties:
        key:
          enum:
            - ACROSS
            - RELAY
            - GASZIP
            - OPENOCEAN
            - JUPITER
            - SYMBIOSIS
            - MAYAN
            - MAYAN_WORMHOLE
            - MAYAN_SWIFT
            - MAYAN_MCTP
            - MAYAN_FAST_MCTP
            - OKX
            - RISE
            - NORDSTERN
            - KYBERSWAP
            - DFLOW
            - NEAR_INTENTS
          type: string
          example: RELAY
        name:
          type: string
          example: Relay
        logoURI:
          type: string
          example: https://example.com/relay.png
        supportedChains:
          example:
            - '1'
            - '8453'
          type: array
          items:
            type: string
      required:
        - key
        - name
        - logoURI
        - supportedChains
    ToolsResponseDto:
      type: object
      properties:
        exchanges:
          type: array
          items:
            $ref: '#/components/schemas/ToolInfoDto'
        bridges:
          type: array
          items:
            $ref: '#/components/schemas/ToolInfoDto'
      required:
        - exchanges
        - bridges
    HealthResponseDto:
      type: object
      properties:
        status:
          type: string
          example: ok
      required:
        - status