Custodian API Overview

The Xellar Custodian API lets you create and manage custodial wallets, accept crypto deposits via invoices, send withdrawals, track off-chain balances and transaction history, and receive real-time events through outbound webhooks.

What You Can Do

• Account & Wallets — Create custodial accounts and read their wallet addresses per network.
• Listen Wallet — Subscribe on-chain addresses so incoming deposits are detected.
• Invoice — Generate a payment request (a deposit address + amount) and track its status.
• Withdraw — Estimate fees and send funds to an external address.
• Assets & Transactions — Read your off-chain balances per token and your ledger history.

Understanding Balances

Xellar tracks money in two ways. You only interact with off-chain balance through the API — but it helps to know both exist.

On-chain balance

Think of this as the real coins sitting inside a wallet address on the blockchain.

When someone sends crypto to a deposit address, the tokens land here first. Xellar reads this from the blockchain and keeps it updated behind the scenes. You do not query on-chain balance through the Custodian API — it is used internally to detect deposits and move funds.

Off-chain balance

Think of this as your app's account book at Xellar — a running total of how much you own, per token.

This is what you see in Assets, what withdrawals spend from, and what deposit webhooks update when a payment is credited. It is fast, consistent, and what you should use for your product logic.

How they connect (simple flow)

1. Deposit arrives — crypto lands on-chain at a wallet address.
2. Xellar detects it — the on-chain transfer is matched to an invoice or listen wallet.
3. Your balance is credited — Xellar adds the amount to your off-chain balance (activeBalance).
4. You withdraw — the request deducts from off-chain balance; Xellar sends the tokens on-chain to the recipient.

Rule of thumb: If an API response includes pendingBalance, activeBalance, withholdBalance, or latestBalance, that is off-chain. On-chain amounts only appear inside webhook transaction objects as the raw blockchain transfer that triggered an event.

• Webhook — Get notified on account creation, deposits, invoice lifecycle, and withdrawal status changes.

Base URL

All client endpoints are served under the /api/v1 prefix.

Authentication

Every client endpoint (except a couple of public listener endpoints) is protected by an ED25519 request signature. You authenticate using an App ID and a private key that you generate from the Xellar Dashboard.

See Authentication to get your key pair and learn how to sign requests.

Getting Started

1. Get your App ID and private key from the dashboard.
2. Create an account to provision custodial wallets.
3. Create an invoice or subscribe an address to receive deposits.
4. Configure a webhook to get real-time updates.

Need help? Email support@xellar.co or Telegram @xellarsupport.