Skip to main content

Run Your Own Router

Running your own router means you operate the on-chain entry point that validates intents, pulls or receives funds, and calls X402FlexRegistry.settleFromRouter.

What “running a router” means​

  • Your router is the only contract allowed to settle into the registry.
  • It enforces scheme rules (Permit2, EIP-2612, EIP-3009, push, AA4337), verifies the witness signature, and emits a single canonical PaymentSettledV2 event via the registry.
  • It is where anti-replay, balance-delta checks, and intent binding live.

Two deployment modes​

If you want your router to settle into the canonical Pepay registry, your router must be allowlisted as a trusted router.

Contact contact@pepay.io with:

  • Chain(s) you need (BNB, opBNB, etc.).
  • Router address + deployment tx.
  • Token allowlist requirements.
  • Whether you need session store integration.

Pepay will:

  • Add your router to the registry trustedRouters allowlist.
  • Grant COLLECTOR_ROLE on the registry so your router can settle.

2) Fully self-host the stack (registry + router + session store)​

If you want full control, deploy the stack yourself and wire it together.

  1. Deploy X402FlexRegistry with a temporary router (use your deployer address to satisfy the constructor).
  2. Deploy X402FlexSessionStore with your session admin.
  3. Deploy X402FlexRouter with the registry + Permit2 addresses.
  4. Wire the session store ↔ router.
  5. Authorize the router in the registry (COLLECTOR_ROLE + trustedRouters).
  6. Allowlist tokens with batchUpdateTokenAllowlist.

Wiring calls:

sessionStore.setRouter(address(router));
router.setSessionStore(IX402FlexSessionStore(address(sessionStore)));
registry.grantRole(registry.COLLECTOR_ROLE(), address(router));
registry.setTrustedRouter(address(router), true);

The repo ships a one-shot Foundry script that performs these steps:

cd contracts/payments
export PRIVATE_KEY=0x...
forge script script/DeployPayments.s.sol:DeployPayments --rpc-url $RPC_URL --broadcast

Optional env vars: FEE_RECIPIENT, SESSION_ADMIN.

Notes for operators​

  • Your router must preserve the canonical event semantics so downstream indexers and agents can trust PaymentSettledV2.
  • Pull schemes enforce exact balance deltas (fee-on-transfer tokens are unsupported).
  • EIP-3009 authorizations must use the intent-derived nonce rule.
  • Sessions require the session store to be wired to your router; otherwise session spends will fail.

If you want help selecting a mode or verifying your deployment, email contact@pepay.io.