Custodian
Overview

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.
  • Deposits — List combined incoming activity (invoices + non-invoice on-chain deposits).
  • Withdraw — Estimate fees and send funds to an external address.
  • Assets & Balances — Public token catalog, off-chain balances, ledger history, convert (per-app), and transfer between apps.
  • Custom transactions — Submit signed EVM contract calls from a custodial wallet.
  • KYC submissions — Create and submit end-user KYC packages (when enabled for your integration).
  • Webhooks — Configure your HTTPS endpoint and inspect delivery attempts.

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 that ledger is keyed depends on your app's balance type (set when the app is created; it cannot be changed later):

Balance typeLedgerWithdraw
per_app (default)One off-chain balance per token for the whole appDo not send walletId
per_walletOne off-chain balance per token and deposit walletYou must pass walletId so the correct wallet's balance is deducted

How they connect (simple flow)

  1. Deposit arrives — crypto lands on-chain at a wallet address.
  2. Xellar detects it — as soon as the on-chain transfer is matched, you get deposit.invoice.pending_confirmation or deposit.wallet.pending_confirmation (confirmationStatus: "pending", not credited yet).
  3. Xellar waits for block confirmations — after the network's confirmation threshold, the invoice is marked paid (if matched) and the ledger is credited.
  4. Your balance is credited — deposit.invoice.paid or deposit.wallet.credited. Treat these as final for product logic.
  5. 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.

Signed API routes (/api/v1)

All routes below require authentication (X-App-ID, X-Timestamp, X-Signature) unless noted as public.

AreaMethodPathDoc
AccountPOST/account/createAccount
AccountGET/account/:subIDAccount
AccountGET/account/:subID/wallet/:walletIDAccount
AccountGET/account/:subID/network/:networkAccount
ListenGET/wallets/listenListen wallet
ListenPOST/wallets/listen/:addressListen wallet
ListenPATCH/wallets/listen/:addressListen wallet
ListenDELETE/wallets/listen/:addressListen wallet
ListenGET/wallets/to-listenListen wallet public
ListenGET/wallets/listen/:address/statusListen wallet public
InvoicePOST/invoicesInvoice
InvoiceGET/invoicesInvoice
InvoiceGET/invoices/:idInvoice
InvoicePOST/invoices/:id/cancelInvoice
DepositsGET/depositsDeposits
WithdrawPOST/withdraws/estimateWithdraw
WithdrawPOST/withdrawsWithdraw
WithdrawGET/withdrawsWithdraw
WithdrawGET/withdraws/:idWithdraw
Custom txPOST/transactionsCustom transactions
Custom txGET/transactions/:idCustom transactions
AssetsGET/tokensAssets public
AssetsGET/assetsAssets
AssetsGET/assets/:tokenCodeAssets
AssetsGET/transaction-historiesAssets
AssetsPOST/balances/convert/estimateAssets
AssetsPOST/balances/convertAssets
AssetsPOST/balances/transferAssets
WebhookGET/webhooks/settingsWebhook
WebhookPUT/webhooks/settingsWebhook
WebhookDELETE/webhooks/settingsWebhook
WebhookPOST/webhooks/testWebhook
WebhookGET/webhooks/deliveriesWebhook
KYCPOST/kyc/submissionsKYC
KYCGET/kyc/submissionsKYC
KYCGET/kyc/submissions/:idKYC
KYCPATCH/kyc/submissions/:idKYC
KYCPOST/kyc/submissions/:id/documentsKYC
KYCPOST/kyc/submissions/:id/submitKYC

Base URL

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

EnvironmentBase URL
Developmenthttps://custodian-api-dev.xellar.co/api/v1
Productionhttps://custodian-api.xellar.co/api/v1

Authentication

Every client endpoint (except a few public reads) is protected by an ED25519 request signature. You authenticate using an App ID and a private key that you generate from the Xellar Panel (opens in a new tab).

Public (no signature): list addresses to listen, listen status, and list allowed tokens.

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 Xellar Panel (opens in a new tab).
  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.

Supported NetworksAuthentication