Monero Deposit Reconciliation Before a Swap Payout13 min read2,639 words

Monero Deposit Reconciliation Before a Swap Payout

Learn how to reconcile Monero deposits before a swap payout, from subaddress mapping to confirmations and exception handling. Build a safer release workflow.

Monero deposit reconciliationMonero swap payoutXMR confirmationsMonero subaddresscross-chain swaps
Monero Deposit Reconciliation Before a Swap Payout

How to Verify a Monero Deposit Before Releasing a Swap Payout

In a cross-chain swap, there's a moment where an incoming payment turns into an outgoing obligation. If the source asset is Monero (XMR), you can't treat that handoff as a quick "check the transaction on a block explorer" step. Monero hides transaction amounts and recipient details from public observers, so your backend has to verify the deposit using wallet data and tie it to the right order.

That sounds simple - until deposits arrive late, show up short, get reported more than once by your scanner, or change status after a chain reorg. Release the destination asset too early and you may have no practical way to recover it. Hold everything forever and your service grinds to a halt. The goal is a release decision that's reliable, explainable, and recoverable - not just "able to detect an incoming transfer."

This guide walks through a reconciliation workflow: create a unique deposit mapping, scan incoming wallet transfers, set confirmation rules based on risk, and handle ambiguous payments without breaking order records. It also covers operational controls that help prevent a deposit-processing service from holding spending keys it doesn't need.

Start with an order-to-deposit model

The first design decision isn't how often to poll the wallet. It's how your system knows which order an incoming payment belongs to. With Monero, public transaction data doesn't give an outside observer enough information to reliably map a customer's payment amount to a specific recipient and order. Your own wallet can see incoming transfers, but your application still needs a safe mapping from wallet activity to an order.

Use a unique subaddress for each order

Generate a new Monero subaddress for every order and store the mapping in your database. A subaddress is a receiving address tied to a wallet; the wallet can report incoming funds to it, while public blockchain data doesn't expose the same customer-to-order link.

Store what you'll need for the payout decision, including:

  • Order ID and customer or session reference, where appropriate
  • Wallet account and subaddress indices
  • The generated deposit address
  • Expected amount and asset
  • Destination asset and chain
  • Order creation time and expiry
  • Applicable underpayment and late-payment policies

Don't reuse a subaddress or move its mapping to a new order after expiry. Customers sometimes pay after they think the order is over. If the address gets reassigned, you can end up crediting an old payment to the wrong order. Keeping expired orders searchable also makes late deposits traceable to their original context.

Keep order state separate from payment observations

An order and a transfer are related, but they're not the same record. An order can receive multiple transfers - for example, an initial partial payment followed by a top-up. And your scanner might observe the same transfer multiple times while it polls the wallet.

Keep those things separate. Store the order with its expected terms and status. Store transfer observations keyed by stable identifiers like transaction ID and subaddress index. Then compute how much you've credited to an order from its associated observations, instead of incrementing a running balance every time a polling job runs.

This separation is what makes retries safe. If you don't do it, a scan retry after a timeout can accidentally credit the same transfer twice. One manual correction is survivable; doing that at scale is where operational incidents happen.

Give each service only the access it needs

Deposit detection doesn't require the order-processing service to hold spending keys. A view-only wallet can scan incoming funds. A separate, tightly controlled signing component should handle outgoing transfers. Split those responsibilities whenever your architecture allows it.

This won't make you invincible, but it reduces damage if something goes wrong. A service that can match deposits but can't spend them has a smaller blast radius than one that can both observe incoming funds and authorize payouts. When you wire up Monero, read the Monero wallet RPC documentation so you understand what your wallet integration can expose.

Identify and reconcile incoming XMR

Once an order has a unique receiving address, you need a reliable way to view wallet activity. Use a wallet connected to a synchronized Monero daemon and query incoming transfers through the wallet interface - for example, via the get_transfers wallet RPC method. The wallet provides the account/subaddress info you need to match the transfer to your order mapping.

Match the wallet record to the order

For each incoming transfer, match the wallet's account and subaddress indices to the stored order mapping. Then:

  • Verify the order is eligible to receive payment
  • Record the transfer's transaction ID, amount, confirmation state, and timestamps you'll need later

