Overview

X402Flex protocol standardizes x402 payments across EVM chains supporting multiple payments, agentic sessions, and subscriptions so humans and agents share one canonical payment playbook.

What you get

• Router-only settlement with a single PaymentSettledV2 receipt schema.
• SDK-first integration via @pepay/x402flex.
• x402Flex middleware via the same canonical SDK package.
• API + relay services for invoices, sessions, and gift cards.
• Agent readiness (MCP server + x402 reference tooling).

Core primitives

• PaymentIntent – typed struct executed by the router (paymentId, merchant, token, amount, deadline, payer, resourceId, referenceHash, nonce).
• FlexWitness – witness that binds scheme + payer to the intent hash.
• ResourceId – deterministic hash of chainId + merchant + token + amount + referenceId + salt.
• SchemeId – keccak of scheme string (exact:evm:permit2, push:evm:direct, ...).
• Reference tags – session and resource tags appended to reference strings for SessionGuard accounting.

Docs focus

These docs are SDK- and API-centric (payment + x402 patterns), not UI component guidance.

Docs navigation

• Quickstart
• Payments Architecture
• Invoices
• API Usage
• SDK Reference
• x402Flex
• WordPress

Repo map

Package	Purpose
packages/x402flex	Canonical SDK package (@pepay/x402flex) for API + contracts + x402 wrappers
bnbpay-api	Indexer + REST API + relay endpoints
contracts/payments	Router + X402FlexRegistry + X402FlexSessionStore + X402FlexSubscriptions
mcp-server	Agent-facing tools (Claude/Codex)
bnbpay-wp-woocommerce-extension	WooCommerce payment gateway

Next steps

1. Quickstart – run a full invoice → payment → confirmation loop.
2. Payments – understand router-only settlement and scheme coverage.
3. API + SDK – choose whether to call the REST API directly or via createApiClient.
4. x402Flex – ship HTTP 402 flows for API monetization.