P402.io Protocol

P402.io is a payment infrastructure built for AI agents and micropayments on the Base L2 network. It enables sub-cent USDC transactions with instant settlement, using the x402 standard for payment-required HTTP status codes and ERC-8004 for autonomous agent identity.

This monorepo contains the complete reference implementation, including SDKs for clients and servers, a settlement facilitator, an agent core, demo applications, and a landing page.

🚀 Key Features

USDC Micropayments: Pay-per-use model with USDC on Base network (as low as $0.0001 per transaction)
1% Protocol Fee: Transparent, flat 1% fee on all transactions (vs Stripe's $0.30 + 2.9%)
HTTP 402 Paywalls: Standardized "Payment Required" flow for APIs and content
Session Keys: One signature enables 1-hour of frictionless payments (no popups)
Autonomous Agents: AI agents can pay for resources automatically with policy-based spending
ERC-8004 Identity: On-chain agent reputation for access control
Type-Safe SDKs: Fully typed TypeScript SDKs for easy integration

💰 Business Model

P402.io collects a 1% protocol fee on every transaction:

Merchant receives: 0.99 USDC
Protocol fee (1%): 0.01 USDC → P402.io Treasury
Recipient receives: 0.99 USDC

Fee Collection Status:

✅ Fee calculation implemented
✅ Fee tracking in dashboard
⚠️ On-chain settlement (EIP-3009) in development

See docs/FEE_COLLECTION.md for details.

🏗 Architecture

This project is organized as a Turborepo monorepo:

📦 Packages (`/packages`)

Package	Description
`@p402/types`	Shared TypeScript interfaces for P402.io (`PaymentRequirement`, `SessionDelegation`, etc.)
`@p402/sdk-core`	P402.io EIP-712 Typed Data definitions and cryptographic helpers
`@p402/sdk-server`	P402.io Express middleware (`x402PaymentRequired`) and `PaymentVerifier` logic
`@p402/sdk-client`	P402.io browser client with `fetch` wrapper and `SessionManager` for auto-signing
`@p402/agent-core`	P402.io toolkit for building autonomous agents (Policy Engine, Identity, Reputation)

📱 Applications (`/apps` & `/examples`)

App	Description	URL
`apps/landing`	Marketing landing page with wallet connection and onboarding wizard	http://localhost:3003
`apps/facilitator`	Settlement service that processes payments and collects protocol fees	http://localhost:3002
`apps/dashboard`	Next.js dashboard to monitor transactions, volume, and protocol revenue	http://localhost:3000
`examples/express-api`	Reference Node.js API protected by P402.io	http://localhost:3001
`examples/react-app`	React frontend demonstrating wallet connection and session key flows	http://localhost:5173

🛠 Getting Started

Prerequisites

Node.js (v18+)
pnpm (v8+)
MetaMask or Coinbase Wallet with USDC on Base network
Base Network configured in your wallet (Chain ID: 8453)

Installation

Clone the repository:

git clone https://github.com/yourusername/p402.git
cd p402

Install dependencies:
```
pnpm install
```
Build all packages:
```
pnpm build
```

Configure environment variables:

cd apps/facilitator
cp .env.example .env
# Edit .env and set P402_TREASURY_ADDRESS to your wallet

▶️ Running the Full Stack

You'll need 5 terminal windows to run the complete system:

1. Start the Landing Page

Marketing site with wallet connection and onboarding.

pnpm --filter landing dev -p 3003
# Running on http://localhost:3003

2. Start the Protected API

This service sells "Premium Content" for 0.01 USDC.

pnpm --filter example-express-api start
# Running on http://localhost:3001

3. Start the Facilitator

Settlement service that processes payments and collects fees.

pnpm --filter facilitator start
# Running on http://localhost:3002

4. Start the Dashboard

Monitor transactions, volume, and protocol revenue.

pnpm --filter dashboard dev
# Running on http://localhost:3000

5. Start the Client App

User interface to buy content with USDC.

pnpm --filter react-app dev
# Running on http://localhost:5173

🕹 Usage Flows

Getting Started (New Users)

Visit Landing Page → http://localhost:3003
Click "Connect Wallet" → Approve MetaMask connection
Follow Onboarding Wizard:
- Confirms wallet connection
- Explains USDC requirement (Base network)
- Sets up session keys
Launch Demo → Redirects to http://localhost:5173

Manual Payment (Popup Mode)

Open the React App (http://localhost:5173)
Click Connect Wallet
Click Buy Content (0.01 USDC)
Sign the payment in your wallet
Content is delivered instantly

Session Key Payment (Frictionless Mode)

In the React App, click Enable 1-Hour Session
Sign one message delegating 10 USDC spending limit
Click Buy Content
No popup! Payment happens automatically
Check the Dashboard to see real-time transaction logs

For Developers

Integrate P402.io into your API:

import { x402PaymentRequired } from '@p402/sdk-server';

app.get('/premium-content',
  x402PaymentRequired({
    amount: '10000', // 0.01 USDC (6 decimals)
    token: 'USDC',
    recipient: '0xYourAddress'
  }),
  (req, res) => {
    res.json({ content: 'Premium data' });
  }
);

💳 USDC Requirements

Important: P402.io uses USDC (USD Coin) on the Base network for all payments.

Setup Checklist

Install MetaMask or Coinbase Wallet
Add Base network (Chain ID: 8453)
Get USDC on Base:
- Testnet: Base Sepolia faucet
- Mainnet: Bridge from Ethereum or buy on Base

USDC Contract Addresses

Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Base Sepolia (Testnet): 0x036CbD53842c5426634e7929541eC2318f3dCF7e

🔒 Security

EIP-712 Signatures: All payments use structured, human-readable signing
Session Limits: Strictly limited by amount (e.g., 10 USDC) and time (1 hour)
Signature Verification: Full chain of trust verification: Master Wallet → Session Key → Payment Signature
Nonce Protection: Prevents replay attacks
Treasury Security: Use multi-sig wallet (Gnosis Safe) for production

Running Security Tests

pnpm exec vitest run packages/sdk-server/test/verifier.test.ts

🤖 Agent Integration

Build autonomous AI agents that can pay for resources:

import { Agent, AgentPolicy } from "@p402/agent-core";

const agent = new Agent({
    privateKey: process.env.AGENT_KEY,
    policy: new AgentPolicy({ 
        maxBudget: 100,      // $100 daily limit
        maxPerTx: 1,         // $1 per transaction
        approvedDomains: ['api.openai.com']
    })
});

// Agent automatically handles 402 challenges and pays with USDC
const response = await agent.fetch("http://localhost:3001/data");

📊 Monitoring & Analytics

Dashboard Features

Protocol Revenue: Track total fees collected (1% of all transactions)
Transaction Volume: Monitor total USDC processed
Agent Balance: View agent wallet balances
Transaction Log: Real-time feed of all payments

Access at: http://localhost:3000

🚧 Current Status & Roadmap

✅ Implemented (MVP)

Client SDK with session keys
Server SDK with payment verification
Express middleware for API protection
React demo app with wallet integration
Dashboard with real-time monitoring
Landing page with onboarding wizard
Fee calculation and tracking (1%)
Agent core with policy engine

⚠️ In Development

EIP-3009 USDC transferWithAuthorization implementation
Smart contract for trustless fee splitting
On-chain settlement (currently simulated)
Production deployment to Base mainnet

🔮 Planned Features

See docs/EIP3009_IMPLEMENTATION.md for production roadmap.

📚 Documentation

docs/FEE_COLLECTION.md - How protocol fees work
docs/EIP3009_IMPLEMENTATION.md - Production settlement guide
docs/COINBASE_INTEGRATION.md - Coinbase Commerce integration

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

Landing Page: http://localhost:3003
Dashboard: http://localhost:3000
Demo App: http://localhost:5173
GitHub: [Coming Soon]
Discord: [Coming Soon]

Built with ❤️ for the Machine Age

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.turbo		.turbo
apps		apps
docs		docs
examples		examples
packages		packages
scripts		scripts
.gitignore		.gitignore
BUILD_VERIFICATION_REPORT.md		BUILD_VERIFICATION_REPORT.md
COMPLETE_REBRANDING_REPORT.md		COMPLETE_REBRANDING_REPORT.md
FINAL_REBRANDING_VERIFICATION.md		FINAL_REBRANDING_VERIFICATION.md
README.md		README.md
REBRANDING_COMPLETE_SUMMARY.md		REBRANDING_COMPLETE_SUMMARY.md
REBRANDING_STATUS.md		REBRANDING_STATUS.md
REBRANDING_SUMMARY.md		REBRANDING_SUMMARY.md
REBRANDING_VERIFICATION.md		REBRANDING_VERIFICATION.md
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

P402.io Protocol

🚀 Key Features

💰 Business Model

🏗 Architecture

📦 Packages (/packages)

📱 Applications (/apps & /examples)

🛠 Getting Started

Prerequisites

Installation

▶️ Running the Full Stack

1. Start the Landing Page

2. Start the Protected API

3. Start the Facilitator

4. Start the Dashboard

5. Start the Client App

🕹 Usage Flows

Getting Started (New Users)

Manual Payment (Popup Mode)

Session Key Payment (Frictionless Mode)

For Developers

💳 USDC Requirements

Setup Checklist

USDC Contract Addresses

🔒 Security

Running Security Tests

🤖 Agent Integration

📊 Monitoring & Analytics

Dashboard Features

🚧 Current Status & Roadmap

✅ Implemented (MVP)

⚠️ In Development

🔮 Planned Features

📚 Documentation

🤝 Contributing

📄 License

🔗 Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

📦 Packages (`/packages`)

📱 Applications (`/apps` & `/examples`)

Packages