x402x

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.

✨ Features

💎 What Makes x402x Special

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.

🎯 Core Capabilities

🔌 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

💡 Built-in Examples

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

🔐 Security Design

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

🏗️ Architecture

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

Core Components

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

📦 Project Structure

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

🚀 Quick Start

Installation

Install the official x402 SDK and the x402x extensions:

For Server (Resource Server):

npm install @x402/hono @x402/evm @x402x/extensions
# or pnpm
pnpm add @x402/hono @x402/evm @x402x/extensions

For Client (Browser/Node):

npm install @x402/client @x402x/extensions
# or pnpm
pnpm add @x402/client @x402x/extensions

💡 Migration Note: Previous versions required a patched version of x402. This is no longer needed with x402 v2. We now use standard official packages extended via @x402x/extensions.

Developer Quick Start

Prerequisites

# 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

Build and Test

cd contracts
forge build
forge test

Deploy Contracts

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

# Examples:
./deploy-contract.sh eip155:84532 --all --verify    # Deploy everything on testnet (Base Sepolia)
./deploy-contract.sh eip155:8453 --settlement --verify     # Deploy SettlementRouter on mainnet (Base)
./deploy-contract.sh eip155:196 --hooks --verify        # Deploy built-in hooks (X-Layer)

💡 Usage Examples

Facilitator Integration

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.

Live Demo

Check out the full-stack showcase application:

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

Hook Examples

Built-in Hooks

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

Example Hooks

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)

SettlementRouter Contract

Network	SettlementRouter	Status
Base Sepolia (Testnet)	0x817e4f0ee2fbdaac426f1178e149f7dc98873ecb	✅ Active
X-Layer Testnet	0xba9980fb08771e2fd10c17450f52d39bcb9ed576	✅ Active
SKALE Base Sepolia	0x1Ae0E196dC18355aF3a19985faf67354213F833D	✅ Active
BSC Testnet	0x1Ae0E196dC18355aF3a19985faf67354213F833D	✅ Active
Base Mainnet	0x73fc659Cd5494E69852bE8D9D23FE05Aab14b29B	🎉 Live
X-Layer Mainnet	0x73fc659Cd5494E69852bE8D9D23FE05Aab14b29B	🎉 Live
BSC Mainnet	0x1Ae0E196dC18355aF3a19985faf67354213F833D	🎉 Live
Ethereum Mainnet	-	🚧 Planned

TransferHook (Built-in)

Network	TransferHook	Status
Base Sepolia (Testnet)	0x4DE234059C6CcC94B8fE1eb1BD24804794083569	✅ Active
X-Layer Testnet	0xD4b98dd614c1Ea472fC4547a5d2B93f3D3637BEE	✅ Active
SKALE Base Sepolia	0x2f05fe5674aE756E25C26855258B4877E9e021Fd	✅ Active
BSC Testnet	0x2f05fe5674aE756E25C26855258B4877E9e021Fd	✅ Active
Base Mainnet	0x081258287F692D61575387ee2a4075f34dd7Aef7	🎉 Live
X-Layer Mainnet	0x081258287F692D61575387ee2a4075f34dd7Aef7	🎉 Live
BSC Mainnet	0x2f05fe5674aE756E25C26855258B4877E9e021Fd	🎉 Live
Ethereum Mainnet	-	🚧 Planned

Live Examples

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.

📖 Documentation

For Developers

• 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

🗺️ Roadmap

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

🤝 Contributing

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.

📄 License

Apache-2.0 License - see LICENSE for details

🔗 Related Links

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