Skip to content

Overview

This API lets your application programmatically open custody accounts for end customers, generate deposit wallets, move funds, and receive event-driven notifications.

Core concepts

The platform is organized around five concepts. Build a mental model of these before writing code.

Vault

A vault is the top-level container for a single end-customer's holdings.

  • One vault per customer.
  • Holds one or more wallets (one per asset).
  • Acts as the boundary for balance and audit reporting.

Created via POST /vaults.

Wallet

A wallet holds the balance for one asset (BTC, ETH, USDT, …) inside a vault. Each wallet exposes one or more deposit addresses on the asset's native chain.

  • Created via POST /vaults/{vaultId}/wallets.
  • Has its own balance.
  • Has a deposit address you give to the end-customer.

Transaction

A transaction is any movement of value involving a wallet. Three kinds:

Kind Trigger On-chain?
Deposit Funds arrive at a wallet address. Yes (detected automatically).
Internal transfer POST /transactions/transfer between two wallets you control. No.
Withdrawal POST /transactions/withdraw to an external address. Yes.

Transactions progress through statuses: Submitted → PendingSignature → Broadcasting → Confirming → Completed (or Failed / Cancelled).

Address book

A per-tenant allow-list of external addresses. Withdrawals can only target addresses that already exist in the address book — protects against typos and limits damage from leaked keys.

Managed via /address-book endpoints.

Webhook

A single HTTPS endpoint you register to receive real-time event notifications: deposits credited, withdrawals confirmed, address-book changes, vault status changes.

Each delivery carries an X-Webhook-Signature header (HMAC-SHA256 of the body using your signing secret) so you can verify it came from us.

Managed via /webhooks/* endpoints — see Webhook integration.

A typical integration

The first end-to-end flow you will build:

  1. Get an API key from your tenant administrator. The key carries scopes (vaults:write, wallets:create, etc.) and may carry an IP allow-list.
  2. Create a vault for each end-customer (POST /vaults).
  3. List enabled assets for your tenant.
  4. Create wallets in each vault for the assets the customer needs (POST /vaults/{vaultId}/wallets).
  5. Give the customer the wallet's deposit address.
  6. Configure a webhook so you hear about deposits in real time, instead of polling.
  7. For outbound transfers, add the destination to the address book first, then call POST /transactions/withdraw.

Authentication, scopes, environments

  • All requests are signed with HMAC-SHA256. Three required headers (X-API-Key, X-Timestamp, X-Signature). Full details in Authentication.
  • Each key is granted a set of scopes. A request that targets an endpoint needing a scope your key doesn't carry returns 403.
  • Two environments — sandbox and production — with separate keys (..._test_… vs ..._live_…). Pick the matching server in the API Reference when calling out.

Next