Tizondocs
Guides

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 it is still being created — poll until it is active rather than treating null as an error.

To show a payer one address, ask for that one. It is created if the account does not have it yet, and no other is:

curl -G https://api.tizon.mobile/v1/wallet/addresses \
  -H "Authorization: Bearer $TIZON_KEY" \
  -d asset=USDT \
  -d network=trc20

asset and network go together (400 invalid_query_parameter for one alone), and the pair must be accepted (400 unsupported_network for USDC on trc20). Without them you get every destination, each created on first request. If one cannot be created right now, the response is 502 rail_unavailable: retry shortly.

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.

Without a filter, the list also holds the account's dedicated bank virtual account, 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. If no invoice can be minted right now, nothing is created and the response is 502 rail_unavailable: retry shortly.

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

RailGood forWatch out for
USDT / USDCTopping up in bulk, any amount, no expiryTwo-step credit; right network per asset
Bank transferFunding from a local accountSlowest to land
LightningExact amounts, instant creditExpires; 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

On this page