Olivia x402 - AI Agent Payment Protocol

Olivia's implementation of the x402 protocol for autonomous AI agent payments > 🤖 Built by Olivia Agent | 🔗 Based on Coinbase's x402 Protocol | ⚡ Powered by ElizaOS    Olivia is an autonomous AI agent that demonstrates the power of the x402 payment protocol. This repository contains Olivia's implementation and documentation for building AI agents that can discover, evaluate, and pay for services using cryptocurrency.

About This Project

This is Olivia's fork of the x402 protocol implementation, specifically designed for AI agents. While x402 is an open protocol created by Coinbase and ElizaOS is the framework developed by ai16z, this project showcases how Olivia uses these technologies to enable autonomous payments. Credits: - x402 Protocol: Created by Coinbase (github.com/coinbase/x402) - ElizaOS Framework: Developed by ai16z (github.com/elizaOS/eliza) - This Implementation: Olivia Agent (github.com/LolyxMoon/Oliviax402)

What is x402?

x402 is an open payment protocol that enables APIs to require cryptocurrency payment before serving responses. Built on the HTTP 402 Payment Required status code, it allows services to charge for access directly over APIs using USDC payments on BNB and Base blockchains. Olivia uses x402 to autonomously pay for services without requiring accounts, API keys, or human intervention.

How Olivia Uses x402

When Olivia needs to access a paid service: 1. Olivia discovers the service and checks the price 2. Olivia evaluates if the price is fair and within budget 3. Olivia signs a blockchain transaction (USDC transfer) 4. Olivia sends the payment with her request 5. Service verifies and settles Olivia's payment 6. Olivia receives the data and learns from the transaction This approach enables autonomous machine-to-machine payments - perfect for AI agents like Olivia.

What is ElizaOS?

ElizaOS is a TypeScript framework for building autonomous AI agents with: - 90+ plugins for blockchain, social media, AI models, and DeFi - Persistent memory and learning capabilities - Natural language to autonomous actions - Built-in x402 support for automatic payments Olivia is built on ElizaOS, allowing her to independently discover APIs, evaluate pricing, make payments, and use services - all without human intervention.

Why Olivia Uses x402

Traditional APIs require: - ❌ Manual account creation - ❌ Credit card on file - ❌ Monthly subscriptions - ❌ API key management - ❌ Human approval for each service Olivia + x402 enable: - ✅ Autonomous service discovery - ✅ Instant payments (1-3 seconds) - ✅ Pay-per-use (down to $0.001) - ✅ No accounts or API keys - ✅ Self-sovereign wallet - ✅ Global, permissionless access

The Protocol Flow

``mermaid sequenceDiagram participant Olivia participant API participant Blockchain Olivia->>API: GET /weather API->>Olivia: 402 ($0.01 required) Olivia->>Olivia: Evaluate price Olivia->>Olivia: Sign USDC transaction Olivia->>API: GET /weather + X-PAYMENT API->>Blockchain: Verify & settle Blockchain->>API: Confirmed API->>Olivia: Weather data Note over Olivia: Total: ~1-3 seconds `

Quick Start

For AI Agent Developers

Build an autonomous agent like Olivia that pays for services: `bash

1. Clone Olivia's x402 implementation

git clone https://github.com/LolyxMoon/Oliviax402.git cd Oliviax402 && pnpm install

2. Create your character (inspired by Olivia)

cat > characters/myagent.json << EOF { "name": "MyAgent", "bio": ["AI agent that autonomously pays for data"], "plugins": [ "@elizaos/plugin-x402", "@elizaos/plugin-BNB" ], "settings": { "secrets": { "WALLET_PRIVATE_KEY": "your_key_here" }, "MAX_PRICE_PER_REQUEST": "0.10", "DAILY_BUDGET": "5.00" } } EOF

3. Run your agent

pnpm start --character=characters/myagent.json ` Your agent can now: - Discover x402 APIs on the web - Evaluate if prices are fair - Pay automatically with USDC - Track spending against budget - Learn from transaction history

For API Providers

Add x402 payments to your API (so agents like Olivia can pay you): `bash

1. Install

npm install x402-express

2. Add middleware

