> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Explore the VelaFi REST API: base URLs, JSON request format, standard response envelope, rate limits, and links to key resource sections.

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.

| Environment | Base URL |
| - | - |
| Production | `https://api.velafi.com` |
| Sandbox | `https://api-test.velafi.com` |

> [!NOTE]
>
> 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:

```http theme={null}
Content-Type: application/json
```

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](https://docs.velafi.com/api-reference/authentication.md) page for details.

**Example request**

```bash theme={null}
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: your_token"
```

## Response Envelope

Successful responses are wrapped in this JSON envelope. Error responses carry `code` and `msg` but no `data`; see [Error Codes](https://docs.velafi.com/docs/error-codes.md).

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": { ... }
}
```

**code** `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](https://docs.velafi.com/docs/error-codes.md).

**msg** `string`

A short human-readable message summarising the outcome, for example `"SUCCESS"` or a description of the error.

**data** `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.

| Code | Meaning |
| - | - |
| `200 OK` | The request succeeded. |
| `400 Bad Request` | Any authentication, validation, rate-limit, or business error. The body carries the error `code` and `msg`, and for most errors the code is repeated in the `error_code` response header. |
| `404 Not Found` | The path does not exist. |
| `405 Method Not Allowed` | The path does not accept this HTTP method. |
| `500 Internal Server Error` | An unexpected error occurred. The body carries code `-1001`. |

> [!WARNING]
>
> 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](https://docs.velafi.com/docs/error-codes.md) 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.

| Endpoint | Default limit |
| - | - |
| `GET /v2/user/crypto-quote` | 500 requests per minute |
| `GET /v2/user/fiat-quote` | 500 requests per minute |
| `POST /v2/order/fiat_to_crypto` | 500 requests per minute |
| `POST /v2/order/crypto_to_fiat` | 500 requests per minute |
| `POST /v2/order/fiat_to_fiat` | 500 requests per minute |
| `GET /v2/merchant/check/alias` | 100 requests per minute |
| `GET /v2/merchant/check/cvu` | 100 requests per minute |

> [!NOTE]
>
> 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](https://docs.velafi.com/docs/error-codes.md), because `-1006` is also used for other failures.

Other endpoints may have their own limits. Contact [VelaFi support](mailto:support@velafi.com) 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.

> [card] [Merchants](https://docs.velafi.com/api-reference/merchant/create-merchant.md)
>
> Configure merchant profiles, retrieve merchant details, and manage merchant-level settings.

> [card] [Orders](https://docs.velafi.com/api-reference/order/create-a-fiat-to-crypto-order.md)
>
> Create, query, and manage on-ramp, off-ramp, and fiat-to-fiat payment orders.

> [card] [Beneficiaries](https://docs.velafi.com/api-reference/beneficiary/get-payment-templates.md)
>
> Add and manage the bank accounts and crypto wallets that receive payouts.

> [card] [Webhooks](https://docs.velafi.com/api-reference/webhooks/webhook-setup.md)
>
> Subscribe to real-time event notifications for order status changes and more.


## Related topics

- [Authentication](https://docs.velafi.com/api-reference/authentication.md)
- [Generate a Token](https://docs.velafi.com/api-reference/generate-token.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)
- [Payment Methods](https://docs.velafi.com/docs/payment-methods.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.