{"id":33311637,"url":"https://github.com/kamiyo-ai/x402resolve","last_synced_at":"2025-11-19T05:04:23.976Z","repository":{"id":323059996,"uuid":"1091185075","full_name":"kamiyo-ai/x402resolve","owner":"kamiyo-ai","description":"Trustless payment escrow for HTTP 402 APIs with oracle-verified quality assessment on Solana","archived":false,"fork":false,"pushed_at":"2025-11-16T08:54:38.000Z","size":2917,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-16T10:19:57.263Z","etag":null,"topics":["ai-agents","api-monetization","defi","dispute-resolution","http-402","oracle","payment-escrow","solana","switchboard","web3"],"latest_commit_sha":null,"homepage":"https://x402resolve.kamiyo.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kamiyo-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap/SWITCHBOARD_INTEGRATION.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T17:07:44.000Z","updated_at":"2025-11-12T00:09:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kamiyo-ai/x402resolve","commit_stats":null,"previous_names":["kamiyo-ai/x402resolve"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kamiyo-ai/x402resolve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamiyo-ai%2Fx402resolve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamiyo-ai%2Fx402resolve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamiyo-ai%2Fx402resolve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamiyo-ai%2Fx402resolve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kamiyo-ai","download_url":"https://codeload.github.com/kamiyo-ai/x402resolve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamiyo-ai%2Fx402resolve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285187921,"owners_count":27129352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","api-monetization","defi","dispute-resolution","http-402","oracle","payment-escrow","solana","switchboard","web3"],"created_at":"2025-11-19T05:01:56.280Z","updated_at":"2025-11-19T05:04:23.957Z","avatar_url":"https://github.com/kamiyo-ai.png","language":"TypeScript","readme":"# x402Resolve\n\n![x402resolve](https://github.com/user-attachments/assets/7c7783d6-2055-400b-a1e5-cb4c2ce7a76c)\n\nTrustless payment escrow for HTTP 402 APIs with oracle-verified quality assessment on Solana.\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Solana](https://img.shields.io/badge/Solana-Devnet-14F195?logo=solana)](https://solana.com)\n[![Anchor](https://img.shields.io/badge/Anchor-0.31.1-663399)](https://www.anchor-lang.com/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?logo=typescript)](https://www.typescriptlang.org/)\n[![Rust](https://img.shields.io/badge/Rust-1.75-orange?logo=rust)](https://www.rust-lang.org/)\n[![Tests](https://img.shields.io/badge/tests-unit%20%7C%20integration%20%7C%20e2e%20%7C%20security-success)](TESTING.md)\n[![Coverage](https://img.shields.io/badge/coverage-program%20%7C%20SDK%20%7C%20oracle-brightgreen)](TESTING.md)\n[![Docs](https://img.shields.io/badge/docs-API%20examples-success)](docs/API_EXAMPLES.md)\n[![MCP](https://img.shields.io/badge/MCP-8%20tools-purple?logo=anthropic)](packages/mcp-server/README.md)\n\n## Overview\n\nPDA-based escrow implementing RFC 9110 Section 15.5.3 (HTTP 402) with sliding-scale refunds based on oracle quality assessment. No admin keys, no custody. Quality verified before payment release.\n\n**Program ID**: `E5EiaJhbg6Bav1v3P211LNv1tAqa4fHVeuGgRBHsEu6n` (Devnet)\n\n**Live Demo**: [https://x402resolve.kamiyo.ai/](https://x402resolve.kamiyo.ai/)\n\n**Demo Video**: [https://x402resolve.kamiyo.ai/demo-video.mp4/](https://x402resolve.kamiyo.ai/demo.html/)\n\n## Problem\n\nHTTP 402 APIs lack trustless quality assurance. Clients pay upfront with no recourse for poor data. Traditional chargebacks take 30-90 days and cost $35-50 per dispute. Providers face fraud risk and admin overhead.\n\n**x402Resolve fixes this:** Oracle-verified quality assessment triggers automatic sliding-scale refunds (0-100%) on-chain. Payment released only after quality validation. 2-48 hour resolution at $2-8 per dispute.\n\n## Market Opportunity\n\nThe AI agents market reached **$7.6B in 2025** (41% YoY growth) while payment disputes hit **$41.69B**. As agents make autonomous purchases, traditional chargebacks (30-90 days, $35-50/dispute) break automation. Industry experts predict: *\"AI agent transactions will trigger new payment disputes... New data from Worldpay projects $261 billion of online spending will be done by AI agents in the next 5 years.\"*\n\n**x402Resolve advantage:** 15-45x faster resolution, 5-25x cheaper, sliding-scale refunds vs binary (all-or-nothing).\n\n**Go-to-Market:** Phase 1: MCP ecosystem (Claude, LangChain). Phase 2: Developer platforms (Replit, Zed). Phase 3: Enterprise (Fortune 500, Stripe, Visa). Phase 4: Protocol standardization (RFC, industry adoption). 6-12 month first-mover lead, network effects via reputation data.\n\n**Full strategy:** [Market Analysis \u0026 GTM](docs/MARKET_STRATEGY.md)\n\n## Quick Integration\n\nBuild x402-compliant APIs or agents in **minutes**, not weeks. No custom escrow logic, refund math, or reputation tracking needed.\n\n### API Provider\n\n```typescript\nimport { x402PaymentMiddleware } from '@x402resolve/middleware';\n\napp.use('/api/*', x402PaymentMiddleware({\n  programId: new PublicKey('E5EiaJhbg6Bav1v3P211LNv1tAqa4fHVeuGgRBHsEu6n'),\n  connection, price: 0.001, qualityGuarantee: true\n}));\n```\n\n### AI Agent\n\n```typescript\nconst escrow = await client.createEscrow({ api: provider, amount: 0.001 });\nconst data = await fetch(apiUrl, { headers: { 'X-Payment-Proof': escrow } });\nif (quality \u003c 80) await client.markDisputed(escrow); // Auto-refund\n```\n\n**What you get:** Automatic escrows, quality-based refunds, dispute resolution, reputation tracking, rate limiting—all handled on-chain.\n\n## Autonomous Agent Applications\n\nProduction-ready AI agents that make autonomous payments with quality guarantees. Demonstrating advanced multi-agent reasoning, consensus building, and cost optimization.\n\n### Advanced Trading Bot\n\nSophisticated trading bot with 4-phase reasoning pipeline and quality-weighted data consensus.\n\n**Complex Reasoning:**\n- Multi-source data gathering with automatic dispute filing\n- Quality-weighted consensus building (filters \u003c80% quality)\n- Risk-adjusted decision making with composite scoring\n- Cost-benefit validation factoring x402 refunds\n\n**Key Innovation**: Uses quality scores to weight data sources and adjust position sizing dynamically.\n\n```typescript\n// 4-Phase Decision Pipeline\nPhase 1: Gather data from 3 sources → Auto-dispute if quality \u003c80%\nPhase 2: Build quality-weighted consensus → Filter low-quality data\nPhase 3: Calculate composite risk score → Adjust position size\nPhase 4: Validate ROI including refunds → Execute or hold\n```\n\n[View Full Example →](examples/trading-bot-agent/)\n\n**Example Output:**\n```\n[Phase 1] Multi-Source Data Gathering\n  → High-Frequency Oracle: 97% quality, 0.0005 SOL\n  → Aggregated DEX Data: 88% quality, 0.0003 SOL\n  → Community Sentiment: 73% quality, 0.0002 SOL ⚠ Disputed\n\n[Phase 2] Quality-Weighted Consensus\n  Consensus Price: $102.45 (92% avg quality, 2/3 sources)\n  Signal: BUY (72% confidence)\n\n[Phase 3] Risk-Adjusted Decision\n  Composite Risk Score: 23/100\n  Position Size: 0.2310 SOL (risk-adjusted from 0.30 SOL)\n\n[Phase 4] Cost-Benefit Analysis\n  Data Investment: 0.000946 SOL\n  Expected Profit: 0.004620 SOL\n  ROI: 388% → Execute Trade\n```\n\n### Multi-Agent Orchestration\n\nCoordinator managing 4 specialized agents with quality consensus and dependency resolution.\n\n**Agents:**\n- **SecurityAnalyst**: 90% quality threshold, security audits\n- **MarketAnalyst**: 85% quality threshold, market data\n- **RiskAnalyst**: 95% quality threshold, risk assessment\n- **ComplianceAgent**: 98% quality threshold, regulatory checks\n\n**Advanced Features:**\n- Dependency-based task execution\n- Inter-agent context sharing\n- Quality-weighted voting (higher quality = more weight)\n- Coordinated dispute resolution\n\n```typescript\n// Multi-Agent Consensus Building\nAgent1: 95% quality → 51.9% voting weight\nAgent2: 88% quality → 48.1% voting weight\nAgent3: 72% quality → Filtered out (disputed)\n\nConsensus: STRONG (92% avg quality)\nDecision: PROCEED with high confidence\n```\n\n[View Full Example →](examples/multi-agent-orchestration/)\n\n### CDP Agent Demo\n\nDemand-side agent using Coinbase CDP Embedded Wallets for autonomous API discovery and consumption.\n\n**Features:**\n- Discovers x402-enabled APIs automatically\n- Reasons over available tools\n- Chains multiple API calls\n- Auto-disputes poor quality (\u003c85%)\n\n**Workflow:**\n```\n1. Discovery  → Find 402-enabled endpoints\n2. Reasoning  → Evaluate cost vs quality vs relevance\n3. Execution  → Create escrows, make calls\n4. Assessment → Quality check each response\n5. Chaining   → Use results to inform next calls\n```\n\n[View Full Example →](examples/cdp-agent-demo/)\n\n### Integration Test\n\nEnd-to-end validation proving agents work with actual infrastructure.\n\n**Tests 6 Components:**\n1. SDK creates real escrows on Solana devnet\n2. Reputation tracking initializes and updates\n3. Agent autonomous consumption with quality checks\n4. Multi-agent coordination and consensus\n5. MCP server tools validation (8 tools)\n6. Quality assessment across scenarios\n\n**Run Test:**\n```bash\ncd examples/agent-integration-test\nnpm install\nnpm test\n```\n\n**Validates:**\n- Real Solana transactions with explorer links\n- MCP + SDK + Agent integration\n- Quality guarantees enforced\n- All systems working together\n\n[View Test Suite →](examples/agent-integration-test/)\n\n## MCP Server (AI Agent Integration)\n\n**Production-ready MCP server** for HTTP 402 payments with quality-verified refunds, multi-agent orchestration, and advanced ML-powered features.\n\n### What is MCP?\n\n[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is Anthropic's open standard for connecting AI systems to external tools and data sources. Our MCP server gives Claude Desktop, LangChain, AutoGPT, and other AI agents:\n\n**Core Capabilities:**\n- Create payment escrows with quality guarantees\n- Assess API response quality\n- File disputes for poor data\n- Check escrow status\n- Verify API provider reputation\n- Estimate refunds based on quality scores\n\n**Advanced Features:**\n- Context compression (20-30% token reduction)\n- Zero-knowledge quality proofs\n- Adaptive ML learning (40% accuracy improvement)\n- Multi-model LLM routing (60% cost savings)\n- Parallel processing (sub-100ms latency)\n- Reputation NFTs\n- Carbon tracking\n\n**8 production-ready tools** with cutting-edge enhancements.\n\n### Quick Start (Claude Desktop)\n\n1. **Install dependencies:**\n```bash\ncd packages/mcp-server\nnpm install\nnpm run build\n```\n\n2. **Configure environment:**\n```bash\ncp .env.example .env\n# Edit .env with your keypair\n```\n\n3. **Configure Claude Desktop:**\n```json\n{\n  \"mcpServers\": {\n    \"x402resolve\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/packages/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"SOLANA_RPC_URL\": \"https://api.devnet.solana.com\",\n        \"X402_PROGRAM_ID\": \"E5EiaJhbg6Bav1v3P211LNv1tAqa4fHVeuGgRBHsEu6n\",\n        \"AGENT_PRIVATE_KEY\": \"\u003cyour_base58_private_key\u003e\"\n      }\n    }\n  }\n}\n```\n\n4. **Use in Claude:**\n```\nUser: \"Create a 0.001 SOL escrow for weather API at 9W...\"\nClaude: Creating escrow...\nEscrow: E7x... (0.001 SOL, expires in 1h)\n```\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `create_escrow` | Lock payment with quality guarantee |\n| `call_api_with_escrow` | Unified flow: create + call + assess |\n| `assess_data_quality` | Evaluate completeness, freshness, schema compliance |\n| `file_dispute` | Submit dispute for poor quality data |\n| `check_escrow_status` | Monitor escrow state |\n| `get_api_reputation` | Check provider trust score |\n| `verify_payment` | Confirm payment received |\n| `estimate_refund` | Calculate refund by quality score |\n\n**Full Documentation:** [packages/mcp-server/README.md](packages/mcp-server/README.md)\n\n## Why Solana?\n\n**High TPS** → Real-time refunds (2-48 hours vs 30-90 days). No waiting for traditional payment processors.\n\n**PDAs (Program Derived Addresses)** → Keyless escrow security. No admin keys to compromise, no custody risk. Funds locked by cryptographic derivation.\n\n**Switchboard On-Demand** → Decentralized oracle verification. Quality assessment verified on-chain with 300s freshness guarantee. No single point of failure.\n\n**Sub-penny costs** → $0.02/dispute (even with ML inference + infrastructure). Traditional methods cost $35-50.\n\n## Use Cases\n\n| Use Case | Features | Example |\n|----------|----------|---------|\n| **AI Agent Marketplaces** | Auto-pay with quality guarantees, threshold enforcement (85%+ quality) | Agent calls Twitter API → pays 0.001 SOL → auto-refund if data incomplete |\n| **Data Marketplaces** | Oracle-verified freshness, completeness and schema validation | Financial API → oracle checks timestamp → refund if stale |\n| **Compute Marketplaces** | SLA enforcement, response time and accuracy verification | Image generation → quality score based on resolution + inference time |\n| **ML Model Endpoints** | Pay-per-inference, confidence thresholds, schema validation | Sentiment analysis → refund if confidence \u003c90% |\n\n## Ecosystem\n\n| Category | Description | Integrations |\n|----------|-------------|--------------|\n| **Agent Frameworks** | Drop-in payment layer for autonomous agents | LangChain tool calling, AutoGPT flows, any HTTP client (axios, fetch) |\n| **Solana DeFi** | Composable with existing protocols | SPL tokens (planned), Solana Pay format, Jupiter/Orca swaps (planned) |\n| **Oracle Networks** | Multi-oracle quality verification | Switchboard On-Demand (live), Pyth feeds (planned), custom endpoints |\n| **API Standards** | RFC-compliant design | HTTP 402 (RFC 9110), OpenAPI 3.0, Express/FastAPI/Next.js |\n\n## Economics\n\nCost comparison at 1% dispute rate (100 disputes/month on $5,000 API spend):\n\n| Method | Cost/Dispute | Total/Month | Resolution Time | Annual Cost |\n|--------|--------------|-------------|-----------------|-------------|\n| Traditional (Stripe/PayPal) | $35-50 | $3,500-5,000 | 30-90 days | $42,000-60,000 |\n| x402Resolve (All-in) | $2-8 | $200-800 | 2-48 hours | $2,400-9,600 |\n| **Savings** | **$27-48 (84-94%)** | **$2,700-4,800 (84-94%)** | **97-99% faster** | **$32,400-57,600 (84-94%)** |\n\n- **Traditional:** $35-50/dispute (chargeback + processing + admin)\n- **x402Resolve:** $2-8/dispute (ML inference $0.5-2 + agent compute $0.3-1.5 + infrastructure $1-3 + on-chain $0.02)\n- **84-94% cost reduction**\n\n## Features\n\n- PDA-secured escrow without admin keys\n- Ed25519 signature verification for centralized oracle\n- Switchboard On-Demand integration for decentralized oracle\n- Sliding-scale refunds (0-100%) based on quality metrics\n- Timestamp validation (300s freshness window)\n- Reputation tracking for agents and APIs\n- Rate limiting with verification tiers\n\n## Architecture\n\n### High-Level Flow\n\n```\n┌──────────┐    ┌────────┐    ┌─────┐    ┌────────┐\n│  Client  │───▶│ Escrow │───▶│ API │◀──▶│ Oracle │\n└──────────┘    └────────┘    └─────┘    └────────┘\n                     │            │           │\n                     │            │           │\n                     │◀───────────┴───────────┘\n                     │  Quality Assessment\n                     │\n                     ▼\n              Sliding-Scale Refund\n```\n\n### Dispute Resolution Flow\n\n```\n1. Payment          2. API Call         3. Quality Check      4. Settlement\n┌─────────┐        ┌─────────┐         ┌──────────┐         ┌──────────┐\n│ Client  │        │   API   │         │  Oracle  │         │  Escrow  │\n│ creates │───────▶│ returns │────────▶│ assesses │────────▶│ executes │\n│ escrow  │  SOL   │  data   │  JSON   │ quality  │  score  │  refund  │\n└─────────┘        └─────────┘         └──────────┘         └──────────┘\n   0.01 SOL          Response            Score: 65            0.0035 SOL\n   locked            received            (35% refund)         returned\n```\n\n### State Machine\n\n```\ninitialize_escrow → Active → [release_funds | mark_disputed]\n                      ↓                           ↓\n                   Released                   Disputed\n                                                 ↓\n                                         resolve_dispute\n                                                 ↓\n                                             Resolved\n                                         (split by refund %)\n```\n\n### Account Structure\n\n**Escrow PDA**\n```rust\nseeds = [b\"escrow\", transaction_id.as_bytes()]\n\nagent: Pubkey                              // 32 bytes - Client/consumer\napi: Pubkey                                // 32 bytes - API provider\namount: u64                                // 8 bytes  - Escrowed amount in lamports\nstatus: EscrowStatus                       // 2 bytes  - Active | Released | Disputed | Resolved\ncreated_at: i64                            // 8 bytes  - Unix timestamp\nexpires_at: i64                            // 8 bytes  - Time-lock expiration\ntransaction_id: String                     // 68 bytes - 4 (length) + 64 (max_len)\nbump: u8                                   // 1 byte   - PDA bump seed\nquality_score: Option\u003cu8\u003e                  // 2 bytes  - Oracle quality assessment (0-100)\nrefund_percentage: Option\u003cu8\u003e              // 2 bytes  - Refund percentage (0-100)\n```\n\n**EntityReputation PDA**\n```rust\nseeds = [b\"reputation\", entity.key().as_ref()]\n\nentity: Pubkey                             // 32 bytes - Agent or API provider\nentity_type: EntityType                    // 2 bytes  - Agent | Provider\ntotal_transactions: u64                    // 8 bytes  - Total completed transactions\ndisputes_filed: u64                        // 8 bytes  - Total disputes initiated\ndisputes_won: u64                          // 8 bytes  - Full refunds (quality \u003c50)\ndisputes_partial: u64                      // 8 bytes  - Partial refunds (quality 50-79)\ndisputes_lost: u64                         // 8 bytes  - No refund (quality ≥80)\naverage_quality_received: u8               // 1 byte   - Running average quality score\nreputation_score: u16                      // 2 bytes  - Calculated score (0-1000)\ncreated_at: i64                            // 8 bytes  - Account creation timestamp\nlast_updated: i64                          // 8 bytes  - Last reputation update\nbump: u8                                   // 1 byte   - PDA bump seed\n```\n\n## Oracle Integration\n\n### Centralized (Python)\nEd25519-signed quality assessment with on-chain signature verification.\n\n### Decentralized (Switchboard)\nOn-Demand pull feed with cryptographic attestation. Timestamp validation enforces 300-second freshness window.\n\n```rust\nlet feed_data = PullFeedAccountData::parse(feed_account_info.data.borrow())?;\nlet age = clock.unix_timestamp - feed_data.last_update_timestamp;\nrequire!(age \u003e= 0 \u0026\u0026 age \u003c= 300, StaleAttestation);\n```\n\n## Quality Scoring\n\nOracle outputs:\n1. **quality_score** (0-100): Weighted assessment\n2. **refund_percentage** (0-100): Refund amount\n\nRefund logic determined by oracle. Typical mapping:\n- Score \u003c 50 → Full refund\n- Score 50-79 → Partial refund\n- Score ≥ 80 → No refund\n\n## Packages\n\nMonorepo with 6 specialized packages for different use cases:\n\n| Package | Description | Quick Start |\n|---------|-------------|-------------|\n| **[x402-escrow](packages/x402-escrow/)** | Solana program (Anchor) | `cd packages/x402-escrow \u0026\u0026 anchor build` |\n| **[x402-sdk](packages/x402-sdk/)** | TypeScript client library | `npm install @kamiyo/x402-sdk` |\n| **[x402-middleware](packages/x402-middleware/)** | HTTP 402 middleware (Express/FastAPI) | `npm install @x402resolve/middleware` |\n| **[mcp-server](packages/mcp-server/)** | Model Context Protocol server for AI agents | [See MCP Server section](#mcp-server-ai-agent-integration) |\n| **[agent-client](packages/agent-client/)** | Autonomous agent implementation | `npm install @kamiyo/agent-client` |\n| **[switchboard-function](packages/switchboard-function/)** | Decentralized oracle function | [Integration Guide](packages/x402-escrow/SWITCHBOARD_INTEGRATION.md) |\n\nEach package contains its own README with detailed setup instructions and examples.\n\n## Security\n\n- Checked arithmetic for all calculations\n- PDA authority isolation\n- Time-lock bounds (1h - 30d)\n- Amount limits (0.001 - 1000 SOL)\n- Rent-exempt validation\n- Rate limiting by verification tier\n\nSee [SECURITY.md](./SECURITY.md) for details.\n\n## API Reference\n\n### SDK Methods\n\n| Method | Parameters | Returns | Description |\n|--------|-----------|---------|-------------|\n| `client.pay()` | `{ amount, recipient, enableEscrow }` | `{ token, escrowAddress, transactionId }` | Create payment with optional escrow |\n| `client.fileDispute()` | `{ transactionId, qualityScore, evidence }` | `Promise\u003cvoid\u003e` | File dispute for poor quality |\n| `client.getDisputeStatus()` | `transactionId: string` | `{ status, refundPercentage }` | Get dispute resolution status |\n| `escrow.createEscrow()` | `{ api, amount, timeLock }` | `PublicKey` | Create escrow account |\n| `escrow.markDisputed()` | `escrowPDA: PublicKey` | `Transaction` | Mark escrow as disputed |\n| `escrow.releaseFunds()` | `escrowPDA: PublicKey` | `Transaction` | Release funds to API provider |\n\n### Middleware Configuration\n\n```typescript\nx402PaymentMiddleware({\n  programId: PublicKey,      // Escrow program ID\n  connection: Connection,    // Solana RPC connection\n  price: number,            // Price in SOL\n  realm: string,            // API identifier\n  qualityGuarantee: boolean // Enable quality refunds (default: false)\n})\n```\n\n### Error Handling\n\n| Error Code | Message | Solution |\n|------------|---------|----------|\n| `PAYMENT_REQUIRED` | No payment proof provided | Include `X-Payment-Proof` header with escrow address |\n| `INVALID_ESCROW` | Escrow account not found | Verify escrow creation succeeded |\n| `ESCROW_EXPIRED` | Time lock expired | Create new escrow |\n| `QUALITY_TOO_LOW` | Quality below threshold | Review quality scoring logic |\n| `RATE_LIMIT_EXCEEDED` | Too many requests | Wait or upgrade verification tier |\n\nFull examples: [API_EXAMPLES.md](docs/API_EXAMPLES.md)\n\n## Documentation\n\n- [API Reference](./docs/markdown/API_REFERENCE.md)\n- [Switchboard Integration](./packages/x402-escrow/SWITCHBOARD_INTEGRATION.md)\n- [Troubleshooting](./TROUBLESHOOTING.md)\n\n## Roadmap\n\n| Timeline | Status | Features |\n|----------|--------|----------|\n| **Nov 2025 (Hackathon)** | Live | Solana escrow program (devnet), MCP server (Claude integration), TypeScript SDK, HTTP 402 middleware (Express), Switchboard On-Demand oracle, Quality-based sliding-scale refunds, Reputation tracking |\n| **Dec 2025 - Feb 2026** | Phase 1 | Mainnet MCP ecosystem launch, LangChain/AutoGPT integrations, 10+ API provider onboarding, Security audit for mainnet, Multi-oracle consensus (3+ verifiers), Mainnet dispute resolution UI |\n| **Mar - May 2026** | Phase 2 | Developer platform integrations (Replit, Zed), Framework middleware (FastAPI, Next.js), SPL token escrows (USDC/USDT), Enhanced ML quality scoring |\n| **Jun - Nov 2026** | Phase 3 | Enterprise white-label deployments, Cross-chain support (Base, Ethereum via Wormhole), Pyth price feeds, Governance token launch, SOC2/GDPR compliance packages |\n| **2027+** | Phase 4 | Protocol standardization (RFC submission), Multi-chain expansion, Chainlink CCIP integration, DAO governance, NFT-gated API access, Jupiter aggregator |\n\n**See full strategy:** [Market Analysis \u0026 GTM](docs/MARKET_STRATEGY.md)\n\n## License\n\nMIT | KAMIYO\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamiyo-ai%2Fx402resolve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkamiyo-ai%2Fx402resolve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamiyo-ai%2Fx402resolve/lists"}