Skip to main content
The VelaFi REST API lets you programmatically manage fiat-to-crypto on-ramps, crypto-to-fiat off-ramps, and fiat-to-fiat global payments via stablecoin rails. The API follows RESTful conventions — every resource is addressable by a URL, every interaction uses standard HTTP methods, and every response body is JSON. All communication occurs over HTTPS, and standard HTTP status codes indicate the outcome of each request.

​
Base URLs

Choose the environment that matches your integration stage. Use the sandbox environment for development and testing so that no real funds are moved. Switch to the production URL only when you are ready to go live.
Sandbox and production credentials are not interchangeable. Use the API key, API secret, and token issued for the environment you are calling.

​
Request Format

Send all request bodies as JSON and set the Content-Type header accordingly:
Every request that accesses a protected resource must also include a business token in the X-BH-TOKEN header. Get the token from GET /v2/token/generate by signing the request with your API key and API secret. See the Authentication page for details. Example request

​
Response Envelope

Successful responses are wrapped in this JSON envelope. Error responses carry code and msg but no data; see Error Codes.
​
number
200 on success (a few endpoints return 0). On an error, code is the error code (negative, except 30012). It does not mirror the HTTP status: responses that carry an error code use HTTP 400 or 500. See Error Codes.
​
string
A short human-readable message summarising the outcome, for example "SUCCESS" or a description of the error.
​
object | array | null
The payload returned by the endpoint. The shape varies by endpoint and is documented on each individual reference page.

​
HTTP Status Codes

The table below lists the HTTP status codes the API returns.
A missing, invalid, or expired token returns 400 with code -1002 or -1022, not 401. Exceeding a rate limit returns 400 with code -1006, not 429. Always branch on the code field. See Error Codes for every code and for which codes mean the outcome is unknown.

​
Rate Limits

The endpoints below have a default rate limit, counted per VelaFi account and separately for each endpoint. The one-minute window starts with your first request and resets one minute later.
A request over the limit is rejected with HTTP 400 and code -1006 (Execution status unknown.), not 429. Separately, any endpoint can return code 30012 (HTTP 400) when it receives too many concurrent requests. Back off before retrying. For order-creation calls, follow the “Outcome Unknown: Check Before You Retry” section of Error Codes, because -1006 is also used for other failures.
Other endpoints may have their own limits. Contact VelaFi support if you need a higher throughput allowance for your use case.

​
Key Sections

Use the cards below to jump straight to the resource group you need.

Merchants

Configure merchant profiles, retrieve merchant details, and manage merchant-level settings.

Orders

Create, query, and manage on-ramp, off-ramp, and fiat-to-fiat payment orders.

Beneficiaries

Add and manage the bank accounts and crypto wallets that receive payouts.

Webhooks

Subscribe to real-time event notifications for order status changes and more.