Compare amounts in atomic units instead of rounded display values. One XMR equals 1,000,000,000,000 atomic units. Integer comparisons avoid rounding issues and floating-point errors. Don't try to derive an order's paid amount from public transaction data - Monero's privacy model means that's the wrong source for reconciliation.

A practical reconciliation rule is:

  1. Identify the wallet account and subaddress for the transfer.
  2. Find the matching order mapping, including any expired orders you still track.
  3. Record the observation once using an idempotent key.
  4. Compare the cumulative qualifying amount with the order terms.
  5. Update order status only after applying the order's payment policy.

The word qualifying matters. A transfer might be visible in the wallet but still be unconfirmed, below the expected amount, or linked to an expired order. Detection is about what the wallet currently shows; payout eligibility is your business decision.

Treat polling as repeated observation, not a one-time event

A backend will check wallet activity more than once. Your scanner should handle retries, missed requests, and temporary outages. Re-reading the same transfer must not create a second credit, and a failed poll must not be treated as proof that no deposit exists.

Use a durable scan cursor (or a similar recovery approach), but don't rely on it as your only safety net. On restart, rescan an overlap from a safe earlier height or range and deduplicate observations. That overlap helps you catch events near a process interruption; idempotency ensures you don't count them twice.

Also separate a few situations:

  • Wallet unavailable
  • Wallet exists but is still syncing
  • Scan completed successfully and found no new transfers

Those states have different consequences. If the wallet is behind the daemon, you can't safely treat its latest view as "complete."

Define the amount policy before an order is created

The expected amount and acceptable variance should be part of the order terms. If you require an exact amount, say so. If your service accepts a bounded shortfall or calculates the destination amount from what was actually received, define that up front too.

Don't make a silent assumption like "close enough counts." At minimum, spell out how you handle:

  • Exact payments
  • Underpayments and later top-ups
  • Overpayments
  • Multiple transfers for one order
  • Deposits after expiry
  • Transfers whose destination address matches no active order

This is a product and operations decision, not something the wallet API can decide for you. Clear rules reduce support chaos and stop different operators from improvising different outcomes for similar cases.

Set a confirmation gate before payout

Seeing a transfer in a wallet doesn't automatically mean the destination asset is safe to release. Your payout policy needs a confirmation requirement by risk tier, and your service has to check that requirement right before acting.

Treat confirmation count as a risk input

Monero targets a block roughly every two minutes. Wallets commonly need 10 confirmations before an output is unlocked, which works out to about 20 minutes on average. That's a reasonable operational baseline, but it's not a guarantee of final settlement time - and it's not a universal rule for every swap design.

Pick a threshold based on what's at stake and how costly it would be if you hit a reorganization (where blocks you saw get replaced by a competing chain). A small payout and a large payout shouldn't necessarily tolerate the same level of exposure. You can choose higher thresholds for larger amounts, or add limits that prevent large payouts from being released until additional checks pass.

Keep two wallet facts conceptually separate:

  • Confirmation count: how many blocks have followed the block that contains the transfer.
  • Locked status: whether the output is currently spendable by the wallet.

Neither fact alone defines your business risk policy. An output can be confirmed but still not spendable under wallet rules, and your service's acceptable risk might be stricter than the wallet's spendability threshold. Don't treat "the wallet can spend it" as the same thing as "we should release now."

Gate on fresh, synchronized wallet state

Right before sending the destination asset, recheck the deposit. Confirm that:

  • The wallet and daemon are synchronized and reporting a usable current state
  • The transfer still appears in the wallet results
  • Its amount and subaddress match the order record
  • It meets your configured confirmation threshold
  • It's confirmed, not just observed in the transaction pool
  • The wallet reports double_spend_seen as false

A transaction you've seen but that isn't mined yet is not a confirmed deposit. You can use it for customer-facing "we detected payment" messaging, but it shouldn't satisfy a payout gate that requires confirmations.

Use one clear payout decision point. The decision should read the latest eligible order and transfer state, apply the current policy, and then either authorize the payout or record why it's still blocked. If you send the destination transaction in a separate worker, pass an authorization tied to the specific order and source transfer. Don't rely on stale status from the UI.

Make the threshold configurable, not improvised

