openapi: 3.0.0
info:
  title: Hifi Account Offramp API
  version: 2.0.0
  description: API documentation for Hifi
servers:
- url: https://production.hifibridge.com
  description: Production server
- url: https://sandbox.hifibridge.com
  description: Sandbox server
security:
- bearerAuth: []
tags:
- name: Offramp
  description: Offramp endpoints
paths:
  /v2/offramps:
    post:
      summary: Create an offramp
      description: "\nAn offramp facilitates the conversion of crypto to fiat. Once the crypto transfer is confirmed, HIFI will deposit the converted fiat into the receiving user’s bank account. \n\nThere are two types of offramp:\n\n* **Quote-based offramp**: This type of offramp first returns the conversion rate quote based on the best market rate, which you can accept through the [Accept an offramp quote](https://docs.hifibridge.com/api-reference/offramp/accept-an-offramp-quote) endpoint to initiate the offramp.  \n To learn more about quote-based offramps, click [here](https://docs.hifibridge.com/guides/transfers/onramps/usd-usdc).\n\n* **Non-quote-based offramp**: This type of offramp will be initiated immediately upon creating an offramp.\n"
      tags:
      - Offramp
      requestBody:
        $ref: '#/components/requestBodies/CreateOfframpBody'
      responses:
        '200':
          $ref: '#/components/responses/CryptoToFiatTransferResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
    get:
      summary: List all offramps
      description: 'Returns a list of offramps associated with a user under your organization. The offramps are returned sorted by creation date, with the most recent offramps appearing first.

        '
      tags:
      - Offramp
      parameters:
      - $ref: '#/components/parameters/UserIdOptionalParameter'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/CreatedBeforeParameter'
      - $ref: '#/components/parameters/CreatedAfterParameter'
      responses:
        '200':
          $ref: '#/components/responses/CryptoToFiatAllRecordsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/offramps/{transferId}:
    get:
      summary: Retrieve an offramp
      description: Retrieves an offramp.
      tags:
      - Offramp
      parameters:
      - $ref: '#/components/parameters/OfframpRecordIDPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/CryptoToFiatRecordResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/offramps/{transferId}/quote/accept:
    post:
      summary: Accept an offramp quote
      description: 'Accept and initiate a quote-based offramp.


        For example, an offramp from crypto currency `usdc` to fiat currency `brl` is quote-based so its initial status will be `OPEN_QUOTE`. After reviewing the offramp conversion rate quote information, you can accept it to initialize the offramp.

        '
      tags:
      - Offramp
      parameters:
      - $ref: '#/components/parameters/OfframpRecordIDPathParameter'
      responses:
        '200':
          $ref: '#/components/responses/CryptoToFiatAcceptQuoteResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
  /v2/offramps/rates:
    get:
      summary: Retrieve an offramp rate
      description: 'Offramp rates are estimated rates for offramp conversions from different cryptocurrencies on different networks into all the different fiat currencies.

        '
      tags:
      - Offramp
      parameters:
      - $ref: '#/components/parameters/FromCryptoCurrencyParameter'
      - $ref: '#/components/parameters/ToFiatCurrencyParameter'
      responses:
        '200':
          $ref: '#/components/responses/CryptoToFiatConversionRateResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  schemas:
    CreateMexicoGlobalNetworkOfframp:
      type: object
      title: Offramp Global Network (MXN)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - invoice_payments
          - payment_for_services
          - payment_for_software
          - payment_for_imported_goods
          - travel_services
          - transfer_to_own_account
          - repayment_of_loans
          - payroll
          - payment_of_property_rental
          - information_service_charges
          - advertising_and_public_relations
          - royalty_and_ip_fees
          - financial_service_fees
          - advisory_and_consulting_fees
          - representative_office_expenses
          - tax_payment
          - transportation_fees
          - construction_costs
          - insurance_premium
          - offline_goods_trade
          - insurance_claims
          - remittance_to_family_or_friends
          - education_expenses
          - medical_treatment
          - donations
          - mutual_fund_investment
          - currency_exchange
          - advance_payment_for_goods
          - merchant_settlement
          - repatriation_fund_settlement
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/MxnOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    CreateChinaGlobalNetworkOfframp:
      type: object
      title: Offramp Global Network (CHN)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - invoice_payments
          - payment_for_services
          - payment_for_software
          - payment_for_imported_goods
          - travel_services
          - transfer_to_own_account
          - repayment_of_loans
          - payroll
          - payment_of_property_rental
          - information_service_charges
          - advertising_and_public_relations
          - royalty_and_ip_fees
          - financial_service_fees
          - advisory_and_consulting_fees
          - representative_office_expenses
          - tax_payment
          - transportation_fees
          - construction_costs
          - insurance_premium
          - offline_goods_trade
          - insurance_claims
          - remittance_to_family_or_friends
          - education_expenses
          - medical_treatment
          - donations
          - mutual_fund_investment
          - currency_exchange
          - advance_payment_for_goods
          - merchant_settlement
          - repatriation_fund_settlement
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/ChinaOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    OfframpConversionRateObject:
      type: object
      properties:
        fromCurrency:
          type: string
          enum:
          - usdc
          description: source currency
        toCurrency:
          type: string
          enum:
          - usd
          - brl
          - mxn
          - ugx
          - ngn
          - kes
          - tzs
          - mwk
          - xaf
          - bwp
          - zar
          - usd-hka
          - usd-chn
          - cny
          - hkd
          - sgd
          - usd-sgp
          description: target currency
        conversionRate:
          type: string
        conversionRates:
          type: array
          items:
            type: object
            properties:
              transferType:
                type: string
                description: when `transferType` is `default`, this is the conversion rate for the default transfer type
              conversionRate:
                type: string
      example:
        fromCurrency: usdc
        toCurrency: usd
        conversionRate: '1'
        conversionRates:
        - transferType: default
          conversionRate: '1'
    CreateCopOfframp:
      type: object
      title: Offramp (COP)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/CopOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    AfricaOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          description: 'fiat currency.

            Look at the list of supported `currency` [here](https://docs.google.com/spreadsheets/d/1QxAWGoZMznB6_Ts4mzFcFD49ZOMUZNdNiR6wlr8NDL0/edit?gid=293141391#gid=293141391).

            Make sure the `currency` enum is supported for the provided `accountId`.

            '
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
      required:
      - currency
      - accountId
    CreateHongKongGlobalNetworkOfframp:
      type: object
      title: Offramp Global Network (HKD)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - invoice_payments
          - payment_for_services
          - payment_for_software
          - payment_for_imported_goods
          - travel_services
          - transfer_to_own_account
          - repayment_of_loans
          - payroll
          - payment_of_property_rental
          - information_service_charges
          - advertising_and_public_relations
          - royalty_and_ip_fees
          - financial_service_fees
          - advisory_and_consulting_fees
          - representative_office_expenses
          - tax_payment
          - transportation_fees
          - construction_costs
          - insurance_premium
          - offline_goods_trade
          - insurance_claims
          - remittance_to_family_or_friends
          - education_expenses
          - medical_treatment
          - donations
          - mutual_fund_investment
          - currency_exchange
          - advance_payment_for_goods
          - merchant_settlement
          - repatriation_fund_settlement
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/HongKongOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    HongKongOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - hkd
          - usd
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        paymentReference:
          type: string
          description: 'a reference message to include when offramping.

            '
      required:
      - currency
      - accountId
    OfframpAcceptedQuoteObject:
      $ref: '#/components/schemas/OfframpObject'
    OfframpAllRecordsObject:
      type: object
      properties:
        count:
          type: integer
        records:
          type: array
          items:
            $ref: '#/components/schemas/OfframpRecordObject'
        nextCursor:
          type: string
          description: The `createdAt` timestamp of the last record in the current page. Pass this as `createdBefore` in the next request to retrieve the next page of results.
    CreateBrazilGlobalNetworkOfframp:
      type: object
      title: Offramp Global Network (BRL)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - invoice_payments
          - payment_for_services
          - payment_for_software
          - payment_for_imported_goods
          - travel_services
          - transfer_to_own_account
          - repayment_of_loans
          - payroll
          - payment_of_property_rental
          - information_service_charges
          - advertising_and_public_relations
          - royalty_and_ip_fees
          - financial_service_fees
          - advisory_and_consulting_fees
          - representative_office_expenses
          - tax_payment
          - transportation_fees
          - construction_costs
          - insurance_premium
          - offline_goods_trade
          - insurance_claims
          - remittance_to_family_or_friends
          - education_expenses
          - medical_treatment
          - donations
          - mutual_fund_investment
          - currency_exchange
          - advance_payment_for_goods
          - merchant_settlement
          - repatriation_fund_settlement
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/BrlOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    OfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - usd
          - eur
          - brl
          - hkd
          - mxn
          - cop
          - ars
          - ngn
          - ugx
          - kes
          - zmw
          - mwk
          - rwf
          - tzs
          - xaf
          - xof
          - bwp
          - xaf
          - cdf
          - ghs
          - zar
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        sameDayAch:
          type: boolean
          default: false
          description: same day ACH offramp for a $1 additional fee
        achReference:
          type: string
          description: "a reference message to include when offramping through ACH transfer. \n\nit can be at most 10 characters, A-Z, a-z, 0-9, and spaces. Note that as of `2024-08-06`, setting this field is only supported for certain developers while we work on rolling out general support for everyone.\n"
        sepaReference:
          type: string
          description: "a reference message to include when offramping through SEPA transfer.  \n\nit must be between 6 to 140 characters. The allowed characters are a-z, A-Z, 0-9, spaces, ampersand (&), hyphen (-), full stop (.), and solidus (/).\n"
        wireMessage:
          type: string
          description: "a message to include when offramping through WIRE transfer. \n\nit can be at most 4 lines, each with a max length of 35 char according to the Fedwire standard.\n"
        paymentReference:
          type: string
          description: "a reference message to include when offramping. \n\nPlease utilize `wireMessage` for wire transfer and `achReference` for ACH transfer instead of this field.\n"
        swiftReference:
          type: string
          description: "a reference message or remittance information to include when offramping through SWIFT transfer. \n\nit can have at most 4 lines (separated by \"\\n\"), each line with a max length of 35 chars. The allowed characters are a-z, A-Z, 0-9, special characters (/ - ? : ( ) . , ' +), and spaces.\n"
        swiftCharges:
          type: string
          enum:
          - sha
          - our
      required:
      - currency
      - accountId
    MxnOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - mxn
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        paymentReference:
          type: string
          description: 'a reference message to include when offramping.

            '
      required:
      - currency
      - accountId
    InternalServerError:
      type: object
      properties:
        error:
          type: string
          example: Unexpected error happened
    CreateNigeriaGlobalNetworkOfframp:
      type: object
      title: Offramp Global Network (NGN)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - invoice_payments
          - payment_for_services
          - payment_for_software
          - payment_for_imported_goods
          - travel_services
          - transfer_to_own_account
          - repayment_of_loans
          - payroll
          - payment_of_property_rental
          - information_service_charges
          - advertising_and_public_relations
          - royalty_and_ip_fees
          - financial_service_fees
          - advisory_and_consulting_fees
          - representative_office_expenses
          - tax_payment
          - transportation_fees
          - construction_costs
          - insurance_premium
          - offline_goods_trade
          - insurance_claims
          - remittance_to_family_or_friends
          - education_expenses
          - medical_treatment
          - donations
          - mutual_fund_investment
          - currency_exchange
          - advance_payment_for_goods
          - merchant_settlement
          - repatriation_fund_settlement
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/NigeriaOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    BrlOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - brl
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        paymentReference:
          type: string
          description: 'a reference message to include when offramping.

            '
      required:
      - userId
      - currency
      - accountId
    DeveloperFee:
      type: object
      properties:
        fees:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - PERCENTAGE
                - FLAT
              value:
                type: string
                description: 'Fee amount as a string. For PERCENTAGE type, "0.0005" represents 0.05%.

                  For FLAT type, represents absolute amount.

                  For PERCENTAGE type, the value must be between 0 and 1 with max 4 decimal places.

                  '
              walletAddress:
                type: string
                description: Wallet address to receive the fee
            required:
            - type
            - value
            - walletAddress
      required:
      - fees
    ArsOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - ars
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
      required:
      - currency
      - accountId
    CreateMxnOfframp:
      type: object
      title: Offramp (MXN)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/MxnOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    OfframpRecordObject:
      $ref: '#/components/schemas/OfframpObject'
    CreateArsOfframp:
      type: object
      title: Offramp (ARS)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/ArsOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    NigeriaOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - ngn
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        paymentReference:
          type: string
          description: 'a reference message to include when offramping.

            '
      required:
      - currency
      - accountId
    OfframpDepositInstructionsList:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            format: uuid
          fromAddress:
            type: string
          toAddress:
            type: string
          currency:
            type: string
          contractAddress:
            type: string
          rawAmount:
            type: string
          amount:
            type: number
          chain:
            type: string
          collected:
            type: boolean
          collectable:
            type: boolean
          expiresAt:
            type: string
            format: date-time
          transactionHash:
            type: string
            nullable: true
    OfframpObject:
      type: object
      properties:
        transferType:
          type: string
        transferDetails:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: unique identifier for the offramp
            requestId:
              type: string
              format: uuid
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            status:
              $ref: '#/components/schemas/OfframpStatusEnum'
            failedReason:
              type: string
            source:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                chain:
                  type: string
                currency:
                  type: string
                amount:
                  type: number
                walletAddress:
                  type: string
                user:
                  type: object
                  properties:
                    email:
                      type: string
                    lastName:
                      type: string
                      nullable: true
                    firstName:
                      type: string
                      nullable: true
                    businessName:
                      type: string
                      nullable: true
            destination:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                amount:
                  type: number
                currency:
                  type: string
                user:
                  type: object
                  properties:
                    email:
                      type: string
                    lastName:
                      type: string
                      nullable: true
                    firstName:
                      type: string
                      nullable: true
                    businessName:
                      type: string
                      nullable: true
                accountId:
                  type: string
                  format: uuid
                  description: destination offramp account ID
                sameDayAch:
                  type: boolean
                  default: false
                  description: same day ACH offramp for a $1 additional fee
            receipt:
              type: object
              properties:
                transactionHash:
                  type: string
                  nullable: true
                paymentTracking:
                  $ref: '#/components/schemas/OfframpPaymentTrackingObject'
            developerFee:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: unique identifier for the developer fee record
                transactionHash:
                  type: string
                  nullable: true
                  description: transaction hash of the fee transfer
                fees:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - PERCENTAGE
                        - FLAT
                      value:
                        type: string
                        description: fee amount as string, for percentage represents decimal (e.g. "0.0005" = 0.05%)
                      amount:
                        type: string
                        description: actual fee amount charged
                      walletAddress:
                        type: string
                        description: wallet address receiving the fee
                    required:
                    - type
                    - value
                    - amount
                    - walletAddress
            quoteInformation:
              type: object
              properties:
                sendGross:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                sendNet:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                receiveGross:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                receiveNet:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                rate:
                  type: string
                expiresAt:
                  type: string
                  format: date-time
            depositInformation:
              $ref: '#/components/schemas/OfframpDepositInstructionsList'
    OfframpSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of crypto currency to send
        currency:
          type: string
          enum:
          - usdc
          - usdt
          - usdHifi
          description: 'crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)

            '
        chain:
          type: string
          enum:
          - POLYGON
          - ETHEREUM
          - SOLANA
          - BASE
        userId:
          type: string
          format: uuid
          description: user who is sending the crypto, required if `externalWalletId` is not provided
        externalWalletId:
          type: string
          format: uuid
          description: external wallet id who is sending the crypto, required if `userId` is not provided
      required:
      - currency
      - chain
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          example: Not authorized
    CopOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - cop
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
      required:
      - currency
      - accountId
    OfframpPaymentTrackingObject:
      type: object
      properties:
        fedBatchId:
          type: string
          description: Fedwire or ACH batch ID used for settlement tracking
        imad:
          type: string
          description: Input Messaging Accountability Data. A combination of a date, source identifier, and sequence number assigned to a Fedwire message when it is processed by the Federal Reserve Bank Funds Transfer application. Unique to the payment.
        omad:
          type: string
          description: Output Messaging Accountability Data. A combination of a date, destination identifier, and sequence number assigned to a Fedwire message when it is processed by the Federal Reserve Bank Funds Transfer application.
        traceNumber:
          type: string
          description: Unique ACH trace number for the transaction
        paymentRail:
          type: string
          enum:
          - wire
          - ach
          - rtp
          - swift
    ChinaOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - usd
          - cny
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        paymentReference:
          type: string
          description: 'a reference message to include when offramping.

            '
      required:
      - currency
      - accountId
    UsdOfframpDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to receive
        currency:
          type: string
          enum:
          - usd
          description: fiat currency
        accountId:
          type: string
          format: uuid
          description: account that is receiving the fiat currency
        userId:
          type: string
          format: uuid
          description: user who is receiving the fiat
        sameDayAch:
          type: boolean
          default: false
          description: same day ACH offramp for a $1 additional fee
        achReference:
          type: string
          description: "a reference message to include when offramping through ACH transfer. \n\nit can be at most 10 characters, A-Z, a-z, 0-9, and spaces. Note that as of `2024-08-06`, setting this field is only supported for certain developers while we work on rolling out general support for everyone.\n"
        wireMessage:
          type: string
          description: "a message to include when offramping through WIRE transfer. \n\nit can be at most 4 lines, each with a max length of 35 char according to the Fedwire standard.\n"
        swiftReference:
          type: string
          description: "A reference message to include when offramping through SWIFT transfer that is mainly use to indicate the purpose of payment. \n\nit can be at most 12 characters.\n"
      required:
      - currency
      - accountId
    CreateAfricaOfframp:
      type: object
      title: Offramp (Africa)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/AfricaOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
      - purposeOfPayment
    CreateBrlOfframp:
      type: object
      title: Offramp (BRL)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/BrlOfframpDestination'
        fee:
          type: object
          description: custom offramp fee, omit if no fee is charged
          nullable: true
          allOf:
          - $ref: '#/components/schemas/OfframpFee'
      required:
      - requestId
      - source
      - destination
    CreateUsdOfframp:
      type: object
      title: Offramp (USD)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        supportingDocumentType:
          type: string
          enum:
          - billing_document
          - order_document
          - shipment_document
          - regulatory_document
          - transport_document
          - other_document
          description: 'The type of supporting document, required for swift payment.

            '
        supportingDocumentUrl:
          type: string
          description: 'The URL of the supporting document, required for swift payment.

            '
        description:
          type: string
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/UsdOfframpDestination'
        developerFee:
          type: object
          description: custom offramp developer fee, omit if no developer fee is charged
          nullable: true
          $ref: '#/components/schemas/DeveloperFee'
      required:
      - requestId
      - source
      - destination
    OfframpStatusEnum:
      type: string
      enum:
      - NOT_INITIATED
      - CREATED
      - OPEN_QUOTE
      - CRYPTO_INITIATED
      - AWAITING_FUNDS
      - CRYPTO_PENDING
      - CRYPTO_PROCESSED
      - FIAT_INITIATED
      - FIAT_PENDING
      - COMPLETED
      - FIAT_FAILED
      - CRYPTO_RETURNED
      - CRYPTO_FAILED
      - QUOTE_FAILED
      - IN_REVIEW
      description: 'Refer to [here](https://docs.hifibridge.com/docs/transfers/offramps#transaction-status) for more details on each offramp status.

        '
    CreateOfframp:
      type: object
      title: Offramp
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        purposeOfPayment:
          type: string
          enum:
          - gift
          - bills
          - groceries
          - travel
          - health
          - entertainment
          - housing
          - school-fees
          - other
        supportingDocumentType:
          type: string
          enum:
          - billing_document
          - order_document
          - shipment_document
          - regulatory_document
          - transport_document
          - other_document
          description: 'The type of supporting document, required for swift payment.

            '
        supportingDocumentUrl:
          type: string
          description: 'The URL of the supporting document, required for swift payment.

            '
        description:
          type: string
          description: Memo code or description for usd offramp.
        source:
          type: object
          description: offramp source
          $ref: '#/components/schemas/OfframpSource'
        destination:
          type: object
          description: offramp destination
          $ref: '#/components/schemas/OfframpDestination'
        developerFee:
          type: array
          description: custom offramp fees, omit if no fees are charged
          nullable: true
          items:
            $ref: '#/components/schemas/DeveloperFee'
      required:
      - requestId
      - source
      - destination
  responses:
    CryptoToFiatAllRecordsResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OfframpAllRecordsObject'
          examples:
            OfframpObjectListExample:
              $ref: '#/components/examples/OfframpObjectListExample'
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
    NotFoundResponse:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                - error
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    CryptoToFiatTransferResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OfframpObject'
          examples:
            OfframpObjectUsdOpenQuoteExample:
              $ref: '#/components/examples/OfframpObjectUsdOpenQuoteExample'
    CryptoToFiatRecordResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OfframpRecordObject'
          examples:
            OfframpObjectUsdCompleteExample:
              $ref: '#/components/examples/OfframpObjectUsdCompleteExample'
    CryptoToFiatConversionRateResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OfframpConversionRateObject'
    CryptoToFiatAcceptQuoteResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OfframpAcceptedQuoteObject'
          examples:
            OfframpObjectUsdCryptoInitiatedExample:
              $ref: '#/components/examples/OfframpObjectUsdCryptoInitiatedExample'
  parameters:
    LimitParameter:
      name: limit
      in: query
      schema:
        type: string
        minimum: 1
        maximum: 100
      description: default to 10, maximum to 100
      required: false
    FromCryptoCurrencyParameter:
      name: fromCurrency
      in: query
      schema:
        type: string
        enum:
        - usdc
      required: true
    OfframpRecordIDPathParameter:
      name: transferId
      in: path
      schema:
        type: string
      description: Transfer record ID.
      required: true
    UserIdOptionalParameter:
      name: userId
      in: query
      schema:
        type: string
      description: The user ID.
      required: false
    CreatedBeforeParameter:
      name: createdBefore
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
    CreatedAfterParameter:
      name: createdAfter
      in: query
      schema:
        type: string
        format: date
      description: 'ISO format: YYYY-MM-DD'
      required: false
    ToFiatCurrencyParameter:
      name: toCurrency
      in: query
      schema:
        type: string
        enum:
        - usd
        - brl
        - mxn
        - ugx
        - ngn
        - kes
        - tzs
        - mwk
        - xaf
        - bwp
        - zar
        - usd-hka
        - usd-chn
        - cny
        - hkd
        - sgd
        - usd-sgp
      required: true
  examples:
    OfframpObjectUsdCryptoInitiatedExample:
      summary: Offramp Object (USD - CRYPTO_INITIATED)
      value:
        transferType: OFFRAMP
        transferDetails:
          id: 173c1e89-7bbd-4352-9e5d-73807681510d
          requestId: 201ca31d-700f-4c76-ac4b-961623acbb79
          createdAt: '2025-02-03T16:12:04.331652+00:00'
          updatedAt: '2025-02-03T16:12:08.732+00:00'
          status: CRYPTO_INITIATED
          failedReason: null
          source:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            chain: POLYGON
            currency: usdc
            amount: 10
            walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D6'
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
          destination:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            amount: 0
            currency: usd
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
            accountId: 12c1c496-8f57-41a1-8292-dbe6547791ce
          receipt:
            transactionHash: null
            paymentTracking: null
          developerFee:
            id: 1c3d24c1-6136-574c-a647-e7eb6a9fb6ed
            transactionHash: null
            fees:
            - type: PERCENTAGE
              value: '0.0005'
              amount: '0.000515'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
            - type: FLAT
              value: '0.01'
              amount: '0.010000'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
          quoteInformation:
            sendGross:
              amount: '10'
              currency: usdc
            sendNet:
              amount: '10'
              currency: usdc
            receiveGross:
              amount: '10'
              currency: usd
            receiveNet:
              amount: '10'
              currency: usd
            rate: '1'
          depositInformation: []
    OfframpObjectUsdOpenQuoteExample:
      summary: Offramp Object (USD - OPEN_QUOTE)
      value:
        transferType: OFFRAMP
        transferDetails:
          id: 173c1e89-7bbd-4352-9e5d-73807681510d
          requestId: 201ca31d-700f-4c76-ac4b-961623acbb79
          createdAt: '2025-02-03T16:12:04.331652+00:00'
          updatedAt: '2025-02-03T16:12:08.732+00:00'
          status: OPEN_QUOTE
          failedReason: null
          source:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            chain: POLYGON
            currency: usdc
            amount: 10
            walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D6'
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
          destination:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            amount: 0
            currency: usd
            wireMessage: Wire message
            achReference: ACH reference
            paymentReference: Payment reference
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
            accountId: 12c1c496-8f57-41a1-8292-dbe6547791ce
          receipt:
            transactionHash: null
            paymentTracking: null
          developerFee:
            id: 1c3d24c1-6136-574c-a647-e7eb6a9fb6ed
            transactionHash: null
            fees:
            - type: PERCENTAGE
              value: '0.0005'
              amount: '0.000515'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
            - type: FLAT
              value: '0.01'
              amount: '0.010000'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
          quoteInformation:
            sendGross:
              amount: '10'
              currency: usdc
            sendNet:
              amount: '10'
              currency: usdc
            receiveGross:
              amount: '10'
              currency: usd
            receiveNet:
              amount: '10'
              currency: usd
            rate: '1'
          depositInformation: []
    OfframpObjectListExample:
      summary: Offramp Object List
      value:
        count: 1
        records:
        - transferType: OFFRAMP
          transferDetails:
            id: 173c1e89-7bbd-4352-9e5d-73807681510d
            requestId: 201ca31d-700f-4c76-ac4b-961623acbb79
            createdAt: '2025-02-03T16:12:04.331652+00:00'
            updatedAt: '2025-02-03T16:12:08.732+00:00'
            status: COMPLETED
            failedReason: null
            source:
              userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
              chain: POLYGON
              currency: usdc
              amount: 10
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D6'
              user:
                email: john.doe@hifibridge.com
                firstName: John
                lastName: Doe
                businessName: null
            destination:
              userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
              amount: 0
              currency: usd
              wireMessage: Wire message
              achReference: ACH reference
              paymentReference: Payment reference
              user:
                email: john.doe@hifibridge.com
                firstName: John
                lastName: Doe
                businessName: null
              accountId: 12c1c496-8f57-41a1-8292-dbe6547791ce
            receipt:
              transactionHash: null
              paymentTracking:
                imad: 20250827SIM14AE0135526
                omad: 20250827SIM22390135526
                paymentRail: wire
            developerFee:
              id: 1c3d24c1-6136-574c-a647-e7eb6a9fb6ed
              transactionHash: null
              fees:
              - type: PERCENTAGE
                value: '0.0005'
                amount: '0.000515'
                walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
              - type: FLAT
                value: '0.01'
                amount: '0.010000'
                walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
            quoteInformation:
              sendGross:
                amount: '10'
                currency: usdc
              sendNet:
                amount: '10'
                currency: usdc
              receiveGross:
                amount: '10'
                currency: usd
              receiveNet:
                amount: '10'
                currency: usd
              rate: '1'
            depositInformation: []
    OfframpObjectUsdCompleteExample:
      summary: Offramp Object (USD - COMPLETED)
      value:
        transferType: OFFRAMP
        transferDetails:
          id: 173c1e89-7bbd-4352-9e5d-73807681510d
          requestId: 201ca31d-700f-4c76-ac4b-961623acbb79
          createdAt: '2025-02-03T16:12:04.331652+00:00'
          updatedAt: '2025-02-03T16:12:08.732+00:00'
          status: COMPLETED
          failedReason: null
          source:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            chain: POLYGON
            currency: usdc
            amount: 10
            walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D6'
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
          destination:
            userId: 7d54a7a7-dac3-4313-8b09-27fa4b7fd1ee
            amount: 0
            currency: usd
            wireMessage: Wire message
            achReference: ACH reference
            paymentReference: Payment reference
            user:
              email: john.doe@hifibridge.com
              firstName: John
              lastName: Doe
              businessName: null
            accountId: 12c1c496-8f57-41a1-8292-dbe6547791ce
          receipt:
            transactionHash: null
            paymentTracking:
              imad: 20250827SIM14AE0135526
              omad: 20250827SIM22390135526
              paymentRail: wire
          developerFee:
            id: 1c3d24c1-6136-574c-a647-e7eb6a9fb6ed
            transactionHash: null
            fees:
            - type: PERCENTAGE
              value: '0.0005'
              amount: '0.000515'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
            - type: FLAT
              value: '0.01'
              amount: '0.010000'
              walletAddress: '0x366B759bAA089Fa57a08edd3F2E028E86b97f8D7'
          quoteInformation:
            sendGross:
              amount: '10'
              currency: usdc
            sendNet:
              amount: '10'
              currency: usdc
            receiveGross:
              amount: '10'
              currency: usd
            receiveNet:
              amount: '10'
              currency: usd
            rate: '1'
          depositInformation: []
  requestBodies:
    CreateOfframpBody:
      required: true
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/CreateOfframp'
            - $ref: '#/components/schemas/CreateUsdOfframp'
            - $ref: '#/components/schemas/CreateBrlOfframp'
            - $ref: '#/components/schemas/CreateCopOfframp'
            - $ref: '#/components/schemas/CreateMxnOfframp'
            - $ref: '#/components/schemas/CreateArsOfframp'
            - $ref: '#/components/schemas/CreateAfricaOfframp'
            - $ref: '#/components/schemas/CreateBrazilGlobalNetworkOfframp'
            - $ref: '#/components/schemas/CreateMexicoGlobalNetworkOfframp'
            - $ref: '#/components/schemas/CreateNigeriaGlobalNetworkOfframp'
            - $ref: '#/components/schemas/CreateHongKongGlobalNetworkOfframp'
            - $ref: '#/components/schemas/CreateChinaGlobalNetworkOfframp'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT