Skip to main content
A payments business needs to know, reliably and quickly, that a customer’s funds have arrived. This solution creates a wallet per customer, exposes each customer’s deposit address, and turns on-chain deposits into signed webhook events your ledger can consume.

​
What you’ll need

  • A sandbox or production workspace and an API key with the wallets:create, wallets:read, assets:attach, balances:read and webhooks:manage scopes.
  • An HTTPS endpoint that can receive webhook deliveries.
  • A place in your own system to store the mapping from customer to wallet_id.

​
Components to configure

​
Steps

1

Create a wallet for each customer

POST /api/v1/wallets with the customer’s identifier as name and an X-Idempotency-Key derived from it, so a retried onboarding never creates two wallets. Creation is asynchronous; store the returned wallet_id and wait for wallet.created before showing the customer an address.
2

Attach the assets customers may deposit

PUT /api/v1/wallets/{wallet_id}/asset/{asset_id} for each supported asset. The response carries the deposit address, derived by the platform from the wallet’s key. On EVM networks one address serves the native asset and its tokens. Read it back at any time with GET /api/v1/wallets/{wallet_id}/deposit-address.
3

Register a webhook

POST /api/v1/workspaces/{workspace_id}/webhooks with your HTTPS URL and the events deposit.detected, balance.updated and deposit.failed. Fetch the workspace’s verification key from GET /api/v1/workspaces/{workspace_id}/webhook-verification-key and verify the Ed25519 signature on every delivery before acting on it.
4

Credit the customer on delivery

Map the event’s wallet_id back to the customer and credit your ledger. Deliveries are retried up to ten times with increasing back-off when your endpoint does not return 2xx, so make the handler idempotent on the event’s identifiers.
5

Reconcile daily

Compare your ledger against GET /api/v1/workspaces/{workspace_id}/transactions (or the CSV from /transactions/export) and each wallet’s GET /api/v1/wallets/{wallet_id}/balance/{asset_id}. Balances are read from the chain, so the platform’s numbers are the source of truth for what is actually held.

​
Considerations

  • Detection and confirmation are distinct: deposit.detected means the transfer was seen; the balance reflects it once it is confirmed. Decide which one your product credits on, based on the amount and your risk appetite.
  • Sweeping customer deposits into a treasury wallet is an outbound transfer like any other (see Automate payments) and is subject to your policies.
  • Give the API key that creates wallets no withdrawal scope. Keys are scoped per capability; a deposit service never needs withdrawals:create.