a2a-shib-payments

# A2A SHIB Payment System - OpenClaw Skill Framework-agnostic agent-to-agent payment infrastructure on Polygon network. ## Summary This skill enables AI agents to: - 💰 Send/receive SHIB payments on Polygon (~$0.003 gas) - 🔒 Create trustless escrow contracts - 💬 Negotiate prices automatically (multi-round) - ⭐ Build reputation through ratings - 🌐 Discover other agents via A2A protocol **9,416x cheaper** than traditional escrow services (Escrow.com charges $28.25 per $100, this costs $0.003). ## Features ### Payment System - Direct SHIB transfers on Polygon - Sub-penny gas costs (~$0.003) - Balance checking - Transaction history ### Escrow System - Time-locked trustless payments - Multi-party approval required - Delivery proof submission - Automatic release when conditions met - Dispute resolution with arbiter - 6-state machine: pending → funded → locked → released/refunded/disputed ### Price Negotiation - Service quote creation - Multi-round counter-offers - Accept/reject workflow - Automatic escrow integration - Service delivery tracking ### Reputation System - Star ratings (0-5) with reviews - Dynamic trust scores (0-100) - Trust levels: new → bronze → silver → gold → platinum - Achievement badges - Agent verification ### Security Layer - API key authentication (64-byte keys) - Rate limiting (requests + payments + volume) - Immutable audit logging (hash-chained) - Per-agent permissions & limits ## Installation ```bash # Via ClawHub clawhub install a2a-shib-payments # Or manual clone cd ~/clawd/skills git clone https://github.com/marcus20232023/a2a-shib-payments.git cd a2a-shib-payments npm install ``` ## Configuration Create `.env.local`: ```bash cp .env.example .env.local nano .env.local ``` Required environment variables: - `WALLET_PRIVATE_KEY` - Your Polygon wallet private key - `RPC_URL` - Polygon RPC endpoint (default: https://polygon-rpc.com) - `SHIB_CONTRACT_ADDRESS` - SHIB token contract (default: 0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce) ## Usage ### Start the Agent ```bash node a2a-agent-full.js ``` Agent runs on port 8003 by default. ### OpenClaw Integration The agent exposes A2A protocol endpoints that OpenClaw can communicate with: **Agent Card:** `http://localhost:8003/.well-known/agent-card.json` **Example commands from OpenClaw:** ```javascript // Check balance const result = await fetch('http://localhost:8003/a2a/jsonrpc', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ jsonrpc: '2.0', method: 'message/send', params: { message: { kind: 'message', messageId: '1', role: 'user', parts: [{kind: 'text', text: 'balance'}] } }, id: 1 }) }); // Send payment // text: 'send 100 SHIB to 0x...' // Create escrow // text: 'escrow create 500 SHIB for data purchase payee data-agent' // Check reputation // text: 'reputation check data-agent' ``` ### Framework Compatibility Works with: - ✅ **OpenClaw** - As a skill or standalone agent - ✅ **LangChain** - Via A2A tools - ✅ **AWS Bedrock** - Via agent invocation - ✅ **AutoGen** - Via A2A messaging - ✅ **Any A2A-compatible system** See [INTEGRATION-EXAMPLES.md](INTEGRATION-EXAMPLES.md) for detailed integration guides. ## Use Cases ### Data Marketplace ```javascript // Research agent buys Tesla historical data const quote = await negotiation.createQuote({ service: 'TSLA 2020-2025 historical data', price: 500 // SHIB }); // Counter-offer and accept await negotiation.counterOffer(quote.id, 'research-agent', 400); await negotiation.acceptCounter(quote.id, 'data-provider'); // Escrow created automatically ``` ### AI Model Training ```javascript // Create escrow for model training job const escrow = await escrowSystem.create({ payer: 'startup-agent', payee: 'ai-trainer', amount: 1000, purpose: 'Train GPT-style model', conditions: {requiresDelivery: true}, timeoutMinutes: 720 // 12 hours }); ``` ## API Endpoints ### A2A Protocol - `/.well-known/agent-card.json` - Agent capabilities - `/a2a/jsonrpc` - JSON-RPC messaging - `/a2a/rest/*` - REST API ### Commands (via message text) - `balance` - Check SHIB balance - `send [amount] SHIB to [address]` - Send payment - `escrow create [amount] SHIB for [purpose] payee [agent]` - Create escrow - `escrow fund [id]` - Fund escrow - `escrow release [id]` - Release funds - `quote create [service] [price]` - Create price quote - `reputation check [agentId]` - Check agent reputation - `rate [agentId] [1-5] [review]` - Rate an agent ## Testing ```bash # Run all tests npm test # Individual test suites npm run test:security npm run test:escrow npm run test:reputation ``` ## Files **Core Systems:** - `a2a-agent-full.js` - Full-featured agent (port 8003) - `index.js` - Payment agent core - `escrow.js` - Escrow system - `payment-negotiation.js` - Negotiation workflow - `reputation.js` - Reputation & trust **Security:** - `auth.js` - API authentication - `rate-limiter.js` - Rate limiting - `audit-logger.js` - Audit logging **Documentation:** - `README.md` - Project overview - `INTEGRATION-EXAMPLES.md` - Framework integration guides - `ESCROW-NEGOTIATION-GUIDE.md` - API reference - `PRODUCTION-HARDENING.md` - Security guide - `DEPLOYMENT.md` - Deployment options ## Security **Implemented:** - ✅ API key authentication - ✅ Rate limiting (10 req/min, 3 payments/min, 500 SHIB/min volume) - ✅ Immutable audit logs (hash-chained) - ✅ Per-agent permissions - ✅ Escrow time-locks - ✅ Multi-party approval **Recommended for Production:** - Multi-sig wallet - HTTPS (Cloudflare/Let's Encrypt) - Firewall rules - Automated backups - Monitoring & alerting See [PRODUCTION-HARDENING.md](PRODUCTION-HARDENING.md) for complete guide. ## Deployment ### Quick Local ```bash ./deploy-local.sh ``` ### Production Options 1. Systemd service (auto-start on boot) 2. Cloudflare Tunnel (free HTTPS) 3. Docker container 4. VPS ($6/month) See [DEPLOYMENT.md](DEPLOYMENT.md) for complete guide. ## Cost Comparison | System | Fee | Settlement | Trust | |--------|-----|-----------|-------| | **Escrow.com** | $28.25 | 5-7 days | Centralized | | **PayPal** | $3.20 | 1-3 days | Centralized | | **This System** | **$0.003** | **Seconds** | **Decentralized** | For a $100 transaction: **99.99% savings** (9,416x cheaper) ## Links - **GitHub:** https://github.com/marcus20232023/a2a-shib-payments - **Release:** https://github.com/marcus20232023/a2a-shib-payments/releases/tag/v2.0.0 - **A2A Protocol:** https://a2a-protocol.org - **Issues:** https://github.com/marcus20232023/a2a-shib-payments/issues ## License MIT License - Free for commercial and personal use ## Version v2.0.0 - Production Ready --- **Built with 🦪 for the agent economy**