openapi: 3.2.0
info:
  description: The Stablecoin Payment Network
  title: Iron API - Sandbox Exchange Rate API
  version: 1.0-16988
servers:
- url: https://api.sandbox.iron.xyz/api
tags:
- description: Operations on Exchange Rate
  name: Exchange Rate
paths:
  /exchange-rate:
    get:
      description: Get the exchange rate from a source currency to a destination currency for a customer with effective rate and fees
      operationId: getExchangeRate
      parameters:
      - deprecated: false
        description: customer id
        explode: false
        in: query
        name: customer_id
        required: false
        schema:
          default: null
          format: uuid
          type: string
      - deprecated: false
        description: source currency code
        explode: true
        in: query
        name: source_currency_code
        required: true
        schema:
          maxLength: 32
          type: string
      - deprecated: false
        description: source currency type
        explode: true
        in: query
        name: source_currency_type
        required: true
        schema:
          $ref: '#/components/schemas/CurrencyType'
      - deprecated: false
        description: source currency chain
        explode: true
        in: query
        name: source_currency_chain
        required: false
        schema:
          $ref: '#/components/schemas/Blockchain'
      - deprecated: false
        description: destination currency code
        explode: true
        in: query
        name: destination_currency_code
        required: true
        schema:
          maxLength: 32
          type: string
      - deprecated: false
        description: destination currency type
        explode: true
        in: query
        name: destination_currency_type
        required: true
        schema:
          $ref: '#/components/schemas/CurrencyType'
      - deprecated: false
        description: destination currency chain
        explode: true
        in: query
        name: destination_currency_chain
        required: false
        schema:
          $ref: '#/components/schemas/Blockchain'
      - deprecated: false
        description: amount
        explode: true
        in: query
        name: amount
        required: true
        schema:
          format: decimal
          type: string
      - deprecated: true
        description: partner fee in bips
        explode: true
        in: query
        name: _partner_fee_in_bips
        required: false
        schema:
          format: uint64
          type: integer
      - $ref: '#/components/parameters/XApiVersion'
      responses:
        '200':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ExchangeRate'
          description: The exchange rate response
        '400':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: The bad request response
        '401':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: The unauthorized response
        '404':
          content:
            application/json; charset=utf-8:
              schema:
                type: string
          description: The not found response
        '500':
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The internal server error response
      security:
      - ApiKeyAuth: []
      summary: Get exchange rate
      tags:
      - Exchange Rate
