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

# Quickstart

> Set up your VelaFi account, generate an API key, and send your first authenticated API request in under 15 minutes with this step-by-step quickstart.

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](https://www.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.

> [!TIP]
>
> 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.

> [!NOTE]
>
> For a complete walkthrough of merchant creation and document requirements, see the [Creating Your Merchant](https://docs.velafi.com/docs/guides/creating-merchant.md) 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](https://www.velafi.com/security/interface).
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.

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

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

**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](mailto: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.

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

```bash cURL theme={null}
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"
TIMESTAMP=$(( $(date +%s) * 1000 ))
SIGNATURE=$(printf 'timestamp=%s' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.*= //')

# 1. Get a token
curl --request GET \
  --url "https://api.velafi.com/v2/token/generate?timestamp=${TIMESTAMP}&signature=${SIGNATURE}" \
  --header "X-BH-APIKEY: ${API_KEY}"

# 2. Call the API with the token from data.token
curl --request GET \
  --url https://api.velafi.com/v2/user/account \
  --header "X-BH-TOKEN: YOUR_TOKEN"
```

```python Python theme={null}
import hashlib
import hmac
import time

import requests

BASE_URL = "https://api.velafi.com"
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"

# 1. Get a token
timestamp = str(int(time.time() * 1000))
signature = hmac.new(
    API_SECRET.encode("utf-8"),
    f"timestamp={timestamp}".encode("utf-8"),
    hashlib.sha256,
).hexdigest()
token_body = requests.get(
    f"{BASE_URL}/v2/token/generate",
    params={"timestamp": timestamp, "signature": signature},
    headers={"X-BH-APIKEY": API_KEY},
).json()
if token_body["code"] != 200:
    raise RuntimeError(f"Token request failed: {token_body}")

# 2. Call the API with the token
response = requests.get(
    f"{BASE_URL}/v2/user/account",
    headers={"X-BH-TOKEN": token_body["data"]["token"]},
)
print(response.json())
```

```javascript Node.js theme={null}
const crypto = require("crypto");

const BASE_URL = "https://api.velafi.com";
const API_KEY = "YOUR_API_KEY";
const API_SECRET = "YOUR_API_SECRET";

async function main() {
  // 1. Get a token
  const timestamp = Date.now().toString();
  const signature = crypto
    .createHmac("sha256", API_SECRET)
    .update(`timestamp=${timestamp}`)
    .digest("hex");
  const tokenResponse = await fetch(
    `${BASE_URL}/v2/token/generate?timestamp=${timestamp}&signature=${signature}`,
    { headers: { "X-BH-APIKEY": API_KEY } }
  );
  const tokenBody = await tokenResponse.json();
  if (tokenBody.code !== 200) {
    throw new Error(`Token request failed: ${JSON.stringify(tokenBody)}`);
  }

  // 2. Call the API with the token
  const response = await fetch(`${BASE_URL}/v2/user/account`, {
    headers: { "X-BH-TOKEN": tokenBody.data.token },
  });
  console.log(await response.json());
}

main();
```

A successful response returns `"code": 200` and `"msg": "SUCCESS"`, with your account details in `data`. See [Get Account Details](https://docs.velafi.com/api-reference/account/get-account-details.md) 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](https://docs.velafi.com/api-reference/authentication.md) 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](mailto:contact@velafi.com) to request sandbox credentials — no KYC or API key creation is required.

See the [Sandbox](https://docs.velafi.com/docs/sandbox.md) page for a full comparison of sandbox and production behaviors and an example request.

***

## Next Steps

> [card] [Sandbox Environment](https://docs.velafi.com/docs/sandbox.md)
>
> Test against simulated data before you touch production.

> [card] [On-Ramp: Fiat → Crypto](https://docs.velafi.com/docs/guides/on-ramp.md)
>
> Build your first fiat-to-crypto order flow end to end.

> [card] [Off-Ramp: Crypto → Fiat](https://docs.velafi.com/docs/guides/off-ramp.md)
>
> Convert crypto balances and deliver fiat to beneficiary accounts.

> [card] [API Reference](https://docs.velafi.com/api-reference/overview.md)
>
> Browse the full endpoint catalog with parameters and response schemas.


## Related topics

- [Sandbox](https://docs.velafi.com/docs/sandbox.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)


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