Funding a wallet
Stablecoins, bank transfer and Lightning — and what each one is good for.
Fund the wallet once and every purchase afterwards is a single call that either succeeds
or returns 402 with the shortfall. Nothing waits on a payment.
There are two shapes of funding, and the difference matters:
- Standing destinations — a bank account and a stablecoin address per asset and network. They never change, and anything sent to them credits the wallet.
- Lightning invoices — minted per payment, for one amount, and they expire.
Standing destinations
curl https://api.tizon.mobile/v1/wallet/addresses \
-H "Authorization: Bearer $TIZON_KEY"{
"object": "list",
"data": [
{
"id": "addr_01J9Z8W5P2R6T9V3Y7B1E4H8K2",
"object": "funding_destination",
"type": "crypto_address",
"asset": "USDT",
"network": "base",
"address": "0x5f1c9a3e7b424d189e650c7a2d4b8e31f0a9c6d2",
"memo": null,
"status": "active"
}
],
"has_more": false,
"next_cursor": null
}USDT is accepted on bep20, base and trc20; USDC on base and bep20. Stablecoins
credit 1:1 with USD. A destination may come back with address: null and
status: "pending" while the provider is still generating it — poll until it is active
rather than treating null as an error.
Test and live destinations are different addresses. Never send real money to a test destination: a test wallet credit is not real, and the funds are not recoverable through the API.
There is also a dedicated bank virtual account in the same list, as a
bank_account destination.
Deposits credit in two steps
A stablecoin deposit is detected first, then confirmed. While detected it sits in
the wallet's pending_credit — visible, but not spendable and not part of balance. On
confirmation it credits the balance.
So a wallet can show a deposit you cannot yet spend. Read available_to_spend, not
pending_credit, when deciding whether a purchase will go through.
Both steps emit events: deposit.detected, then deposit.confirmed and
wallet.credited.
Lightning top-ups
To top up by a specific amount, mint an invoice:
curl https://api.tizon.mobile/v1/wallet/lightning_invoices \
-H "Authorization: Bearer $TIZON_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "amount": 2000 }'amount is USD cents to credit, at least 100 (Lightning cannot carry a sub-cent payment)
and at most 500000.
The invoice is denominated in USD by a USD-settling receiver: the payer sends satoshis and
the wallet is credited amount whatever the rate does in between. amount_sats is
indicative only — never settle on it.
Because an invoice is for one amount and expires, this mints a new one each time and takes
an Idempotency-Key.
To pay for a single purchase without topping up first, do not mint an invoice here —
quote with payment_source: lightning instead. See
on-the-fly payment.
Choosing a rail
| Rail | Good for | Watch out for |
|---|---|---|
| USDT / USDC | Topping up in bulk, any amount, no expiry | Two-step credit; right network per asset |
| Bank transfer | Funding from a local account | Slowest to land |
| Lightning | Exact amounts, instant credit | Expires; one amount per invoice |
Testing it
Nothing above needs real money in test mode:
curl https://api.tizon.mobile/v1/test_helpers/deposits \
-H "Authorization: Bearer $TIZON_KEY" \
-H "Content-Type: application/json" \
-d '{ "amount": 5000, "asset": "USDT", "network": "base", "status": "detected" }'That leaves $50 in pending_credit so you can exercise the gap, then confirm it with
POST /v1/test_helpers/deposits/{deposit_id}/confirm. See
test mode.
Watching the money move
Every movement is on the wallet ledger, oldest to newest:
curl -G https://api.tizon.mobile/v1/wallet/ledger \
-H "Authorization: Bearer $TIZON_KEY" \
-d limit=20