Skip to main content
A User represents an individual or business on the HIFI platform. Users are the foundation of all transaction activity - every onramp, offramp, and transfer is associated with a user.

​
User Types

HIFI supports two types of users:
TypeDescriptionUse Cases
IndividualA natural personPersonal accounts, freelancers, employees
BusinessA legal entityCompanies, NGOs, partnerships

​
User Capabilities

What users can do depends on their verification status:
Available immediately after creation:
  • ✅ Receive cryptocurrency to their wallet addresses
  • ✅ Send cryptocurrency to other HIFI users
  • ✅ Transfer crypto to external wallets
Not available:
  • ❌ Fiat onramp (deposit USD to receive stablecoins)
  • ❌ Fiat offramp (send stablecoins to receive USD)
All unverified capabilities, plus:
  • ✅ Onramp fiat to stablecoins via virtual accounts
  • ✅ Offramp stablecoins to fiat bank accounts
  • ✅ Access to regulated fiat rails (USD, EUR, etc.)
Requirements:
  • Complete KYC verification for desired rails
  • Maintain active compliance status

​
User Lifecycle

​
Creation

Users are created in two steps:
  1. Generate Terms of Service link - User must review and accept HIFI’s Terms of Service
  2. Create user record - Once terms are accepted, create the user with basic information
Upon creation, users are automatically provisioned with cryptocurrency wallet addresses on supported blockchains (Polygon, Ethereum, etc.). These wallets are immediately functional for sending and receiving digital assets. Create a user: 
curl -X POST "https://sandbox.hifibridge.com/v2/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "dateOfBirth": "1990-05-15",
    "address": {
      "addressLine1": "456 Market St",
      "city": "San Francisco",
      "stateProvinceRegion": "CA",
      "postalCode": "94102",
      "country": "USA"
    },
    "signedAgreementId": "8cb49537-bcf9-41b1-8d8c-c9c200d7341b",
    "requestId": "705f1f8b-a080-467c-b683-174eca409928"
  }'
Response: 
{
  "id": "usr_abc123",
  "type": "individual",
  "email": "jane@example.com",
  "name": "Jane Smith",
  "wallets": {
    "INDIVIDUAL": {
      "POLYGON": {
        "address": "0x1b932E54e77Aeb698144550d5a493Ea99E20Daa7"
      },
      "ETHEREUM": {
        "address": "0xC1c767eaB34b3Cc2C33a354f6Ff2c20fCB98D3C9"
      }
    }
  }
}

​
Verification

To unlock fiat rails, users must complete KYC (Know Your Customer) verification. KYC requirements vary by rail (USD, EUR, etc.) and include:
  • Personal information (name, date of birth, address, tax ID)
  • Identity documents (passport, driver’s license, or ID card)
  • Proof of address (in some cases)
The KYC process typically takes:
  • Sandbox: Typically auto-approved within minutes for testing (may be blocked by compliance checks like PEP screening)
  • Production: 1-3 business days for manual review
Once approved, the user can access fiat onramp and offramp capabilities for that specific rail. Check KYC status: 
curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/kyc/status?rails=USD" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Management

Users can be updated throughout their lifecycle to:
  • Update contact information
  • Add or modify KYC data
  • Link additional bank accounts
  • Add virtual accounts for different currencies
Retrieve user details: 
curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
User Wallets

Every user receives wallet addresses on supported blockchains automatically at creation. These wallets are:
  • Custodial - Managed by HIFI for security and compliance
  • Multi-chain - Available on Polygon, Ethereum, Base, Solana, Flow and other supported networks
  • Immediately active - Ready to send and receive crypto without additional setup
Wallet addresses never change and can be shared with other users or external parties for receiving cryptocurrency.

​
User Accounts

Users can have multiple account types for different purposes:
Account TypePurposeDirection
Virtual AccountReceive fiat depositsFiat → Crypto (onramp)
Offramp AccountSend fiat withdrawalsCrypto → Fiat (offramp)
These accounts are created separately after user creation and require KYC verification to be functional.

​
Key Concepts

Before creating a user, they must accept HIFI’s Terms of Service. This ensures compliance with data handling and regulatory requirements. The signedAgreementId from the ToS acceptance is required when creating the user.
All user creation requests require a requestId (UUID). This ensures idempotency - retrying the same request won’t create duplicate users.
A “rail” is a payment corridor enabling conversions between specific fiat currencies and stablecoins. For example, the USD rail allows conversion between USD and USDC. Each rail has its own KYC requirements.

​
Sample Code

​
Create and verify a user

1

Generate ToS link

curl -X POST "https://sandbox.hifibridge.com/v2/tos-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey": "8cb49537-bcf9-41b1-8d8c-c9c200d7341b"}'
2

Create user (after ToS accepted)

curl -X POST "https://sandbox.hifibridge.com/v2/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "signedAgreementId": "8cb49537-bcf9-41b1-8d8c-c9c200d7341b",
    "requestId": "705f1f8b-a080-467c-b683-174eca409928"
  }'
3

Update KYC information

Provide required personal information:
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/kyc" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "taxIdentificationNumber": "123456789",
    "nationality": "USA"
  }'
4

Upload identity documents

First, upload the document files:
# Upload front side
curl -X POST "https://sandbox.hifibridge.com/v2/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@drivers_license_front.png"

# Upload back side
curl -X POST "https://sandbox.hifibridge.com/v2/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@drivers_license_back.png"
Then attach the documents to the user’s KYC:
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/kyc/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "type": "DRIVERS",
      "subType": "FRONT_SIDE",
      "issuedCountry": "USA",
      "fileId": "file_JzALYV2L1-4LBmaxZ6GCm"
    },
    {
      "type": "DRIVERS",
      "subType": "BACK_SIDE",
      "issuedCountry": "USA",
      "fileId": "file_KpBMZW3M2-5MCnbyA7HDn"
    }
  ]'
5

Submit KYC application

Submit for review once all information and documents are provided:
curl -X POST "https://sandbox.hifibridge.com/v2/users/usr_abc123/kyc/submissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rails": "USD"}'

​
Check user capabilities

Determine what a user can do based on their KYC status: 
curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://sandbox.hifibridge.com/v2/users/usr_abc123/kyc/status?rails=USD" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Getting Help