Security, Architecture & Production

Writing code that detects a Monero payment is the easy part. Running that code in production — where real money flows through it and attackers are actively probing — is where integrations succeed or fail. This lesson covers the architecture and operational discipline that keep an integration safe: separating hot from cold, trusting only your own infrastructure, handling confirmations and reorgs correctly, and treating keys and user data with the care they deserve.

Separate hot from cold

The single most important architectural decision is that your online payment server should run a watch-only wallet. A watch-only wallet holds the view key only — it can see incoming payments and generate subaddresses, but it cannot spend. If your internet-facing server is breached, the attacker learns who paid you, but they cannot move a single piece. There is nothing to steal.

Keep the spend key offline. Withdrawals and payouts should be signed on a separate, locked-down signer: ideally a cold or air-gapped machine, or at minimum a hot signer holding only a small float with strict per-transaction and daily limits. The pattern mirrors how exchanges operate: a thin hot wallet covers day-to-day outflows, and the bulk of funds sit in cold storage. Sweep deposits to cold regularly so the online side never accumulates a tempting balance.

Trust your own infrastructure

Run your own monerod. A remote node you do not control can lie to you — about how many confirmations a transaction has, about the current chain height, or about whether it is even synced. For a payment processor those lies translate directly into stolen goods. Your own node verifies everything itself.

• Bind locally. Run monero-wallet-rpc on localhost and firewall it so nothing on the public internet can reach it.
• Require authentication. Use --rpc-login so even local processes must present credentials, and rotate those credentials.
• Restrict anything exposed. If a daemon RPC port must be reachable, run it in restricted mode so it cannot leak privileged information.
• Consider Tor for your node's peer-to-peer traffic to avoid revealing your server's IP and to harden against network-level surveillance.

Confirmations, locks, and reorgs

Never credit an order until its payment has enough confirmations for the value at stake — a few dollars might need one or two, a large invoice considerably more. The deeper a transaction is buried, the harder it is to undo.

Crucially, a chain reorg can drop a transaction that you already saw, so a payment can un-confirm. Design your credit logic to handle this: do not treat a single sighting as final, and be prepared to reverse provisional state if a transaction disappears from the chain. This is why waiting for sufficient depth matters — it makes reorgs that would undo your credit vanishingly unlikely.

Also remember the 10-block lock: funds you receive are not spendable for roughly 20 minutes regardless of how many confirmations you require for crediting. Even if you credit a customer quickly, you cannot turn around and spend those exact outputs immediately, so size your hot float accordingly.

Idempotency and correctness

Networks retry, processes restart, and webhooks fire twice. Your money-handling code must be idempotent so none of that causes harm.

• Store the tx_hash for every deposit you credit and every withdrawal you send. Before acting, check whether you have already processed that hash. Never double-credit a deposit or double-send a withdrawal on retry.
• Verify exact amounts in atomic units — 1 XMR is 1e12 atomic units. Compare integers, never floating-point, and confirm the received amount matches what the invoice expects.
• Handle underpayment and overpayment explicitly: decide whether to hold, refund, or partially fulfill, and make that decision deterministic rather than letting edge cases fall through.

Operational resilience

An integration is only as reliable as the daemon behind it. Build in monitoring and graceful degradation.

• Monitor sync. Poll get_info and compare height against target_height; alert if your node falls behind, because a lagging node will miss or mis-time payments.
• Expect busy responses. Handle "daemon is busy" and refreshing states by backing off and retrying rather than crashing.
• Persist the wallet. Call store to flush wallet state to disk so a restart does not lose track of what you have seen.
• Design for restarts and rate-limit your RPC calls with sensible back-off so you never overwhelm your own daemon.

Key management

Treat keys as the crown jewels. Encrypt wallet files at rest, and protect and back up your seeds and spend keys offline. Never log secrets — view keys, spend keys, seeds, or RPC passwords should never end up in application logs or error reports. Rotate RPC credentials periodically and after any suspected exposure.

Privacy and data minimization

An integration naturally sees view-key data — the incoming amounts to your wallet — and the mapping of subaddresses to users. That is a sensitive dataset that undermines the privacy your users came to Monero for if it leaks. Minimize what you store and how long you keep it: retain only what you genuinely need to reconcile payments, and prune the rest. Avoid storing IP addresses alongside payment data, since correlating the two reconstructs exactly the surveillance Monero is meant to prevent. Keeping your users private is part of running the integration responsibly.

Test before you go live

Never debug payment logic with real money. Test on stagenet or testnet first: the coins are free, the software is identical, and you can exercise confirmations, reorg edge cases, retries, and failure paths without risk. Only point your integration at mainnet once it behaves correctly against the test networks.

Next: Building Real Services