Environments and base URLs
How to address your V3 Custody instance: the base URL, the /api/v1 prefix, the webhook path, and the [BASE_URL] convention used in examples.
V3 Custody is self-hosted: you deploy the platform in your own environment, so the base URL is the address of your instance. Throughout the documentation it appears as [BASE_URL]; replace it with your actual address.
How instance addresses are structured:
Base URL
[BASE_URL] is the root of your instance. It's used in every example (easy to spot by the square brackets and replace with a single search).
Addressing scopes
Almost all endpoints live under /api/v1; webhooks are the exception:
| Scope | Path pattern | Examples |
|---|---|---|
| vault-scoped | [BASE_URL]/api/v1/vaults/{code}/... | balances, transfers, reports, addresses |
| top-level | [BASE_URL]/api/v1/... | evaluate, policies, invitations |
| webhooks | [BASE_URL]/webhooks/... | webhooks/wallet (TOPUP) |
Example paths:
GET [BASE_URL]/api/v1/vaults
GET [BASE_URL]/api/v1/vaults/acme-otc/balances
POST [BASE_URL]/api/v1/vaults/acme-otc/transfers
POST [BASE_URL]/api/v1/evaluate
Webhooks live outside /api/v1
The incoming Wallet Service webhook lives separately from the API prefix, at [BASE_URL]/webhooks/wallet. This is where Wallet Service sends its events (TOPUP). For details, see the Handle an incoming deposit guide.
Conventions in examples
In all examples, the base URL and token are stored in environment variables:
export V3_BASE_URL="[BASE_URL]"
export V3_TOKEN="YOUR_API_TOKEN"
const BASE_URL = process.env.V3_BASE_URL; // [BASE_URL]
const TOKEN = process.env.V3_TOKEN;
import os
BASE_URL = os.environ["V3_BASE_URL"] # [BASE_URL]
TOKEN = os.environ["V3_TOKEN"]
The token is passed in the Authorization: Bearer <token> header. See Authentication.
Common mistakes
| Symptom | Cause |
|---|---|
404 on every call | the /api/v1 prefix is missing |
| webhook doesn't arrive | it's being sent under /api/v1, but it lives outside the prefix, at /webhooks/wallet |
| Vault not found by path | the path expects the code, but an id was passed |
[BASE_URL] sent in a request | the placeholder wasn't replaced with the instance address |
double // in the URL | BASE_URL ends with a slash and the path starts with one |