SatLane
Skip to documentation
Browse documentation
On this page

Test and live mode

Wallet-free Sandbox on enabled installations

On an installation with wallet-free Sandbox enabled, select Sandbox in the dashboard. A new store has pending Live activation, and Test invoice creation does not require an xpub. External integrations use a test API key and send SatLane-Version: 2026-10-05 on invoice creation. Without that header an enabled Test create returns sandbox_contract_required (426).

Test invoices have environment: "test", address: null, payment_uri: null and a simulated payment_destination with null network/address/URI. Do not generate a QR code, wallet link or payment address for them. Simulate outcomes from invoice details or the authorized simulation endpoint. Test activity is isolated from Live receipts, allocations and billing; it does not consume real Bitcoin or accrue a Live payment fee.

Live uses a Live API key, explicit store activation, an active mainnet receiving xpub, account eligibility and synchronized chain services. Selecting the Live workspace changes the view; it does not activate a store. Pausing stops new Live invoices while existing payments and their webhook processing continue. Sandbox stays available independently.

Register each receiving extended public key with only one store. SatLane compares the underlying public key and chain code across all stores, including inactive wallets and archived stores. Changing xpub/ypub/zpub prefixes, network labels or derivation paths does not bypass this check. Use a separate wallet account for a second store. Historical conflicting keys cannot be reactivated or used to create new invoices; existing invoices remain available for payment monitoring.

Legacy installations with rollout disabled

The legacy store test_mode toggle defaults to true. When enabled, it forces Test invoices regardless of the key environment; existing legacy creation requires an active registered xpub. These records can contain an address but are simulated while store test mode is on: do not send real funds.

With the legacy toggle off, the API key environment selects Live/mainnet or Test/testnet wallet requirements. Confirm the returned environment rather than inferring behavior from a key prefix. Legacy destinations and historical records are not silently converted to the new wallet-free contract. Real testnet support is not part of the new simulated Sandbox contract.