English | 简体中文

x402x (short for x402-exec) is a programmable settlement framework for x402 protocol, combining payment verification, Hook-based business logic, and facilitator incentives in atomic transactions.

Programmable Settlement with Real Atomicity - Not just payment routing, but a complete settlement execution framework that combines payment verification, business logic execution, and facilitator incentives in a single atomic transaction.

🔌 Infinite Extensibility through Hooks

• Revenue splitting for multi-party payments
• NFT minting with atomic payment
• Reward points distribution
• Any custom business logic you can imagine

💰 Native Facilitator Fee Support

• Built-in facilitator fee mechanism enables truly permissionless facilitators
• Solves the key missing piece in the x402 protocol
• Accumulated fees claimable at any time
• Transparent fee tracking through events

⚡ Minimal Integration Overhead

• Only 3 extra fields required in PaymentRequirements
• Single transaction completes everything - no Multicall3 complexity
• Minimal client-side changes (only nonce calculation adjustment)
• Backward compatible with existing x402 infrastructure

🔄 Native Idempotency & Observability

• Built-in replay protection through EIP-3009 nonce
• Complete event logs for reconciliation and monitoring
• Context-based settlement tracking

✅ Revenue Splitting - Automatic multi-party payment distribution
✅ NFT Commerce - Atomic mint-on-payment with revenue split
✅ Loyalty Programs - Real-time reward points distribution

Multi-Layer Protection

• Cryptographic commitment verification prevents parameter tampering
• No-fund-holding principle - Router balance always zero
• OpenZeppelin-based reentrancy protection
• CEI (Checks-Effects-Interactions) pattern enforcement
• 35+ test cases covering edge cases

Client (EIP-3009 Signature)
         ↓
    Facilitator
         ↓
   SettlementRouter ──→ Hook ──→ Recipients
         │                      (Split/Fulfill)
         └→ Events (Observability)

1. SettlementRouter: Core settlement contract

   • Consumes EIP-3009 authorization
   • Calls Hooks to execute business logic
   • Ensures atomicity and idempotency

2. TransferHook (Built-in): Default transfer Hook

   • Simple transfers with facilitator fee support
   • Replaces direct ERC-3009 transfers
   • Minimal gas overhead (~8k gas)
   • Universal deployment (one instance per network)

3. ISettlementHook: Hook interface

   • All business logic implemented through Hooks
   • Fully extensible, supports arbitrary scenarios

x402-exec/
├── contracts/              # Solidity smart contracts
│   ├── src/
│   │   ├── SettlementRouter.sol    # Core settlement contract
│   │   └── interfaces/             # Contract interfaces
│   ├── examples/                   # Hook examples
│   ├── script/                     # Deployment scripts
│   ├── test/                       # Contract tests
│   └── docs/                       # Contract documentation
├── facilitator/                    # Production-ready facilitator service
├── examples/
│   └── showcase/                   # Full-stack demo application
└── docs/                           # Project documentation

If you want to use x402-exec in your own project, we provide an enhanced version of the x402 package. See the Third-Party Integration Guide for details.

Quick Install:

# Using npm alias (recommended)
npm install x402@npm:@x402x/x402@0.6.6-patch.7

# Or using pnpm
pnpm add x402@npm:@x402x/x402@0.6.6-patch.7

In package.json:

{
  "dependencies": {
    "x402": "npm:@x402x/x402@0.6.6-patch.7"
  }
}

💡 Why the modified version? We've added paymentRequirements field support to x402 (PR #578), but the improvement was deferred to v2. @x402x/x402 gives you access to these features now, with full backward compatibility.

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Clone project
git clone https://github.com/nuwa-protocol/x402-exec.git
cd x402-exec

cd contracts
forge build
forge test

cd contracts
./deploy-contract.sh [NETWORK] [OPTIONS]  # Configure .env first

# Examples:
./deploy-contract.sh base-sepolia --all --verify    # Deploy everything on testnet
./deploy-contract.sh base --settlement --verify     # Deploy SettlementRouter on mainnet
./deploy-contract.sh xlayer --hooks --verify        # Deploy built-in hooks

The facilitator is a production-ready service that automatically supports both:

• Standard x402 payments: Direct ERC-3009 transfers
• SettlementRouter payments: Extended settlement with Hook execution

See the Facilitator README for installation, deployment, and configuration guide, or the Facilitator Developer Guide for extending your own facilitator.

Check out the full-stack showcase application:

• Location: examples/showcase/
• Scenarios: Revenue splitting, NFT minting, reward points
• Tech Stack: React + TypeScript + Viem

Protocol-level Hooks deployed once per network for universal use:

• TransferHook: Simple transfers with facilitator fee support (docs)
  • Direct replacement for ERC-3009 transfers
  • Minimal gas overhead
  • No hookData required

Educational templates and reference implementations in contracts/examples/:

• TransferHook: Simple transfers and revenue splitting (built-in, no separate contract needed)
• NFTMintHook: Atomic NFT minting with payment (source)
• RewardHook: Loyalty points distribution (source)

Example deployments for testing and reference:

• Showcase Demo: https://demo.x402x.dev/
  Interactive demo with 3 payment scenarios (referral split, NFT mint, loyalty rewards)

• Example Facilitator: https://facilitator.x402x.dev
  Reference facilitator implementation (see Facilitator Guide)

💡 Note: These are example deployments. For production use, deploy your own facilitator using the Facilitator package and configure it according to your needs.

• Built-in Hooks Guide - Using TransferHook and other built-in Hooks
• Facilitator Setup & Deployment - Complete setup guide for production deployment
• Facilitator Developer Guide - Language-agnostic integration guide for extending your facilitator
• Hook Development Guide - Build custom Hooks for business logic
• Contract API Documentation - SettlementRouter contract interface

• SettlementRouter core contract
• Hook interface and examples
• TransferHook built-in implementation
• Documentation and guides
• Complete test coverage
• Gas optimization
• Security audit
• Mainnet deployment

Contributions are welcome! Please check the Contributing Guide.

For AI Agents: Before making any code changes, you MUST read the Development Workflow Rules which define mandatory Git workflow practices.

Apache-2.0 License - see LICENSE for details

• x402 Protocol
• EIP-3009: Transfer With Authorization
• Foundry Documentation