> ## 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.

# Introduction

> VelaFi lets enterprise developers build fiat-to-crypto on-ramps, crypto-to-fiat off-ramps, and global fiat payment flows via stablecoin rails.

VelaFi is a financial API platform that lets you programmatically manage asset conversions and cross-currency transfers at scale. Whether you need to accept local fiat and settle in stablecoins, pay out crypto balances to bank accounts, or move money across borders without a traditional correspondent network, VelaFi exposes each workflow through a single, RESTful interface. The API accepts and returns JSON, authenticates over HTTPS, and uses standard HTTP status codes — so it integrates cleanly into any existing backend stack.

## Core Workflows

VelaFi organizes its capabilities into three distinct payment flows. Each flow builds on the same account and merchant infrastructure, so once you complete onboarding you can enable any combination of them.

> [card] [Fiat → Crypto On-Ramp](https://docs.velafi.com/docs/guides/on-ramp.md)
>
> Accept local fiat currency from a customer and instantly credit the equivalent stablecoin or cryptocurrency to their custody wallet.

> [card] [Crypto → Fiat Off-Ramp](https://docs.velafi.com/docs/guides/off-ramp.md)
>
> Convert a crypto or stablecoin balance and deliver fiat funds directly to a beneficiary's bank account in their local currency.

> [card] [Fiat → Fiat Global Payments](https://docs.velafi.com/docs/guides/global-payments.md)
>
> Send money across borders using stablecoins as the settlement rail, with the sender and recipient each transacting in their own local currency.

### On-Ramp: Fiat → Crypto

The on-ramp flow lets your merchants collect local fiat deposits — for example, Argentine pesos (ARS) or Mexican pesos (MXN) — and receive the corresponding cryptocurrency balance automatically. After activating a merchant fiat account, you create an order, and VelaFi reconciles the incoming bank transfer and credits crypto to the merchant's custody wallet.

### Off-Ramp: Crypto → Fiat

The off-ramp flow works in reverse. Your merchant holds a crypto or stablecoin balance and wants to pay a recipient in fiat. You create a crypto-to-fiat order, VelaFi validates the crypto, converts it, and delivers the fiat settlement to the beneficiary account you specify.

### Global Payments: Fiat → Fiat

The global payment flow uses stablecoins purely as an internal settlement rail. The sender pays in one fiat currency and the recipient receives a different fiat currency, with no crypto exposure on either side. This makes it suitable for payroll, supplier payments, and marketplace disbursements across regions.

***

## Onboarding Overview

Before you can call the API, complete the following one-time setup sequence. Each step unlocks the next.

**1. Create a VelaFi account**

Register at [velafi.com/signup](https://www.velafi.com/signup). Upon successful registration, VelaFi assigns you a unique **User ID (UID)** that ties together all your merchants, API keys, and transaction history.

**2. Create a merchant and complete KYC/KYB**

Create a legal entity (individual or business) under your account and submit the required compliance documents. Once approved, VelaFi assigns a **Merchant ID (MID)** and automatically provisions a crypto custody wallet for that merchant.

**3. Generate your API key**

Log in to the VelaFi dashboard, navigate to **API Management**, and click **Create API Key**. You will be prompted to enable two-factor authentication (2FA) if it is not already active. Copy the API key and API secret, then add the public IP addresses of your servers to the key's whitelist. A key with no whitelist cannot get a token.

**4. Activate API access**

Email [contact@velafi.com](mailto:contact@velafi.com) to request API access activation for your account. The VelaFi support team will confirm once your account is enabled.

**5. Activate merchant payment accounts**

Submit country-specific documents to activate the fiat channels (ARS, MXN, BRL, USD, and others) where your merchant will operate. Each activated channel receives a dedicated payment account — for example, a CVU and CUIT for Argentine peso operations.

***

## API Environments

VelaFi provides two isolated environments. Use the sandbox to develop and test your integration before switching to production.

| Environment | Base URL | Purpose |
| - | - | - |
| **Sandbox** | `https://api-test.velafi.com` | Simulated transactions, no real funds |
| **Production** | `https://api.velafi.com` | Live transactions with real funds |

> [!NOTE]
>
> Sandbox credentials are separate from your production API key. Contact the VelaFi team to obtain sandbox credentials — no KYC or API key creation is required for sandbox access.

***

## Authentication

Authenticated requests carry a business token in the `X-BH-TOKEN` header. Your server gets the token from `GET /v2/token/generate` by signing the request with your API key and API secret, and requests a new one before it expires. A request with no token fails with code `-1002`, and one with an invalid or expired token fails with code `-1022`.

```http theme={null}
X-BH-TOKEN: YOUR_TOKEN
```

Here is a minimal example that retrieves your account details:

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

See [Authentication](https://docs.velafi.com/api-reference/authentication.md) for the signing steps and the IP whitelist requirement.

> [!WARNING]
>
> Treat your API secret and tokens like passwords. Never expose them in client-side code, public repositories, or log files. If you suspect your key or secret has been compromised, delete the key on the API Management page and create a new one.

***

## Explore the Documentation

> [card] [Quickstart](https://docs.velafi.com/docs/quickstart.md)
>
> Create your account, generate an API key, and make your first API call in minutes.

> [card] [Sandbox](https://docs.velafi.com/docs/sandbox.md)
>
> Test your full integration against simulated data before going live.

> [card] [On-Ramp Guide](https://docs.velafi.com/docs/guides/on-ramp.md)
>
> Step-by-step instructions for building the fiat-to-crypto on-ramp flow.

> [card] [API Reference](https://docs.velafi.com/api-reference/overview.md)
>
> Full endpoint documentation with parameters, request bodies, and response schemas.


## Related topics

- [VelaFi API Docs](https://docs.velafi.com/index.md)


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