Skip to main content
This quickstart walks you through the minimum steps needed to authenticate against the VelaFi API and make a successful request. By the end, you will have a working API key, a verified account, and a live response from the /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.
Log in to the VelaFi dashboard immediately after registering to familiarize yourself with the account structure before proceeding to merchant setup.
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:
  1. In the dashboard, open the Merchants section and click Create Merchant.
  2. Select the entity type — Individual or Business — and fill in the required details.
  3. Upload the compliance documents requested for KYC (individuals) or KYB (businesses).
  4. Submit the form and wait for approval from the VelaFi compliance team.
Once approved, VelaFi assigns a Merchant ID (MID) and automatically provisions a crypto custody wallet for that merchant with an initial monthly withdrawal limit of USD 10,000,000,000.
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.
  1. Log in and open API Management.
  2. Click Create API Key.
  3. 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.
  4. Enter a note (1–30 characters) to identify the key (for example, production-backend).
  5. Click Continue and enter your 2FA code. The confirmation window shows your API key and API secret.
Copy your API secret and store it securely before closing the confirmation window. VelaFi does not display the secret again; the API key stays visible in your key list. If you lose the secret, delete the key and create a new one.
Next, select Whitelist on the new key and add the public IP addresses of the servers that will call the API. You can add up to 5 IPv4 or IPv6 addresses; CIDR ranges are not accepted. A key with no whitelist cannot get a token (code -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:
  • -5033 on the token request: API access is not yet enabled on your account. Contact VelaFi.
  • -1023 on the token request: the API key has no IP whitelist.
  • -2015 on 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).
  • -2019 on the API call: the request came from an IP address that is not on the key’s whitelist.
See Authentication for the full list of authentication errors.
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.
See the Sandbox page for a full comparison of sandbox and production behaviors and an example request.

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.