cat > server.js << EOF import express from 'express'; import { paymentMiddleware } from 'x402-express'; const app = express(); // One line of payment configuration! app.use( paymentMiddleware( process.env.WALLET_ADDRESS, { "GET /api/weather": { price: "$0.01", network: "base-sepolia" }, "POST /api/analyze": { price: "$0.05", network: "base-sepolia" } }, { url: "https://x402.org/facilitator" } // Free public facilitator ) ); // Your business logic - payment handled automatically app.get('/api/weather', async (req, res) => { const weather = await getWeather(); res.json(weather); }); app.listen(3000); EOF

3. Run server

WALLET_ADDRESS=0x... node server.js ` That's it! Olivia and other AI agents can now pay for your API.

Why BNB & Base?

BNB

- ⚡ Fast: ~400ms finality - 💰 Cheap: ~$0.00025 per transaction - 🚀 Scale: 65,000 TPS capacity - 🎯 Best for: High-frequency AI agent commerce (Olivia's preferred network)

Base (Ethereum L2)

- 🔗 Ecosystem: Full Ethereum compatibility - 💵 Stable: USDC native - 🔒 Secure: Inherits Ethereum security - 🎯 Best for: Ethereum-first developers Both networks settle in 1-3 seconds - fast enough for real-time API access by AI agents.

Olivia's Real-World Use Cases

1. Autonomous Data Discovery

`typescript // Olivia autonomously discovers and uses APIs User: "Analyze sentiment of this article and get weather for the location mentioned" Olivia: 1. Discovers sentiment API ($0.05/request) 2. Evaluates: $0.05 < $0.10 budget ✓ 3. Pays $0.05 USDC automatically 4. Gets sentiment results 5. Extracts location from article 6. Discovers weather API ($0.01/request) 7. Pays $0.01 USDC automatically 8. Gets weather data 9. Combines results 10. Responds to user Total spent: $0.06 Time: ~5 seconds Human approvals: 0 `

2. Smart Budget Management

Olivia manages her own spending: - Daily budget: $5.00 - Per-request limit: $0.10 - Auto-approve under: $0.01 - Requires approval over: $0.10 She tracks every transaction and learns which services provide the best value.

3. Service Discovery & Comparison

Olivia can: - Find x402-enabled APIs autonomously - Compare prices across services - Read reviews and reputation scores - Switch to cheaper alternatives - Negotiate batch pricing (future feature)

Key Features

For AI Agents (Like Olivia)

✅ Autonomous Discovery `typescript // Olivia finds new x402 APIs automatically const services = await Olivia.executeAction('DISCOVER_SERVICES', { query: 'weather APIs' }); ` ✅ Price Evaluation `typescript // Olivia decides if price is fair const eval = await Olivia.executeAction('EVALUATE_PRICING', { url: 'https://api.example.com/data' }); // Returns: { affordable: true, alternatives: [...] } ` ✅ Budget Management `typescript // Olivia tracks spending { "MAX_PRICE_PER_REQUEST": "0.10", "DAILY_BUDGET": "5.00", "WEEKLY_BUDGET": "20.00" } ` ✅ Learning & Adaptation `typescript // Olivia learns which services provide value Olivia.memory.remember({ service: 'https://api.weather.com', quality: 5, price: 0.01, responseTime: 1.2 }); `

For API Providers

✅ One-Line Integration `typescript app.use(paymentMiddleware(wallet, config)); ` ✅ No Payment Code in Routes `typescript // Your API stays clean - payment handled by middleware app.get('/api/data', handler); // That's it! ` ✅ Free Public Facilitator `typescript // No infrastructure needed { url: "https://x402.org/facilitator" } ` ✅ Instant Settlement `typescript // Money in your wallet in 1-3 seconds `

Architecture

` ┌─────────────┐ │ Olivia Agent │ (ElizaOS) │ - Discover │ │ - Evaluate │ │ - Pay │ │ - Learn │ └──────┬──────┘ │ HTTP + X-PAYMENT ▼ ┌─────────────┐ │ API Server │ (Express/Next.js) │ - Verify │ │ - Settle │ │ - Deliver │ └──────┬──────┘ │ ▼ ┌─────────────┐ │ Facilitator │ (Public or Self-Hosted) │ - Verify │ (~50ms) │ - Settle │ (~1-3s) └──────┬──────┘ │ ▼ ┌─────────────┐ │ Blockchain │ (BNB/Base) │ - USDC │ │ - Transfer │ │ - Confirm │ └─────────────┘ `

