OpenAPI Specification
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:
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hifi/refs/heads/main/openapi/hifi-offramp-api-openapi.yml