Skip to main content
On networks where compliance is enabled (mainnet today), every route is screened against sanctions and risk data before its funds move. Screening is automatic and enforced on-chain — as a builder you do not run, attach, or sign anything to “pass” it. This page covers the two things you do need to account for: the screening fee and the verification window (plus what happens on a denial).
You take no action to pass screening. The MultiHopper keeper screens the route and submits the on-chain verification for you. The only builder-facing impacts are funding the screening fee and tolerating a short verification delay before hops execute.

What gets screened

When the gate is on, the route’s origin (the sourceOwner / funding wallet) and every recipient in the route — including the final recipientWallet and all intermediate hops — are screened together. The set is cryptographically bound to the route, so funds cannot be screened against one set of addresses and then moved to another.

The screening fee

The fee is the cost of screening the route’s wallets and is not refunded. The per-wallet amount is configured per network and may change, so read it from /estimate rather than hard-coding it.
Ensure the sourceOwner wallet holds the transfer amount plus /estimate’s requiredSolUpFrontLamports before signing, or the deploy can fail for insufficient lamports. Pass the transfer’s arrivalSeconds (and destinationCount) to the estimate so it prices the same wallets /prepare charges for.

Lifecycle

After your final confirm-broadcast, the transfer sits in processing while the keeper screens the route and submits the on-chain verification. This typically takes a few seconds. Once verified, hops begin executing and the transfer proceeds to completed as normal. Keep polling GET /transfers/{id} — no action is required during this window.

When a wallet is flagged

If any screened address is flagged, the route is not executed:
  • The principal is refunded to the sourceOwner.
  • The screening fee is retained.
  • The transfer ends in refunded status.
  • For privacy and legal reasons, the specific reason for a flag is not disclosed.

Enforced on-chain — not by the API

Compliance is a property of the deployed smart contract, not the API server or keeper. The required compliance account is mandatory on every fund-moving instruction, and the program refuses to move funds for a route that has not been verified while the gate is on. This means a route cannot be constructed to bypass screening, whether it is built through this API or by hand. See the Security Model for the underlying guarantees.

Networks

  • Mainnet — the gate is on. Screening and the fee apply as described above.
  • Test mode (mh_test_* keys) — use test-mode keys to integrate against the lifecycle without moving real value. Verify that your wallet budgets for the fee and that your code keeps polling through the verification window.