components:
  schemas:
    ExchangeRate:
      description: 'Exchange Rate


        The exchange rate for a given currency pair

        '
      properties:
        effective_rate:
          description: The effective rate
          format: decimal
          type: string
        fee:
          $ref: '#/components/schemas/Fee'
        from:
          $ref: '#/components/schemas/Currency'
        out_amount:
          $ref: '#/components/schemas/Amount'
        to:
          $ref: '#/components/schemas/Currency'
      required:
      - from
      - to
      - out_amount
      - effective_rate
      - fee
      title: ExchangeRate
      type: object
    Currency_Fiat:
      allOf:
      - properties:
          type:
            enum:
            - Fiat
            example: Fiat
            type: string
        required:
        - type
        type: object
      - $ref: '#/components/schemas/Fiat'
      description: 'Currency


        Can be either crypto or fiat

        '
    NetworkFee:
      anyOf:
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      - $ref: '#/components/schemas/NetworkFee_Amount'
      description: 'Network Fee


        The network fee for a given currency. This is deprecated and will be removed in the future. Use NetworkFeeWithSettlement instead.

        '
      discriminator:
        mapping:
          AchIn: '#/components/schemas/NetworkFee_Amount'
          AchOut: '#/components/schemas/NetworkFee_Amount'
          CitreaGas: '#/components/schemas/NetworkFee_Amount'
          EthereumGas: '#/components/schemas/NetworkFee_Amount'
          RailFee: '#/components/schemas/NetworkFee_Amount'
          SepaIn: '#/components/schemas/NetworkFee_Amount'
          SepaOut: '#/components/schemas/NetworkFee_Amount'
          SolanaTransactionFee: '#/components/schemas/NetworkFee_Amount'
          StellarTransactionFee: '#/components/schemas/NetworkFee_Amount'
          SwiftIn: '#/components/schemas/NetworkFee_Amount'
          SwiftOut: '#/components/schemas/NetworkFee_Amount'
          WireIn: '#/components/schemas/NetworkFee_Amount'
          WireOut: '#/components/schemas/NetworkFee_Amount'
        propertyName: type
      type: object
    Blockchain:
      description: 'Blockchain


        A type of blockchain

        '
      enum:
      - Solana
      - Ethereum
      - Polygon
      - Arbitrum
      - Base
      - Stellar
      - Citrea
      - Plasma
      - Avalanche
      - Moca
      - Tempo
      - Tron
      - Bsc
      type: string
    NetworkFeeWithSettlement:
      description: 'Network Fee with Settlement


        The network fee with settlement for a given currency

        '
      properties:
        fee_amount:
          $ref: '#/components/schemas/Amount'
        fee_type:
          $ref: '#/components/schemas/NetworkFeeType'
        settlement:
          $ref: '#/components/schemas/FeeSettlement'
      required:
      - fee_type
      - fee_amount
      title: NetworkFeeWithSettlement
      type: object
    PartnerFee:
      description: 'Partner Fee


        A partner fee

        '
      properties:
        fee:
          $ref: '#/components/schemas/Amount'
        label:
          description: The label of the partner fee
          type: string
        settlement:
          $ref: '#/components/schemas/FeeSettlement'
      required:
      - label
      - fee
      - settlement
      title: PartnerFee
      type: object
    PaymentNetwork:
      description: 'PaymentNetwork


        A payment network

        '
      enum:
      - Sepa
      - Swift
      - Fps
      - Chats
      - Ach
      - Wire
      - Rtp
      - Fednow
      - Pix
      - Spei
      - AfricanBankTransfer
      - MobileMoney
      - Chaps
      type: string
    Amount:
      description: 'An amount of money

        '
      example:
        amount: '100.5'
        currency:
          code: USD
          type: Fiat
      properties:
        amount:
          description: The amount, a decimal number
          format: decimal
          type: string
        currency:
          $ref: '#/components/schemas/Currency'
      required:
      - amount
      - currency
      title: Amount
      type: object
    NetworkFee_Amount:
      allOf:
      - properties:
          type:
            enum:
            - SwiftOut
            example: SwiftOut
            type: string
        required:
        - type
        type: object
      - $ref: '#/components/schemas/Amount'
      description: 'Network Fee


        The network fee for a given currency. This is deprecated and will be removed in the future. Use NetworkFeeWithSettlement instead.

        '
    FeeSettlement:
      description: 'Fee Settlement


        The settlement type for the fee

        '
      enum:
      - deductedImmediately
      - settledLater
      type: string
    CurrencyType:
      description: 'Currency Type


        The type of currency

        '
      enum:
      - fiat
      - crypto
      type: string
    Fiat:
      description: A fiat currency
      example:
        code: USD
      properties:
        code:
          description: The code of the currency e.g. 'USD'
          type: string
      required:
      - code
      title: Fiat
      type: object
    Fee:
      description: 'Fee


        The fee for a given currency pair

        '
      properties:
        banking_fee:
          $ref: '#/components/schemas/Amount'
        banking_fee_network:
          $ref: '#/components/schemas/PaymentNetwork'
        deducted_fee:
          allOf:
          - $ref: '#/components/schemas/Amount'
          - deprecated: true
            description: The amount of the fee that was deducted immediately and charged to the end customer. This is deprecated and will be removed in the future. Use transaction_fee instead.
          deprecated: true
          description: The amount of the fee that was deducted immediately and charged to the end customer. This is deprecated and will be removed in the future. Use transaction_fee instead.
        iron_fee:
          $ref: '#/components/schemas/Amount'
        iron_fee_settlement:
          $ref: '#/components/schemas/FeeSettlement'
        network_fee:
          $ref: '#/components/schemas/Amount'
        network_fees:
          deprecated: true
          description: The network fees in source currency
          items:
            $ref: '#/components/schemas/NetworkFee'
          type: array
        network_fees_with_settlement:
          description: The network fees with settlement
          items:
            $ref: '#/components/schemas/NetworkFeeWithSettlement'
          type: array
        partner_fee:
          $ref: '#/components/schemas/Amount'
        partner_fees:
          description: The partner fees
          items:
            $ref: '#/components/schemas/PartnerFee'
          type: array
        total_fee:
          $ref: '#/components/schemas/Amount'
        transaction_fee:
          $ref: '#/components/schemas/Amount'
      required:
      - total_fee
      - iron_fee
      - partner_fee
      - network_fees
      - network_fees_with_settlement
      - partner_fees
      - transaction_fee
      - banking_fee
      - network_fee
      title: Fee
      type: object
    Crypto:
      description: A cryptocurrency
      example:
        blockchain: Solana
        token: USDC
      properties:
        blockchain:
          $ref: '#/components/schemas/Blockchain'
        token:
          description: The ticker of the token e.g. 'USDC'
          type: string
      required:
      - token
      - blockchain
      title: Crypto
      type: object
    NetworkFeeType:
      description: 'Network Fee Type


        The type of network fee

        '
      enum:
      - SepaIn
      - SepaOut
      - EthereumGas
      - CitreaGas
      - SolanaTransactionFee
      - StellarTransactionFee
      - PolygonGas
      - BaseGas
      - AvalancheGas
      - TronGas
      - BscGas
      - RailFee
      - AchIn
      - AchOut
      - WireIn
      - WireOut
      - SwiftIn
      - SwiftOut
      - FpsIn
      - FpsOut
      - ChapsIn
      - ChapsOut
      - RtpIn
      - RtpOut
      - FednowIn
      - FednowOut
      type: string
    ApiError:
      description: 'Standard error response returned to API clients for server errors.

        Includes a trace_id that clients can reference when reporting issues.'
      properties:
        message:
          description: Human-readable error message
          type: string
        trace_id:
          description: Trace ID that can be used to look up request details in logs
          type: string
      required:
      - message
      - trace_id
      title: ApiError
      type: object
    Currency:
      anyOf:
      - $ref: '#/components/schemas/Currency_Crypto'
      - $ref: '#/components/schemas/Currency_Fiat'
      description: 'Currency


        Can be either crypto or fiat

        '
      discriminator:
        mapping:
          Crypto: '#/components/schemas/Currency_Crypto'
          Fiat: '#/components/schemas/Currency_Fiat'
        propertyName: type
      type: object
    Currency_Crypto:
      allOf:
      - properties:
          type:
            enum:
            - Crypto
            example: Crypto
            type: string
        required:
        - type
        type: object
      - $ref: '#/components/schemas/Crypto'
      description: 'Currency


        Can be either crypto or fiat

        '
  parameters:
    XApiVersion:
      description: 'Selects the API version for this request, as an ISO date (`YYYY-MM-DD`). Omit to use the default version (`2025-03-13`). Supported versions: 2025-03-13, 2026-07-01.'
      in: header
      name: X-API-Version
      required: false
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      description: API Key
      in: header
      name: X-API-Key
      type: apiKey