Wallets

A TxNod wallet is the dashboard’s representation of an extended public key (xpub) you have registered for a single chain. Once verified, the wallet is bound to one or more projects, and the chain-watcher derives a fresh receive address per invoice from the xpub. This page covers the five concepts you need to operate wallets confidently: why sharing an xpub is safe, what index 0 is, the pool-address model, what archival means, and how rotation works.

xpub privacy

An xpub is the public half of an account-level wallet key. Anyone who has it can derive every receive address that wallet has ever used and watch them on-chain — but not sign transactions out of those addresses. The matching private key never leaves your hardware wallet or seed-managed software wallet.

That guarantee is what makes TxNod’s non-custodial design possible. The system never touches a private key, mnemonic, or signing material; only xpubs and public stake addresses (for Cardano) enter the database. Sharing your xpub with TxNod is the same kind of disclosure as putting a single receive address in a partner’s invoice — except it lets the dashboard derive a new address per invoice instead of reusing one. If you ever decide to stop using a wallet, you stop binding it to projects; the old xpub becomes irrelevant the moment no project routes invoices to it.

Index 0

The first address derivable from your xpub is called index 0 — “this is the first address your Ledger Live (or Sparrow) shows as ‘Account 0 · index 0’.” TxNod reserves this address for a one-time handshake: when you register a new wallet, the dashboard displays the index-0 address and asks you to send a tiny amount of the chain’s native asset to it from any wallet you control. The chain-watcher confirms the inbound transaction and flips the wallet status from pending → verified. The handshake is the proof that you actually control the xpub you pasted; without it, anyone could try to register an xpub they read off a block explorer.

Pool model

Once verified, TxNod allocates pool addresses from your xpub starting at index 1, 2, 3, and onward — index 0 stays reserved for the handshake and is never used for invoices. When you create an invoice, the dashboard picks the next available pool index, derives its address, and locks the address to the invoice for the duration of the expiry window. Once the invoice settles (paid, expired, or otherwise terminal) the address goes through a cooldown before it can be reused, so a stale payer can’t accidentally pay an unrelated invoice. New addresses are allocated as needed; you never need to top up a hot wallet or pre-derive anything.

Archive semantics

When you no longer want to bind a wallet to new invoices, archive it. Archival is non-destructive:

The wallet stays visible in the wallets list (dimmed) so you can still read its history.
Existing pool addresses keep being watched until all open invoices settle or expire — this is the reorg-safety window that prevents a late confirmation from being missed because you archived too early.
You cannot bind new projects to an archived wallet.
You can unarchive later if needed.

Archival is the right move when you are rotating to a fresh xpub (see Rotation below) and want the old wallet to stop accepting new invoices but keep settling the ones already in flight.

Rotation

Rotation is the recommended way to retire an xpub: switch a project’s chain binding from the old wallet to a new one, leaving the old wallet non-archived so existing invoices keep settling against it. When you confirm a rotation in the dashboard:

New invoices on that chain in that project use the new wallet’s next available pool address.
Existing open invoices keep watching the old wallet until they settle or expire.
The old wallet stays available — rotation is not an archive.

Your partner app’s SDK must list BOTH xpubs during the overlap window, so address verification still works on older invoices.

This is a load-bearing detail for SDK consumers: if you only configure the new xpub on the partner side and an older invoice is still open, the SDK’s address-belongs-to-this-wallet check will fail when the eventual payment hash carries an address derived from the old xpub. List both xpubs, let the open invoices drain, then drop the old xpub from the SDK config in a follow-up deploy.

The dashboard’s rotation dialog includes a copyable env-var block with both xpubs prefilled, so you can paste it into your partner app’s .env without typing anything.

TRON address activation

TRON is the only chain in TxNod that requires the recipient address to be “activated” with at least 1 TRX (or 1 USDT-TRC20) before it can hold funds. This is a TRON protocol requirement, not a TxNod policy: every fresh address derived from your xpub starts inactivated and is invisible to a sender until someone burns ~0.1 TRX of network fees to activate it.

Operator side

The dashboard wallet detail page for a TRON wallet exposes:

A live list of pool addresses with their activation status (activated / pending).
A capacity summary — how many activated rows you have left before the next invoice fails.
Two activation paths: (a) copy the unactivated addresses as CSV and use any third-party multisend service of your choice; (b) the in-dashboard Ledger funding tool, which builds and broadcasts a single TRON transaction signing each Transfer with your hardware wallet sequentially. Either path leaves the operator non-custodial — TxNod never sees a private key.

Keep at least a small buffer of activated rows ahead of expected invoice load. The pool address allocator refuses to issue an invoice on a TRON wallet whose activated count is zero (see below).

Partner side

A partner site only needs to know about one failure mode: when the operator’s TRON pool has zero activated addresses at the moment of createInvoice, the v1 API returns HTTP 422 with error_code: tron_no_activated_addresses_available. The SDK throws TxnodTronNoActivatedAddressesError; the error’s walletId field carries the operator wallet id (a ULID, guaranteed non-empty) for deep-link UX. Treat it as operator-action-required — surface it to the operator, do not auto-retry; the next invoice on that wallet will succeed only after the operator activates more addresses.

Inbound activation transactions never appear in the partner-facing GET /api/v1/orphan-payments listing — TxNod silently filters them server-side so the partner doesn’t have to dedupe them.

Sandbox projects

Sandbox projects don’t go through the wallet-connect wizard; they auto-provision testnet xpubs at project creation. See the Sandbox projects guide.

Cardano network switch

Cardano browser wallets (Lace, Eternl, Nami, Yoroi, Typhon, Flint) maintain a per-extension network setting — Mainnet vs Preprod / Preview testnet. When you onboard via the Connect browser wallet path at Step 2, the wizard reads the wallet’s currently-selected network from the CIP-30 handshake and asserts it matches the project kind you picked at Step 1:

A kind: 'production' project requires the wallet to be on Mainnet.
A kind: 'testnet' project requires the wallet to be on Preprod (or Preview).

If the wallet’s network does not match, the wizard shows a cip30_wallet_network_mismatch error: “This wallet is on <network>; you selected <expected>. Switch networks in your wallet (or restart the wizard with the other kind) and try again.”

How to switch

The exact UI varies per wallet, but the pattern is the same across all six supported wallets:

Open the wallet’s browser-extension popup (or the full-page dashboard, depending on the wallet).
Find the network selector — usually in Settings → Network, sometimes in a top-right dropdown labelled with the current network name.
Select the network the wizard asked for. The extension will lock the wallet for a moment as it re-syncs.
Return to the TxNod wizard tab and click Retry (or restart the wizard from Step 1 if the connection was dropped).

If your hardware wallet is Ledger-backed, the network selection lives inside the browser extension, not on the device — Ledger devices speak the chain protocol; the wallet extension picks which chain network to broadcast against. The same step 2–4 above applies.

When to use the testnet kind

Cardano testnet xpubs are useful for staging integrations: a separate kind: 'testnet' project on the dashboard lets you exercise the full create-invoice → CIP-30 → handshake → invoice-paid flow against the Preprod network without spending real ADA. See Project kinds for how testnet projects differ from sandbox projects (which simulate the chain entirely; testnet projects use the real testnet chain).

TON soft deploy

A TON wallet contract is “soft-deployed” by default — the contract address is computed deterministically from the public key + version + sub-wallet id, but the on-chain account stays uninitialized until the first outbound transaction broadcasts the contract code. This is a TON protocol quirk, not a TxNod design choice: every fresh TON address is structurally undeployed at the moment of derivation, and stays so until its owner sends from it.

What works on an undeployed wallet

Inbound deposits work fully. The watcher detects incoming transfers (TON or jetton) into the computed address regardless of whether the contract is deployed; invoice settlement (detected → paid) fires normally.

What is unavailable until first outbound

Outbound sweep — the operator action of moving funds out of a derived pool address — is structurally blocked on an undeployed wallet. Sweeping requires the wallet to broadcast a signed message, and the first such broadcast is what deploys the contract. Until you send out at least once from the wallet (any non-zero outbound transaction), the dashboard’s sweep tooling will mark the wallet “outbound-unavailable”.

How to deploy

The standard flow is passive — the next time you initiate any outbound from your TON wallet (Tonkeeper, MyTonWallet, Tonhub, Telegram @wallet, or a Ledger-signed transaction), the broadcast carries the contract code and the wallet flips to deployed. From the TxNod side, no action is required: the chain-watcher detects the deployment in the next polling cycle and clears the “wallet not yet deployed” banner.

If you want to deploy without spending operationally, send 0.01 TON from the wallet to itself — the broadcast is enough to flip the wallet’s state, and the funds return to the same address minus a fee.

Why TxNod surfaces this

The wallet not yet deployed banner appears on a TON wallet’s detail page in the dashboard so you know in advance that the sweep tool is unavailable; you do not need to take any action on the deposit side. The handshake check at Step 4 of the Add-wallet wizard is not affected — the small inbound handshake amount confirms the wallet receives correctly, which is independent of contract deployment.

Troubleshooting

xpub handshake failure

If an xpub has been stuck in pending for more than 1 hour after a handshake send, open Settings → Wallets → <chain> and verify the derived index-0 address.
Double-check in a block explorer that the send transaction is confirmed and its recipient matches the displayed index-0 address exactly.
Common cause: a derivation-path mismatch. BTC uses BIP-84 (zpub) by default; if you pasted an xpub derived under BIP-44, the displayed address will differ from what your wallet thinks index 0 is. Re-derive your xpub under BIP-84 and re-register — see How to export your xpub for the per-wallet steps.
If the transaction is confirmed to the correct address but the handshake still fails, collect the xpub fingerprint, the chain, and the tx hash, then file a support issue.

Cardano stake-address mismatch

The CIP-30 handshake produces both an acct_xvk1 account key and a stake1u-prefixed reward address. If the wizard rejects with cardano_stake_address_mismatch, your wallet returned a stake address that does not match the account key — typically because the wallet is on the wrong network (see Cardano network switch above) or because two extensions are racing to handle the CIP-30 grant. Disable the secondary extension, switch to the correct network, and retry.

TON wallet not yet deployed

The dashboard shows wallet not yet deployed on a TON wallet’s detail page. Deposits work normally; outbound sweep is unavailable until the first outbound broadcast. See TON soft deploy above for the recovery path.