> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an onramp

> 
An onramp facilitates the conversion of fiat to crypto. Once the fiat payment is received, HIFI will deliver the converted crypto to the receiving user’s wallet.

There are two types of onramp:

* **Quote-based onramp**: This type of onramp first returns the conversion rate quote based on the best market rate, which you can accept through the [Accept an onramp quote](https://docs.hifi.com/api-reference/onramp/accept-an-onramp-quote) endpoint to initiate the onramp.  
  Additionally, you can also refresh the onramp quote using the [Refresh an onramp quote](https://docs.hifi.com/api-reference/onramp/refresh-an-onramp-quote) endpoint to refresh the conversion rate associated with the onramp. To learn more about quote-based onramps, click [here](https://docs.hifi.com/guides/transfers/onramps/usd-usdc).

* **Non-quote-based onramp**: This type of onramp will be initiated immediately upon creating an onramp.




## OpenAPI

````yaml https://production.hifi.com/api/v2/openapi.json post /v2/onramps
openapi: 3.0.0
info:
  title: Hifi 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: Common
    description: Common endpoints
  - name: User
    description: User endpoints
  - name: Kyc
    description: Kyc endpoints
  - name: Wallet
    description: Wallet endpoints
  - name: Account
    description: Account endpoints
  - name: External Account
    description: External Account endpoints for managing beneficiary bank accounts
  - name: Fiat Account
    description: Fiat Account endpoints
  - name: Virtual Account
    description: Virtual Account endpoints
  - name: Onramp
    description: Onramp endpoints
  - name: Offramp
    description: Offramp endpoints
  - name: Orchestration Address
    description: >-
      Orchestration Address endpoints — persistent on-chain wallets that
      automatically off-ramp incoming stablecoin deposits to a USD bank account
  - name: Crypto Transfer
    description: Crypto Transfer endpoints
  - name: Cross-Chain Bridge
    description: Cross-Chain Bridge endpoints
  - name: Token Swap
    description: Token Swap endpoints
  - name: Canton Offers
    description: Canton Offers endpoints
  - name: Transfer Rules
    description: Transfer approval rules and configuration
  - name: Transfer Approvals
    description: Transfer approval workflow and admin actions
  - name: File
    description: File endpoints
  - name: Reporting
    description: Reporting and metrics endpoints
paths:
  /v2/onramps:
    post:
      tags:
        - Onramp
      summary: Create an onramp
      description: >

        An onramp facilitates the conversion of fiat to crypto. Once the fiat
        payment is received, HIFI will deliver the converted crypto to the
        receiving user’s wallet.


        There are two types of onramp:


        * **Quote-based onramp**: This type of onramp first returns the
        conversion rate quote based on the best market rate, which you can
        accept through the [Accept an onramp
        quote](https://docs.hifi.com/api-reference/onramp/accept-an-onramp-quote)
        endpoint to initiate the onramp.  
          Additionally, you can also refresh the onramp quote using the [Refresh an onramp quote](https://docs.hifi.com/api-reference/onramp/refresh-an-onramp-quote) endpoint to refresh the conversion rate associated with the onramp. To learn more about quote-based onramps, click [here](https://docs.hifi.com/guides/transfers/onramps/usd-usdc).

        * **Non-quote-based onramp**: This type of onramp will be initiated
        immediately upon creating an onramp.
      requestBody:
        $ref: '#/components/requestBodies/CreateOnrampBody'
      responses:
        '200':
          $ref: '#/components/responses/FiatToCryptoTransferResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  requestBodies:
    CreateOnrampBody:
      required: true
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/CreateOnramp'
              - $ref: '#/components/schemas/CreateUsdOnramp'
              - $ref: '#/components/schemas/CreateBrlOnramp'
              - $ref: '#/components/schemas/CreateMxnOnramp'
              - $ref: '#/components/schemas/CreateAfricaOnramp'
  responses:
    FiatToCryptoTransferResponse:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OnrampObject'
          examples:
            OnrampObjectUsdOpenQuoteExample:
              $ref: '#/components/examples/OnrampObjectUsdOpenQuoteExample'
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
    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
    InternalServerErrorResponse:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
  schemas:
    CreateOnramp:
      type: object
      title: Onramp
      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
        isInstant:
          type: boolean
          default: false
          description: |
            instant onramp. coming soon ...
        source:
          $ref: '#/components/schemas/OnrampSource'
          type: object
          description: onramp source
        destination:
          $ref: '#/components/schemas/OnrampDestination'
          type: object
          description: onramp destination
        fee:
          type: object
          description: custom onramp fee, omit if no fee is charged
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnrampFee'
      required:
        - requestId
        - source
        - destination
    CreateUsdOnramp:
      type: object
      title: Onramp (USD)
      properties:
        requestId:
          type: string
          description: unique identifier for the request (recommend using uuid v4)
        source:
          $ref: '#/components/schemas/UsdOnrampSource'
          type: object
          description: onramp source
        destination:
          $ref: '#/components/schemas/OnrampDestination'
          type: object
          description: onramp destination
        fee:
          type: object
          description: custom onramp fee, omit if no fee is charged
          allOf:
            - $ref: '#/components/schemas/OnrampFee'
      required:
        - requestId
        - source
        - destination
    CreateBrlOnramp:
      type: object
      title: Onramp (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
        isInstant:
          type: boolean
          default: false
          description: |
            instant onramp. coming soon ...
        source:
          $ref: '#/components/schemas/BrlOnrampSource'
          type: object
          description: onramp source
        destination:
          $ref: '#/components/schemas/OnrampDestination'
          type: object
          description: onramp destination
        fee:
          type: object
          description: custom onramp fee, omit if no fee is charged
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnrampFee'
      required:
        - requestId
        - source
        - destination
    CreateMxnOnramp:
      type: object
      title: Onramp (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
        isInstant:
          type: boolean
          default: false
          description: |
            instant onramp. coming soon ...
        source:
          $ref: '#/components/schemas/MxnOnrampSource'
          type: object
          description: onramp source
        destination:
          $ref: '#/components/schemas/OnrampDestination'
          type: object
          description: onramp destination
        fee:
          type: object
          description: custom onramp fee, omit if no fee is charged
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnrampFee'
      required:
        - requestId
        - source
        - destination
    CreateAfricaOnramp:
      type: object
      title: Onramp (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
        isInstant:
          type: boolean
          default: false
          description: |
            instant onramp. coming soon ...
        source:
          $ref: '#/components/schemas/AfricaOnrampSource'
          type: object
          description: onramp source
        destination:
          $ref: '#/components/schemas/OnrampDestination'
          type: object
          description: onramp destination
        fee:
          type: object
          description: custom onramp fee, omit if no fee is charged
          nullable: true
          allOf:
            - $ref: '#/components/schemas/OnrampFee'
      required:
        - requestId
        - source
        - destination
        - purposeOfPayment
    OnrampObject:
      type: object
      properties:
        transferType:
          type: string
        transferDetails:
          type: object
          properties:
            id:
              type: string
              format: uuid
            requestId:
              type: string
              format: uuid
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
            status:
              $ref: '#/components/schemas/OnrampStatusEnum'
            failedReason:
              type: string
            error:
              type: string
              description: >
                Error code when the onramp transaction has failed (e.g.
                `INTERNAL_ERROR`, `EXPIRED`, `AMOUNT_TOO_LOW`,
                `TRANSACTION_REJECTED`).

                Present when status is a failed state such as `FIAT_FAILED`,
                `CRYPTO_FAILED`, or `QUOTE_FAILED`.
            errorDetails:
              type: string
              description: >
                Human-readable error details when the onramp transaction has
                failed.

                Present when status is a failed state.
            source:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                currency:
                  type: string
                amount:
                  type: number
                  format: float
                accountId:
                  type: string
                user:
                  type: object
                  properties:
                    email:
                      type: string
                    lastName:
                      type: string
                    firstName:
                      type: string
                    businessName:
                      type: string
                bankInfo:
                  $ref: '#/components/schemas/InboundObject'
            destination:
              type: object
              properties:
                userId:
                  type: string
                  format: uuid
                currency:
                  type: string
                chain:
                  type: string
                walletAddress:
                  type: string
                externalWalletId:
                  type: string
                amount:
                  type: number
                  format: float
                user:
                  type: object
                  properties:
                    email:
                      type: string
                    lastName:
                      type: string
                    firstName:
                      type: string
                    businessName:
                      type: string
            receipt:
              type: object
              properties:
                transactionHash:
                  type: string
            developerFee:
              type: object
            quoteInformation:
              type: object
              properties:
                sendGross:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                sendNet:
                  type: object
                  properties:
                    amount:
                      type: string
                    currency:
                      type: string
                railFee:
                  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
            depositInfo:
              $ref: '#/components/schemas/OnrampDepositInfoObject'
    Unauthorized:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        error:
          type: string
          description: Error type
        errorDetails:
          type: string
          description: Detailed error message
    InternalServerError:
      type: object
      properties:
        code:
          type: integer
          description: Error code
        error:
          type: string
          description: Error type
        errorDetails:
          type: string
          description: Detailed error message
    OnrampSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to send
        currency:
          type: string
          enum:
            - usd
            - ngn
            - mwk
            - bwp
            - xaf
            - ghs
            - kes
            - rwf
            - zar
            - tzs
            - ugx
            - xof
            - zmw
            - brl
            - mxn
            - eur
          description: fiat currency
        transferType:
          type: string
          enum:
            - ach
            - wire
          description: |
            payment network type

            * this field is used when onramping from usd, default is `ach`
        accountId:
          type: string
          format: uuid
          description: >
            account the fiat comes from. eg. usd Plaid account


            * this field is optional when onramping from `currency`: `usd`

            * this field is not required when onramping from `currency`: `brl`,
            `mxn`

            * this field is required when onramping from the rest of the
            currencies
        userId:
          type: string
          format: uuid
          description: user who is sending the fiat
      required:
        - currency
        - userId
    OnrampDestination:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of crypto currency to receive
        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
            - TRON
          description: chain of the crypto currency
        userId:
          type: string
          format: uuid
          description: >-
            user who is receiving the crypto, required if `externalWalletId` is
            not provided
        externalWalletId:
          type: string
          format: uuid
          description: >-
            external wallet id who is receiving the crypto, required if `userId`
            is not provided
    OnrampFee:
      type: object
      properties:
        type:
          type: string
          enum:
            - FIX
            - PERCENT
        value:
          type: number
          format: float
          minimum: 0
          description: >
            custom transaction fee (`0.01` represents `1%` when `type` is set to
            `PERCENT`, checkout https://docs.hifi.com/v2/docs/fee-collection for
            more information)
      required:
        - type
        - value
    UsdOnrampSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to send
        currency:
          type: string
          enum:
            - usd
          description: fiat currency
        transferType:
          type: string
          enum:
            - ach
            - wire
          description: |
            payment network type
        accountId:
          type: string
          format: uuid
          description: |
            bank account to ACH pull from.
        userId:
          type: string
          format: uuid
          description: user who is funding the fiat.
      required:
        - transferType
        - currency
        - userId
    BrlOnrampSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to send
        currency:
          type: string
          enum:
            - brl
          description: fiat currency
        userId:
          type: string
          format: uuid
          description: user who is sending the fiat
      required:
        - currency
        - userId
    MxnOnrampSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to send
        currency:
          type: string
          enum:
            - mxn
          description: fiat currency
        userId:
          type: string
          format: uuid
          description: user who is sending the fiat
      required:
        - currency
        - userId
    AfricaOnrampSource:
      type: object
      properties:
        amount:
          type: number
          format: float
          minimum: 0
          description: amount of fiat currency to send
        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 the fiat comes from. eg. usd Plaid account


            * this field is optional when onramping from `currency`: `usd`

            * this field is not required when onramping from `currency`: `brl`

            * this field is required when onramping from the rest of the
            currencies
        userId:
          type: string
          format: uuid
          description: user who is sending the fiat
      required:
        - currency
        - userId
        - accountId
    OnrampStatusEnum:
      type: string
      enum:
        - NOT_INITIATED
        - CREATED
        - OPEN_QUOTE
        - FIAT_INITIATED
        - AWAITING_FUNDS
        - FIAT_PENDING
        - FIAT_PROCESSED
        - CRYPTO_INITIATED
        - CRYPTO_PENDING
        - COMPLETED
        - FIAT_FAILED
        - FIAT_RETURNED
        - CRYPTO_FAILED
        - QUOTE_FAILED
        - EXPIRED
        - CANCELLED
        - UNKNOWN
      description: >
        Refer to
        [here](https://docs.hifi.com/docs/transfers/onramps#transaction-status)
        for more details on each onramp status.
    InboundObject:
      type: object
      properties:
        bankName:
          type: string
        senderName:
          type: string
        routingNumber:
          type: string
        accountNumber:
          type: string
        accountType:
          type: string
        fedBatchId:
          type: string
        imad:
          type: string
        omad:
          type: string
        traceNumber:
          type: string
        bankAddress:
          type: string
        description:
          type: string
        paymentRail:
          type: string
          enum:
            - ach
            - wire
            - rtp
    OnrampDepositInfoObject:
      type: object
      properties:
        bankName:
          type: string
        bankAddress:
          type: string
        swiftCode:
          type: string
        beneficiary:
          type: object
          properties:
            name:
              type: string
            address:
              type: string
        ach:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        wire:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        rtp:
          type: object
          properties:
            routingNumber:
              type: string
            accountNumber:
              type: string
        reference:
          type: string
        depositBy:
          type: string
          format: date-time
        instruction:
          type: string
  examples:
    OnrampObjectUsdOpenQuoteExample:
      summary: Onramp Object (USD - OPEN_QUOTE)
      value:
        transferType: ONRAMP
        transferDetails:
          id: b26927e6-2771-423c-af44-a3c7a3e815c5
          requestId: e1047def-6942-4fd7-be04-e62eb41813b6
          createdAt: '2025-02-03T17:15:31.927121+00:00'
          updatedAt: '2025-02-03T17:15:35.882+00:00'
          status: OPEN_QUOTE
          failedReason: null
          source:
            userId: c15c0adf-3e45-4a62-b334-73aeec127649
            currency: usd
            amount: 10
            accountId: null
            user:
              email: example@hifibridge.com
              lastName: Wu
              firstName: Henry
              businessName: null
            bankInfo: null
          destination:
            userId: c15c0adf-3e45-4a62-b334-73aeec127649
            currency: usdc
            chain: POLYGON
            walletAddress: '0x848732f6c834E05b17C56fa01E83EE095f72C3c3'
            externalWalletId: null
            amount: null
            user:
              email: example@hifibridge.com
              lastName: Wu
              firstName: Henry
              businessName: null
          receipt:
            transactionHash: null
          developerFee: null
          virtualAccountId: null
          quoteInformation:
            sendGross:
              amount: '10.00'
              currency: usd
            sendNet:
              amount: '10.00'
              currency: usd
            railFee:
              amount: '0.00'
              currency: usdc
            receiveGross:
              amount: '10.00'
              currency: usdc
            receiveNet:
              amount: '10.00'
              currency: usdc
            rate: '1.00'
            expiresAt: N/A
          depositInfo: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````