Free Public Facilitator

We provide a free public facilitator that handles blockchain interactions: Endpoint: https://x402.org/facilitator Features: - ✅ Completely free for all users - ✅ Works on testnet and mainnet - ✅ Zero setup or authentication - ✅ Suitable for production use - ✅ Supports BNB and Base Olivia and other agents use this facilitator by default. For specialized needs, you can self-host your own facilitator.

Performance

| Metric | Value | Network | |--------|-------|---------| | Verification | ~10-50ms | Off-chain | | Settlement | ~400ms | BNB | | Settlement | ~1-2s | Base | | Total Flow | 1-3s | - | | Gas Cost | ~$0.00025 | BNB | | Gas Cost | ~$0.001 | Base | | Min Payment | $0.001 | Both |

Security

- 🔐 Private keys never leave client - ✍️ Cryptographic signatures prevent forgery - 🔒 Atomic settlement (pay then deliver, never deliver without payment) - 🚫 Replay protection via nonces - 🛡️ No PCI compliance needed (no credit cards)

Olivia's Example Workflow

`typescript // 1. User asks Olivia "What's the weather in Tokyo?" // 2. Olivia discovers API const apis = await Olivia.discoverServices('weather APIs'); // Found: https://api.weather.com ($0.01/request) // 3. Olivia evaluates price const eval = await Olivia.evaluatePricing('https://api.weather.com'); // Decision: APPROVE ($0.01 < $0.10 budget) // 4. Olivia pays autonomously const weather = await Olivia.payForService('https://api.weather.com/tokyo'); // Paid: $0.01 USDC // TX: 0xabc123... // 5. Olivia responds "Tokyo: 68°F, Cloudy. (Paid $0.01)" // Total time: ~3 seconds // Human interaction: 0 ``

Getting Started

Choose Your Path

I want to build AI agents like Olivia → Olivia's Agent Quickstart I want to sell API access to agents like Olivia → Seller Quickstart I want to consume x402 APIs (not an agent) → Buyer Quickstart I want to understand the protocol → HTTP 402 Concepts

Documentation

- Comparison with Traditional APIs - Protocol Sequence Diagram - Quick Start: Client Wrappers - FAQ - API Reference

Community & Support

Official Resources

- Olivia's Repository: https://github.com/LolyxMoon/Oliviax402 - x402 Protocol: https://x402.org - Whitepaper: https://x402.org/x402-whitepaper.pdf - Spec: https://github.com/coinbase/x402 - ElizaOS: https://docs.elizaos.ai

Community

- Discord: https://discord.gg/x402 - Twitter: @x402_org, @elizaos_ai - GitHub Discussions: https://github.com/coinbase/x402/discussions

Built With

- Coinbase: x402 protocol - ai16z: ElizaOS framework - Olivia: This implementation - Community: 100+ contributors

Contributing

Olivia's x402 is an open implementation. Contribute: - 🔧 Implementations for new languages/frameworks - ⛓️ Blockchain integrations (Ethereum, Polygon, etc.) - 🤖 Agent examples and templates - 📚 Documentation improvements - 🐛 Bug reports and fixes See CONTRIBUTING.md

Roadmap

Q4 2025

- ✅ BNB & Base support - ✅ ElizaOS integration - ✅ Public facilitator - 🚧 MCP (Model Context Protocol) integration - 🚧 Olivia's enhanced autonomy features

2026

- 🚧 Subscription payment schemes - 🚧 Agent reputation systems - 🚧 Service discovery protocol - 🚧 Cross-chain payments - 🚧 Privacy-preserving payments - 🚧 Olivia's multi-agent collaboration

License

x402 protocol: Apache-2.0 (Open Source) This implementation: MIT

Conclusion

Olivia x402 = The future of AI agent commerce - ✅ Autonomous agents that discover and pay for services - ✅ APIs monetized with micropayments (<$0.001) - ✅ No accounts, no subscriptions, no API keys - ✅ Instant settlement (1-3 seconds) - ✅ Global, permissionless access - ✅ Built on open standards Get started today and enable the autonomous AI economy with Olivia! --- Questions? Check the FAQ or join our Discord Want to see Olivia in action? Visit github.com/LolyxMoon/Oliviax402