Integrations

Package: @perawallet/connect

PagePay connects to Pera via the official browser SDK. There is no Pera Chrome extension — desktop users interact through Pera Web or mobile via WalletConnect QR codes.

Connection flow

1. PeraWalletConnect() instance created once per session
2. connect() → modal / redirect to Pera Web
3. User approves Testnet account
4. connector.activeAccount provides address for UI + signing

Signing flow

1. Build atomic txn group from x402 payment requirements
2. Map to SignTransaction format with explicit signers arrays
3. signTransaction([group]) — do not pass address as second arg in v2 integration
4. Return signed bytes to createPaymentPayload

Disconnect / reconnect

Call disconnect() on logout. Stale sessions can cause silent signing failures — always surface wallet.error in UI.

URL: https://facilitator.goplausible.xyz

The hosted facilitator implements x402 verify and settle for exact-AVM Algorand payments. PagePay's server calls it — clients never talk to the facilitator directly.

Fee sponsorship: the facilitator's feePayer address appears in payment requirement extra. It covers Algorand transaction fees so payers only need USDC + minimal ALGO.

Self-hosting: for production you may run your own facilitator. PagePay demo uses GoPlausible to reduce setup friction.

Testnet USDC is issued by Circle's faucet, not the Algorand dispenser.

1. Go to faucet.circle.com
2. Select Algorand blockchain
3. Select Testnet network
4. Paste your Pera address
5. Submit — USDC (ASA 10458941) arrives in ~4 seconds

Rate limits: the faucet may limit requests per address per day. Use a fresh Testnet address if depleted.

Verification: in Pera, open Assets → confirm USDC balance. In explorer, check /asset/10458941 transfers to your address.

Post-settlement, PagePay calls Groq for text generation when GROQ_API_KEY is configured server-side.

Independence: payment and AI are decoupled. Settlement must succeed before any Groq call. If Groq fails after payment, the tx is still on-chain — handle this as a fulfillment error in production (retry, refund policy, support).

Output format: Groq returns Markdown (**bold**, ## headings, bullet lists). Render with react-markdown — do not display raw Markdown strings.

Version alignment: PagePay pins x402 v2 compatible releases. Mismatch between server and client package versions can cause header decode failures.

These are configured server-side for the demo deployment. Documented here for integrators — do not commit secrets.

Frontend env: wallet and network config are compile-time constants in src/lib/x402/client.ts and src/lib/wallet/pera.ts for Testnet.

Embed or link the /x402-demo page in your onboarding:

• Test Mode — zero wallet setup, instant happy-path walkthrough
• Live flow — real 402 against /api/x402-demo with Groq unlock
• Raw HTTP panel — copy/paste headers for your own client implementation
• Log console — timestamped protocol events for debugging

Simulation modes (failed, timeout, invalid_token) help QA error UI without spending testnet USDC.

Always test payments in a standalone browser window, not IDE previews.