/v2/user/account endpoint. If you want to explore the API risk-free before going live, the final step points you to the sandbox environment.
1
Create your VelaFi account
Navigate to velafi.com/signup and complete the registration form. Follow the on-screen instructions to verify your email address and finalize your account.After registration, VelaFi assigns you a unique User ID (UID). This UID is the top-level identifier for all merchants, API keys, and transactions associated with your account. Keep it handy — you will see it referenced throughout the dashboard and API responses.
2
Create a merchant and complete KYC/KYB
VelaFi requires every payment operation to be performed under a verified Merchant entity. A merchant can represent your own business or an individual client you are onboarding.To create a merchant:
- In the dashboard, open the Merchants section and click Create Merchant.
- Select the entity type — Individual or Business — and fill in the required details.
- Upload the compliance documents requested for KYC (individuals) or KYB (businesses).
- Submit the form and wait for approval from the VelaFi compliance team.
For a complete walkthrough of merchant creation and document requirements, see the Creating Your Merchant guide.
3
Generate your API key
With your account active, you can now create an API key through the VelaFi dashboard.
- Log in and open API Management.
- Click Create API Key.
- If two-factor authentication (2FA) is not yet enabled on your account, the system will prompt you to set it up before continuing. Complete the 2FA setup — it is required for key generation.
- Enter a note (1–30 characters) to identify the key (for example,
production-backend). - Click Continue and enter your 2FA code. The confirmation window shows your API key and API secret.
-1023).Every API request authenticates by sending a token, obtained with this key and secret from GET /v2/token/generate, in the X-BH-TOKEN header:4
Activate your API access
Generating an API key does not automatically enable API access on your account. You must contact the VelaFi support team to complete activation.Send an email to contact@velafi.com with your account UID and a brief description of your intended use case. The team will confirm by email once API access is live for your account.
Until API access is active, token requests fail with code
-5033.5
Make your first API call
Once your account is activated, get a token and call the account details endpoint to verify your setup.A successful response returns
"code": 200 and "msg": "SUCCESS", with your account details in data. See Get Account Details for the fields.If a call fails, check the negative code in the response body:-5033on the token request: API access is not yet enabled on your account. Contact VelaFi.-1023on the token request: the API key has no IP whitelist.-2015on the token request: the request came from an IP address that is not on the key’s whitelist, or the key or your account is disabled.-1022: the signature is wrong or the API key does not exist (token request), or the token is invalid or has expired (API call).-2019on the API call: the request came from an IP address that is not on the key’s whitelist.
6
Try the sandbox
Before building out production workflows, use the VelaFi sandbox to test your integration against simulated data with no risk to real funds. The sandbox mirrors the production API at a different base URL and requires separate credentials provided by the VelaFi team.
- Sandbox base URL:
https://api-test.velafi.com - Credentials: Contact contact@velafi.com to request sandbox credentials — no KYC or API key creation is required.
Next Steps
Sandbox Environment
Test against simulated data before you touch production.
On-Ramp: Fiat → Crypto
Build your first fiat-to-crypto order flow end to end.
Off-Ramp: Crypto → Fiat
Convert crypto balances and deliver fiat to beneficiary accounts.
API Reference
Browse the full endpoint catalog with parameters and response schemas.

