HIFI Docs

curl --request POST \
  --url https://production.hifi.com/v3/onramps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b3d1f2a4-5c6e-7890-abcd-ef1234567890",
  "source": {
    "amount": 100,
    "currency": "USD",
    "transferType": "ACH",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs"
  },
  "destination": {
    "currency": "USDC",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "sameDayAch": false,
  "description": "Monthly top-up"
}
'

{
  "id": "onramp_7bV1aLcs3Kf9dQ2mNpXwZ",
  "requestId": "b3d1f2a4-5c6e-7890-abcd-ef1234567890",
  "status": "AWAITING_FUNDS",
  "failedReason": null,
  "error": null,
  "errorDetails": null,
  "source": {
    "amount": 100,
    "currency": "USD",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "externalAccountId": null,
    "virtualAccountId": null,
    "depositInstructions": {
      "bankName": "Cross River Bank",
      "bankAddress": "2115 Linwood Ave, Fort Lee, NJ 07024",
      "beneficiary": {
        "name": "HIFI Bridge Inc",
        "address": "123 Main Street, New York, NY, 10001, USA"
      },
      "ach": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "wire": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "rtp": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "reference": "HIFI-9A2B",
      "depositBy": "2026-07-02T10:30:00.000Z",
      "instruction": "Please deposit USD to the bank account provided. For USDT onramp, a minimum of $10 is required, or the funds will be returned."
    },
    "depositTracking": null
  },
  "destination": {
    "chain": "POLYGON",
    "amount": 100,
    "currency": "USDC",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "externalWalletId": null,
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "receipt": {
    "transactionHash": null
  },
  "settlement": null,
  "quote": {
    "sendGross": {
      "amount": "100.00",
      "currency": "USD"
    },
    "sendNet": {
      "amount": "100.00",
      "currency": "USD"
    },
    "railFee": {
      "amount": "0.00",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "receiveNet": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "rate": "1.00",
    "conversionFee": {
      "amount": "0",
      "currency": "USDC",
      "description": "No conversion fee applicable",
      "timing": "N/A"
    },
    "expiresAt": "N/A"
  },
  "microDeposits": {
    "count": 0,
    "data": []
  },
  "sameDayAch": false,
  "description": "Monthly top-up",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

POST

onramps

curl --request POST \
  --url https://production.hifi.com/v3/onramps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b3d1f2a4-5c6e-7890-abcd-ef1234567890",
  "source": {
    "amount": 100,
    "currency": "USD",
    "transferType": "ACH",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs"
  },
  "destination": {
    "currency": "USDC",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "sameDayAch": false,
  "description": "Monthly top-up"
}
'

{
  "id": "onramp_7bV1aLcs3Kf9dQ2mNpXwZ",
  "requestId": "b3d1f2a4-5c6e-7890-abcd-ef1234567890",
  "status": "AWAITING_FUNDS",
  "failedReason": null,
  "error": null,
  "errorDetails": null,
  "source": {
    "amount": 100,
    "currency": "USD",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "externalAccountId": null,
    "virtualAccountId": null,
    "depositInstructions": {
      "bankName": "Cross River Bank",
      "bankAddress": "2115 Linwood Ave, Fort Lee, NJ 07024",
      "beneficiary": {
        "name": "HIFI Bridge Inc",
        "address": "123 Main Street, New York, NY, 10001, USA"
      },
      "ach": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "wire": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "rtp": {
        "routingNumber": "021000021",
        "accountNumber": "123456789"
      },
      "reference": "HIFI-9A2B",
      "depositBy": "2026-07-02T10:30:00.000Z",
      "instruction": "Please deposit USD to the bank account provided. For USDT onramp, a minimum of $10 is required, or the funds will be returned."
    },
    "depositTracking": null
  },
  "destination": {
    "chain": "POLYGON",
    "amount": 100,
    "currency": "USDC",
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV",
    "externalWalletId": null,
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "receipt": {
    "transactionHash": null
  },
  "settlement": null,
  "quote": {
    "sendGross": {
      "amount": "100.00",
      "currency": "USD"
    },
    "sendNet": {
      "amount": "100.00",
      "currency": "USD"
    },
    "railFee": {
      "amount": "0.00",
      "currency": "USDC"
    },
    "receiveGross": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "receiveNet": {
      "amount": "100.00",
      "currency": "USDC"
    },
    "rate": "1.00",
    "conversionFee": {
      "amount": "0",
      "currency": "USDC",
      "description": "No conversion fee applicable",
      "timing": "N/A"
    },
    "expiresAt": "N/A"
  },
  "microDeposits": {
    "count": 0,
    "data": []
  },
  "sameDayAch": false,
  "description": "Monthly top-up",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Onramp details. Provide exactly one of source.userId / source.externalAccountId, exactly one of source.transferType / source.externalAccountId, exactly one of destination.walletId / destination.externalWalletId, and exactly one of source.amount / destination.amount.

Create an onramp. Provide exactly one of source.userId / source.externalAccountId, exactly one of source.transferType / source.externalAccountId, exactly one of destination.walletId / destination.externalWalletId, and exactly one of source.amount / destination.amount.

requestId

string<uuid>

required

Client-supplied idempotency key. A second create with the same value returns a conflict.

Example:

"b3d1f2a4-5c6e-7890-abcd-ef1234567890"

source

object

required

Source of the fiat funds.

Show child attributes

destination

object

required

Destination for the delivered crypto.

Show child attributes

sameDayAch

boolean

Whether to use same-day ACH settlement.

Example:

false

purposeOfPayment

string

Purpose of the payment.

Example:

"Investment"

description

string

Free-form description for the onramp.

Example:

"Monthly top-up"

Response

Onramp created successfully.

An onramp transaction.

string

Public ID of the onramp (prefixed with onramp_).

Example:

"onramp_7bV1aLcs3Kf9dQ2mNpXwZ"

requestId

string<uuid>

Client-supplied idempotency key from the create request.

Example:

"b3d1f2a4-5c6e-7890-abcd-ef1234567890"

status

enum<string>

Lifecycle status of the onramp transaction.

Available options:

NOT_INITIATED,

CREATED,

OPEN_QUOTE,

IN_REVIEW,

FIAT_INITIATED,

AWAITING_FUNDS,

FIAT_PENDING,

FIAT_PROCESSED,

CRYPTO_INITIATED,

CRYPTO_PENDING,

COMPLETED,

FIAT_FAILED,

FIAT_RETURNED,

CRYPTO_FAILED,

QUOTE_FAILED,

EXPIRED,

UNKNOWN,

CANCELLED

Example:

"AWAITING_FUNDS"

failedReason

string | null

Machine-readable reason when the onramp failed.

Example:

null

error

string | null

User-facing error summary when the onramp failed.

Example:

null

errorDetails

string | null

User-facing error detail when the onramp failed.

Example:

null

source

object

Show child attributes

destination

object

Show child attributes

receipt

object

Show child attributes

settlement

any | null

Settlement breakdown once funds settle.

quote

object

Conversion quote for the onramp.

Show child attributes

microDeposits

object

Micro-deposits received against the onramp while awaiting funds.

Show child attributes

sameDayAch

boolean

Example:

false

description

string | null

Example:

"Monthly top-up"

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

Overview

Endpoints

Create an onramp

Authorizations

Body

Response