Sandbox Environment
This guide uses the Sandbox API where:- ✅ All transactions are simulated - no real money moves
- ✅ KYC applications are typically automatically approved
- ✅ Transactions complete instantly for testing
- ✅ You can experiment freely without financial risk
Prerequisites
Before you start, make sure you have:- API keys from the Dashboard (Get API keys)
- A tool for making API calls (cURL, Postman, or similar)
- Basic understanding of REST APIs
- Your sandbox endpoint:
https://sandbox.hifibridge.com
All examples in this guide use the sandbox environment. When you’re ready for
production, simply replace the sandbox URL with the production endpoint and
use your production API keys.
What you’ll build
Here’s what we’ll accomplish in this guide:- User Creation - Create a user and accept Terms of Service
- KYC Process - Complete verification to unlock fiat rails
- Set Up Virtual Account - Create a virtual account for receiving deposits
- Simulate Deposit - Fund the wallet by simulating a deposit (onramp)
- Execute a Transfer - Send stablecoins between wallets
- Create Offramp Account - Register a bank account for receiving fiat
- Create an Offramp - Convert stablecoins back to fiat currency
Create a User
The User object represents an individual or business on HIFI. All transaction activity is associated with a user object. Creating a user is a two-step process:- Generate a Terms of Service link for your end user to review and accept
- Create the user once they’ve accepted the terms
Generate Terms of Service Link
Generate Terms of Service Link
Before creating a user, they must accept HIFI’s Terms of Service. Generate a unique acceptance link using the Generate Terms of Service Link endpoint.You’ll provide an Response:What to do with this response:
idempotencyKey (any UUID), which will become your signedAgreementId after the user accepts the terms.Request:- Direct your user to the
url- Present this link to your end user (via email, in your app, etc.) - Save the
signedAgreementId- You’ll need this to create the user in the next step - Wait for acceptance - The
signedAgreementIdbecomes valid only after the user clicks “Accept”
Real-time Notifications: HIFI triggers the
TOS_LINK.UPDATE webhook event
when the user accepts the terms, allowing you to proceed with user creation
immediately. Learn about webhooks →Create User
Create User
Once your user has accepted the Terms of Service (and you’ve received the webhook event or confirmed acceptance), create the user account with the Create User endpoint.Request:Response:✅ User created successfully!What you get:
- User ID (
32051b2f-0798-55a7-9c42-b08da4192c97) - Save this for all future operations - Wallet addresses - Pre-provisioned on multiple blockchains, ready to use immediately
- Account status - Active and ready for KYC verification
Automatic Wallet Provisioning: Every user automatically receives wallet
addresses on supported blockchain networks (Polygon, Ethereum, etc.). These
wallets are fully functional immediately - no additional setup required.
What’s Next?
Now that you have a user, the next step is to complete KYC verification to unlock the ability to move money between fiat and crypto. Continue to the KYC section below.Complete KYC
To move money between stablecoins and fiat currencies, users must complete KYC verification to unlock a Rail. What is a Rail? A rail is a payment corridor that enables specific currency conversions. For example, the USD rail enables conversions between USD (fiat) and stablecoins like USDC. In this quickstart, we’ll complete KYC for the USD rail, which allows your user to:- Deposit USD and receive USDC (onramp)
- Send USDC and receive USD (offramp)
Rail-Specific Requirements: Each rail has different KYC requirements based
on regulatory needs. Visit our Rails page to learn about
available rails and their specific requirements.
Recommended: Use KYC Links
The easiest way to collect KYC information is using KYC Links, which provide a hosted, user-friendly flow. Generate a KYC link and redirect your user to complete verification. Request:- Redirect your user to the
kycLinkUrl- They’ll complete KYC on HIFI’s hosted page - User completes KYC - They fill out information and upload documents
- User is redirected back - After completion, they’re sent to your
redirectUrlwith?userId=... - Monitor status - Check KYC status via API or webhooks
KYC Links Benefits: KYC Links handle all the complexity of document
uploads, validation, and submission automatically. This is the recommended
approach for most integrations. Learn more about KYC Links
→
Alternative: Use API
If you need full control over the KYC collection process, you can submit KYC programmatically using the API. This approach requires you to:- Retrieve KYC requirements
- Update KYC information
- Upload identity documents
- Submit the KYC application
- Monitor approval status
For detailed instructions on programmatic KYC submission, see our Submit KYC
Guide.
Check KYC Status
After your user completes KYC (via KYC Link or programmatic submission), check their status: Request:ACTIVE, the USD rail is unlocked and the user can proceed with transfers.
Sandbox Auto-Approval: In the sandbox environment, KYC applications are
typically automatically approved within minutes for testing purposes. In
production, the review process typically takes 1-3 business days.
- Polling the Retrieve KYC Status endpoint
- Listening for
KYC.STATUS_UPDATEwebhook events
Create Virtual Account
Now that your user has passed KYC, you can add a Virtual Account to enable onramping (converting fiat deposits into stablecoins). A Virtual Account is a bank account number automatically created by HIFI that your user can deposit money into. When fiat arrives, it’s automatically converted to the specified stablecoin and sent to the user’s wallet. The parameters you specify determine the conversion:sourceCurrency- Fiat currency to deposit (e.g.,usd)destinationCurrency- Stablecoin to receive (e.g.,usdc)destinationChain- Blockchain network (e.g.,POLYGON)
The unique virtual account ID. Save this for retrieving account details
and monitoring deposits.
Most Important: Bank account details your user needs to send money to.
Share these instructions with your user so they can deposit funds via their
bank (wire transfer, ACH, or RTP).
How to Use: Provide these deposit instructions to your end user through
your app/website. When they send money to this account via their bank, HIFI
automatically detects the deposit, converts it to USDC, and sends it to their
wallet.
Simulate Deposit
Before we can transfer funds, we need to fund the user’s wallet. In sandbox, we’ll simulate a deposit to the virtual account, which will trigger an onramp and deposit USDC into the user’s wallet. What is an Onramp? An onramp converts fiat money deposited into a virtual account into stablecoins and sends them to the user’s wallet.How Onramps Work
In production, onramping happens automatically when your user sends money from their bank to the virtual account. HIFI detects the deposit and automatically triggers the conversion. In sandbox, we use a simulation endpoint to mimic an incoming deposit without requiring real bank transfers.Simulate Deposit (Sandbox)
Since we’re in sandbox, use the simulate endpoint to create a test deposit: Request:How the money is being sent:
wire, ach, or rtpSimulates the sender’s bank information. This represents the bank account
sending money TO the virtual account.
Amount of USD being deposited (will convert to equivalent USDC).
Unique identifier for this deposit simulation (UUID).
Monitor Onramp Status
HIFI creates an onramp transaction when a deposit is detected. You’ll receive aONRAMP.CREATE webhook event with transaction details.
Onramp Status Progression:
FIAT_PENDING- Waiting for fiat to settleCRYPTO_PENDING- Converting and sending cryptoCOMPLETE- USDC delivered to wallet
- Webhooks: Subscribe to
ONRAMP.UPDATEevents for real-time notifications - Polling: Call Retrieve an onramp with the transaction ID
Learn More: For detailed information about receiving money, see the
Receive Money Guide.
Wait for Completion: Wait for the onramp status to reach
COMPLETE before
proceeding with the transfer. This ensures the user’s wallet has funds
available.Execute a Transfer
Now that your user has funds in their wallet, you can execute a transfer - sending stablecoins directly between user wallets on the blockchain. What is a Transfer? A transfer sends stablecoins from one user’s wallet to another user’s wallet. No fiat conversion occurs - this is pure crypto-to-crypto movement.Create Transfer
Send stablecoins from one user to another using the Create a crypto transfer endpoint. Request:Unique identifier (UUID) for this transfer request. Ensures idempotency -
retrying with the same ID won’t create duplicate transfers.
Source of the transfer.
Destination of the transfer.
Amount of stablecoins to transfer.
Stablecoin to transfer (e.g.,
usdc, usdt).Blockchain network for the transfer (e.g.,
POLYGON, ETHEREUM).Unique transfer ID. Save this to check status using the Retrieve a crypto
transfer
endpoint.
Transfer status. Starts as
CREATED, then progresses through: - CREATED -
Transfer initiated - PENDING - Being processed on blockchain - COMPLETE -
Successfully delivered - FAILED - Transfer failed (see failedReason)Monitor Transfer Status
Transfer Status Progression:CREATED- Transfer initiatedPENDING- Being processed on blockchainCOMPLETE- Successfully deliveredFAILED- Transfer failed (seefailedReason)
- Webhooks: Subscribe to
WALLET.TRANSFER.UPDATEevents for real-time notifications - Polling: Call Retrieve a crypto transfer with the transfer ID
Learn More: For detailed information about other transaction types, see: -
Receive Money - Convert fiat to stablecoins -
Send Money - Convert stablecoins to fiat
Sandbox Simulation: No real money moves in sandbox. All transfers are
simulated, but the API requests and responses are identical to production.
Create an Offramp
Now let’s convert stablecoins back to USD using an offramp. An offramp converts USDC to USD and sends it to a user’s bank account.Create Offramp Account
Before creating an offramp, users need to register their bank account as an offramp account. This account will receive fiat currency when stablecoins are converted. Create an offramp account using the Create Account endpoint:- USD (US Bank Account)
- Mexico (MXN - SPEI)
- Brazil (BRL - PIX)
id - you’ll need it when creating offramps.ACTIVE- Account is validated and ready for offrampsPENDING- Account is being validated (wait for activation)REJECTED- Validation failed (checkinvalidFieldsfor details)
ACCOUNT.UPDATE) or by polling the Retrieve an account endpoint.
More Account Types: For additional regions and currencies (China, Hong
Kong, Nigeria, and more), see the Offramp Accounts
Guide.
Create Offramp Request
Create an offramp request to get a quote for converting USDC to USD: Request:OFFRAMP.UPDATE) or by polling the Retrieve an offramp endpoint.
Learn More: For detailed offramp information, see the Send Money
Guide and Offramp
Guide.
🎉 Congratulations!
You’ve successfully completed the HIFI API quickstart! By following the steps above, you can now:- ✅ Create users and handle Terms of Service acceptance
- ✅ Complete the KYC process to unlock fiat rails
- ✅ Set up virtual accounts for receiving deposits
- ✅ Simulate deposits to fund wallets
- ✅ Execute transfers between wallets
- ✅ Create offramp accounts for receiving fiat
- ✅ Create offramps to convert stablecoins to fiat
Next Steps
Ready to build your integration? Here’s what to explore next:- Receive Money - Convert fiat to stablecoins
- Send Money - Convert stablecoins to fiat
- Webhooks - Set up real-time event notifications for transaction updates
- Rails Overview - Learn about additional currency rails
- Error Handling - Understand error codes and how to handle failures
- API Reference - Explore all available endpoints and parameters