Store and version confirmation policy as a business rule. If you change thresholds later, you'll want to know which policy governed payouts made last week. Record the policy version (or at least the actual threshold used) alongside the payout decision.

You don't need complicated tiers everywhere. A simple policy can be safer than a "smart" one nobody can explain. The real test is whether an operator can explain why a deposit was released, held, or escalated without rebuilding the decision from logs.

Handle exceptions and preserve an audit trail

Most reconciliation problems don't happen in the happy path. They show up at the edges: wrong amounts from customers, expired addresses, scanner retries, or a transfer that looks confirmed and then isn't in the wallet's later view. Decide how you handle these cases before real funds depend on your implementation.

Keep partial, late, and unmatched payments pending

Say an order expects 0.50 XMR, but the wallet reports 0.47 XMR to its subaddress. Record what was received, but don't mark the order as fully paid. Apply your underpayment policy and keep the order pending until it meets the required threshold.

If the customer later sends the remainder, reconcile that as another transfer against the same order, then evaluate the combined qualifying amount.

A deposit received after expiry should stay attached to the expired order mapping. Route it to your review, refund, or manual-resolution process. Don't assign it to a new order just because the address appears in a new user session or because the old order isn't visible anymore.

For duplicate observations, use idempotency keys based on the transfer identity and subaddress context. The outcome should be the same whether the scanner sees a transfer once or ten times.

If a transfer can't be matched to an order, keep the observation and send it to a review queue. Don't discard it, and don't guess.

Respond explicitly to a chain change

If a transfer that was previously confirmed disappears from confirmed wallet results, stop any payout that hasn't been released yet. Rescan from a safe earlier height and reconcile the wallet's updated view with the stored transfer record. Don't assume the earlier status is still valid just because it was in your database.

If the destination transaction has already been sent, that's a different scenario. A source-chain reorganization doesn't magically reverse a finalized transaction on another chain. Mark the order for reconciliation, preserve both the source and destination records, and follow your defined recovery process. Depending on your system, this can mean an operational loss, a reserve draw, or a support case. A cross-chain architecture can't delete that problem after the fact.

Keep the evidence behind every payout decision

For each order, retain:

  • The deposit mapping
  • Transfer observations
  • Received amounts
  • Confirmation counts
  • Wallet synchronization state
  • The policy you applied
  • The final payout decision

Store timestamps and enough context to explain what the service knew at the time it acted.

Your audit record isn't only for compliance or post-incident reviews. It's how you recover when a worker crashes between authorizing and sending a payout, or when a customer disputes whether a deposit arrived before expiry. Preserve the source-side evidence and the destination-side transaction reference so the two legs can be reviewed together.

Before using real funds, test the whole lifecycle on a non-production network or in a controlled test setup. Include at least one partial payment, a delayed deposit, a repeated scanner observation, and a wallet resynchronization. A happy-path test proves detection works. The messy cases prove your order state stays correct when the real world isn't tidy.

Conclusion

A safe Monero-to-cross-chain payout flow comes down to one separation: the wallet reports what it observed, and your order policy decides whether that observation is enough to release value. Unique subaddresses, atomic-unit accounting, idempotent transfer records, risk-based confirmations, and a fresh pre-payout check make the decision auditable and repeatable.

Start by documenting your order states and exception policies, then test partial and delayed payments before you connect the flow to production funds. If your team can't explain why a specific transfer qualified for payout, held it, or escalated it, the reconciliation process still needs work before the next swap goes out.

Frequently Asked Questions

Not reliably. Monero conceals transaction amounts and recipient details from public observers. Use your wallet's incoming-transfer records to match a deposit to its subaddress and order; do not infer the customer's payment from public blockchain data.
There is no universal threshold for every swap. Monero targets blocks about every two minutes, and 10 confirmations is a commonly used baseline, or roughly 20 minutes on average. Set your threshold according to the value at risk and your reorganization policy, then recheck wallet state before payout.
Yes, in most order-based deposit flows. A unique subaddress gives the wallet a clear way to associate an incoming transfer with an order. Keep the mapping after expiry so late payments remain attributable, and do not reuse the address for another order.
Record the transfer against its original order and apply the policy communicated when the order was created. Keep an underpaid order pending until it qualifies, and route a late payment to review, refund, or another defined resolution path. Never silently credit it to a different order.

Related articles