Live & Test Mode

HasaPay runs your integration in one of two modes — Test (testnet networks, play money) and Live (mainnet networks, real funds). It's the same API and the same dashboard; mode simply scopes everything to one world or the other.

Critically, the two worlds never mix. Wallets, addresses, balances, transactions, volumes, and fee totals are all scoped to the active mode — a test-mode call never sees mainnet data, and a live-mode call never sees testnet data. Aggregates are never blended.

How mode is determined

API keys (HMAC) — the key is the mode

For programmatic requests, mode is bound to the API key's environment and is authoritative. You don't send a mode header — the key decides:

Key environment	Key prefix	Mode	Networks
`sandbox`	`tk_…`	Test	testnet (Sepolia, Amoy, Shasta, Devnet, Bitcoin testnet)
`production`	`pk_…`	Live	mainnet

A sandbox/test key cannot touch mainnet, and a production/live key cannot touch testnet — regardless of any header sent. This is enforced server-side, so a leaked test key can never move real funds.

The X-HasaPay-Mode header (below) is ignored for API-key requests. The key's environment always wins.

Dashboard / JWT — the `X-HasaPay-Mode` header

For org-user (JWT) sessions, mode is selected per request with a header:

X-HasaPay-Mode: test     # default
X-HasaPay-Mode: live

If the header is missing or unrecognized, the request defaults to test — the safe default. The dashboard sends this header from its Test/Live toggle. The resolved mode is echoed back on the response as X-HasaPay-Mode for debugging.

Going live requires approval

Live mode is gated. An organization can only operate in live mode (create mainnet wallets, enable mainnet assets, mint production API keys) once it is:

Approved by HasaPay (organization status active), and
KYC-approved.

Until both are true, the org is test-only. Requesting live before approval returns:

{ "error": { "code": "LIVE_MODE_LOCKED", "message": "Live mode is locked until your organization is approved" } }

Creating a mainnet master wallet or enabling a mainnet asset additionally requires KYC approval. Test mode needs no approval — you can build and test the full flow on testnet immediately after sign-up.

Mode mismatch errors

If a request targets a network that doesn't belong to the active mode — for example a test key (or test session) trying to act on a mainnet network — the write is rejected:

{ "error": { "code": "MODE_MISMATCH", "message": "This network is not available in the current mode" } }

HTTP status 403. The fix is to use the correct key/mode for the network you're targeting.

Networks per mode

Chain	Test network	Live network
Ethereum	Sepolia	Mainnet
Polygon	Amoy	Mainnet
Solana	Devnet	Mainnet
Tron	Shasta	Mainnet
Bitcoin	Testnet	Mainnet

Recommended workflow

Sign up → you're in test mode automatically with sandbox keys.
Build and verify your full integration on testnet — wallets, addresses, deposits, sweeps, withdrawals, webhooks.
Complete approval + KYC with HasaPay.
Mint a production API key and switch your dashboard toggle to Live — the same code now runs against mainnet, scoped entirely to real funds.