---
title: "Create an onramp"
method: POST
path: "/v2/onramps"
tags: ["Onramp"]
---

# Create an onramp

`POST /v2/onramps`

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.

## Request body

- union
  - CreateOnramp
    - `requestId` string, required — unique identifier for the request (recommend using uuid v4)
    - `purposeOfPayment` 'gift' | 'bills' | 'groceries' | 'travel' | 'health' | 'entertainment' | 'housing' | 'school-fees' | 'other'
    - `isInstant` boolean — instant onramp. coming soon ...
    - `source` OnrampSource, required
      - `amount` number, float — amount of fiat currency to send
      - `currency` 'usd' | 'ngn' | 'mwk' | 'bwp' | 'xaf' | 'ghs' | 'kes' | 'rwf' | 'zar' | 'tzs' | 'ugx' | 'xof' | 'zmw' | 'brl' | 'mxn' | 'eur', required — fiat currency
      - `transferType` 'ach' | 'wire' — payment network type * this field is used when onramping from usd, default is `ach`
      - `accountId` string, uuid — 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` string, uuid, required — user who is sending the fiat
    - `destination` OnrampDestination, required
      - `amount` number, float — amount of crypto currency to receive
      - `currency` 'usdc' | 'usdt' | 'usdHifi' — crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)
      - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'TRON' — chain of the crypto currency
      - `userId` string, uuid — user who is receiving the crypto, required if `externalWalletId` is not provided
      - `externalWalletId` string, uuid — external wallet id who is receiving the crypto, required if `userId` is not provided
    - `fee` OnrampFee
      - `type` 'FIX' | 'PERCENT', required
      - `value` number, float, required — 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)
  - CreateUsdOnramp
    - `requestId` string, required — unique identifier for the request (recommend using uuid v4)
    - `source` UsdOnrampSource, required
      - `amount` number, float — amount of fiat currency to send
      - `currency` 'usd', required — fiat currency
      - `transferType` 'ach' | 'wire', required — payment network type
      - `accountId` string, uuid — bank account to ACH pull from.
      - `userId` string, uuid, required — user who is funding the fiat.
    - `destination` OnrampDestination, required
      - `amount` number, float — amount of crypto currency to receive
      - `currency` 'usdc' | 'usdt' | 'usdHifi' — crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)
      - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'TRON' — chain of the crypto currency
      - `userId` string, uuid — user who is receiving the crypto, required if `externalWalletId` is not provided
      - `externalWalletId` string, uuid — external wallet id who is receiving the crypto, required if `userId` is not provided
    - `fee` OnrampFee
      - `type` 'FIX' | 'PERCENT', required
      - `value` number, float, required — 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)
  - CreateBrlOnramp
    - `requestId` string, required — unique identifier for the request (recommend using uuid v4)
    - `purposeOfPayment` 'gift' | 'bills' | 'groceries' | 'travel' | 'health' | 'entertainment' | 'housing' | 'school-fees' | 'other'
    - `isInstant` boolean — instant onramp. coming soon ...
    - `source` BrlOnrampSource, required
      - `amount` number, float — amount of fiat currency to send
      - `currency` 'brl', required — fiat currency
      - `userId` string, uuid, required — user who is sending the fiat
    - `destination` OnrampDestination, required
      - `amount` number, float — amount of crypto currency to receive
      - `currency` 'usdc' | 'usdt' | 'usdHifi' — crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)
      - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'TRON' — chain of the crypto currency
      - `userId` string, uuid — user who is receiving the crypto, required if `externalWalletId` is not provided
      - `externalWalletId` string, uuid — external wallet id who is receiving the crypto, required if `userId` is not provided
    - `fee` OnrampFee
      - `type` 'FIX' | 'PERCENT', required
      - `value` number, float, required — 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)
  - CreateMxnOnramp
    - `requestId` string, required — unique identifier for the request (recommend using uuid v4)
    - `purposeOfPayment` 'gift' | 'bills' | 'groceries' | 'travel' | 'health' | 'entertainment' | 'housing' | 'school-fees' | 'other'
    - `isInstant` boolean — instant onramp. coming soon ...
    - `source` MxnOnrampSource, required
      - `amount` number, float — amount of fiat currency to send
      - `currency` 'mxn', required — fiat currency
      - `userId` string, uuid, required — user who is sending the fiat
    - `destination` OnrampDestination, required
      - `amount` number, float — amount of crypto currency to receive
      - `currency` 'usdc' | 'usdt' | 'usdHifi' — crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)
      - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'TRON' — chain of the crypto currency
      - `userId` string, uuid — user who is receiving the crypto, required if `externalWalletId` is not provided
      - `externalWalletId` string, uuid — external wallet id who is receiving the crypto, required if `userId` is not provided
    - `fee` OnrampFee
      - `type` 'FIX' | 'PERCENT', required
      - `value` number, float, required — 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)
  - CreateAfricaOnramp
    - `requestId` string, required — unique identifier for the request (recommend using uuid v4)
    - `purposeOfPayment` 'gift' | 'bills' | 'groceries' | 'travel' | 'health' | 'entertainment' | 'housing' | 'school-fees' | 'other', required
    - `isInstant` boolean — instant onramp. coming soon ...
    - `source` AfricaOnrampSource, required
      - `amount` number, float — amount of fiat currency to send
      - `currency` string, required — 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` string, uuid, required — 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` string, uuid, required — user who is sending the fiat
    - `destination` OnrampDestination, required
      - `amount` number, float — amount of crypto currency to receive
      - `currency` 'usdc' | 'usdt' | 'usdHifi' — crypto currency (note: `usdHifi` is only available in sandbox to simulate token movement)
      - `chain` 'POLYGON' | 'ETHEREUM' | 'SOLANA' | 'BASE' | 'TRON' — chain of the crypto currency
      - `userId` string, uuid — user who is receiving the crypto, required if `externalWalletId` is not provided
      - `externalWalletId` string, uuid — external wallet id who is receiving the crypto, required if `userId` is not provided
    - `fee` OnrampFee
      - `type` 'FIX' | 'PERCENT', required
      - `value` number, float, required — 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)

## Response `200`

Success

- OnrampObject
  - `transferType` string
  - `transferDetails` object
    - `id` string, uuid
    - `requestId` string, uuid
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `status` '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' — Refer to [here](https://docs.hifi.com/docs/transfers/onramps#transaction-status) for more details on each onramp status.
    - `failedReason` string
    - `error` string — 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` string — Human-readable error details when the onramp transaction has failed. Present when status is a failed state.
    - `source` object
      - `userId` string, uuid
      - `currency` string
      - `amount` number, float
      - `accountId` string
      - `user` object
        - `email` string
        - `lastName` string
        - `firstName` string
        - `businessName` string
      - `bankInfo` InboundObject
        - `bankName` string
        - `senderName` string
        - `routingNumber` string
        - `accountNumber` string
        - `accountType` string
        - `fedBatchId` string
        - `imad` string
        - `omad` string
        - `traceNumber` string
        - `bankAddress` string
        - `description` string
        - `paymentRail` 'ach' | 'wire' | 'rtp'
    - `destination` object
      - `userId` string, uuid
      - `currency` string
      - `chain` string
      - `walletAddress` string
      - `externalWalletId` string
      - `amount` number, float
      - `user` object
        - `email` string
        - `lastName` string
        - `firstName` string
        - `businessName` string
    - `receipt` object
      - `transactionHash` string
    - `developerFee` object
    - `quoteInformation` object
      - `sendGross` object
        - `amount` string
        - `currency` string
      - `sendNet` object
        - `amount` string
        - `currency` string
      - `railFee` object
        - `amount` string
        - `currency` string
      - `receiveGross` object
        - `amount` string
        - `currency` string
      - `receiveNet` object
        - `amount` string
        - `currency` string
      - `rate` string
      - `expiresAt` string, date-time
    - `depositInfo` OnrampDepositInfoObject
      - `bankName` string
      - `bankAddress` string
      - `swiftCode` string
      - `beneficiary` object
        - `name` string
        - `address` string
      - `ach` object
        - `routingNumber` string
        - `accountNumber` string
      - `wire` object
        - `routingNumber` string
        - `accountNumber` string
      - `rtp` object
        - `routingNumber` string
        - `accountNumber` string
      - `reference` string
      - `depositBy` string, date-time
      - `instruction` string

## Other responses

- `401` — Unauthorized
- `404` — Resource not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/hifi/apis/hifi-api.md) · [All operations](https://skmtc.net/hifi/apis/hifi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hifi/hifi-api/revisions/15a39c342fd1/schema)