[Feature]Integrate x402 (HTTP 402 Payment Protocol) & AP2 (Agents-to-Payments Protocol) for SpoonOS Web3 AI Agent Monetization

[veithly]

1. Feature Overview

Based on official protocol definitions (x402 from x402.org and AP2 from Google’s Agents-to-Payments initiative), this feature aims to integrate two payment-centric protocols into SpoonOS (Agentic OS for the Sentient Economy) to solve a critical gap: enabling AI agents to frictionlessly pay for web resources (x402) and standardize agent-to-agent payment workflows (AP2).

• x402: An open, web-native protocol that activates the HTTP 402 "Payment Required" status code, allowing servers to charge for API/resources via crypto (e.g., USDC) without user registration, OAuth, or complex signatures.
• AP2 (Agents-to-Payments Protocol): Google’s proposed standard for AI agents to initiate, verify, and settle payments with other agents or services—aligning with x402’s web-native design to create end-to-end agent payment workflows.

By combining x402 and AP2, SpoonOS will empower developers to build self-sustaining AI agents that can: 1) Pay for third-party API access (e.g., cloud storage, real-time data) via x402; 2) Settle payments with other agents via AP2; 3) Monetize their own agent services by accepting x402/AP2 payments—all without manual intervention.

2. Core Objectives

Objective	Description
x402 Web-Native Payment Support	Enable SpoonOS agents to send x402-compliant payments for API/resources (e.g., paying a data provider for real-time crypto prices) and accept x402 payments for their own services (e.g., a SpoonOS trading agent charging users for strategy insights).
AP2 Agent Payment Standard Compliance	Make SpoonOS agents AP2-compatible to standardize agent-to-agent payment flows: - Initiate payment requests (e.g., "Agent A requests 0.01 USDC from Agent B for task execution"). - Verify payment receipts (via blockchain or AP2’s verification layer). - Settle payments in alignment with x402’s instant settlement.
Seamless x402 + AP2 Synergy	Link AP2’s agent payment logic to x402’s web-native implementation: e.g., an AP2 payment request triggers x402 headers for HTTP API access, or a SpoonOS agent uses AP2 to verify x402 payment success before providing a service.
Zero-Friction Developer Experience	Follow x402’s "1 line of code" philosophy and SpoonOS’s modular design to provide pre-built middleware, CLI tools, and examples—no deep blockchain/payment protocol expertise required.

3. Key Functional Modules

3.1 x402 Web-Native Payment Module (Aligned with x402.org)

3.1.1 Core Capabilities (Based on x402’s Official Features)

• x402 Payment Middleware: Add a lightweight middleware (compatible with SpoonOS’s Python stack) that lets developers enable x402 payments for their agent’s API endpoints with minimal code—mirroring x402’s "1 line of code" design.
  Example implementation (for a SpoonOS agent exposing a "crypto_analysis" API):

  from spoon_ai.payments.x402 import x402_middleware
  
  # Enable x402 payment: charge 0.01 USDC for /crypto_analysis endpoint (1 line of core logic)
  app.use(x402_middleware(recipient_address="0xYourUSDCWallet", endpoint_rates={"/crypto_analysis": "0.01 USDC"}))

  • When a client (agent or user) calls /crypto_analysis without payment, the server returns HTTP 402 Payment Required with x402 headers (e.g., X-402-Amount: 0.01 USDC, X-402-Recipient: 0x...).
  • After the client completes the crypto payment (via x402’s blockchain-agnostic flow), the server verifies the payment and serves the API response.

• x402 Payment Client for Agents: Add a built-in tool (x402_payment_client) for SpoonOS agents to automatically handle x402 payment requests when accessing third-party APIs.
  Example agent workflow (paying for a data API):

  from spoon_ai.tools.x402 import X402PaymentClient
  
  # Initialize client (uses SpoonOS's existing wallet config for funds)
  x402_client = X402PaymentClient(wallet_address="0xSpoonOSAgentWallet")
  
  # Call a third-party API that requires x402 payment
  api_response = x402_client.call_paid_api(
      url="https://api.data-provider.com/real-time-btc-price",
      method="GET"
  )
  # Under the hood: 
  # 1. If API returns 402, client reads x402 headers to get amount/recipient
  # 2. Client sends crypto payment (e.g., USDC) via SpoonOS's Web3 infrastructure
  # 3. Client retries the API with x402 payment proof header

• Blockchain-Agnostic Support: Align with x402’s "blockchain-agnostic" design—support major blockchains (Ethereum, Solana, Sui) that SpoonOS already integrates with. Let developers configure preferred tokens (e.g., USDC on Ethereum, USDT on Solana) via config.json.

3.2 AP2 (Agents-to-Payments Protocol) Integration Module (Based on Google’s AP2 Vision)

3.2.1 Core Capabilities (Aligned with AP2’s "Agent Payment Standard" Goal)

• AP2 Payment Request/Response: Add AP2-compliant methods for SpoonOS agents to send/receive payment requests to other agents. Follow AP2’s focus on "agent-centric payments" to avoid human intervention.
  Example: Agent A (SpoonOS) requests payment from Agent B (external AP2 agent) for task execution:

  from spoon_ai.payments.ap2 import AP2PaymentHandler
  
  ap2_handler = AP2PaymentHandler(agent_id="spoonos-agent-123")
  
  # Send AP2 payment request to Agent B
  payment_request = ap2_handler.create_payment_request(
      recipient_agent_id="external-agent-456",
      amount="0.02 USDC",
      purpose="Execution of cross-chain swap task",
      expiry=300, // 5 minutes to accept
      settlement_protocol="x402" // Specify x402 for web-native settlement
  )
  
  # Wait for Agent B's acceptance
  if ap2_handler.check_payment_request_status(payment_request.id) == "accepted":
      # Use x402 to settle payment (AP2 + x402 synergy)
      x402_client.settle_payment(
          recipient_address=ap2_handler.get_agent_wallet("external-agent-456"),
          amount="0.02 USDC"
      )

• AP2 Payment Verification: Add tools to verify AP2 payment receipts via blockchain (leveraging SpoonOS’s existing blockchain explorer integrations) or AP2’s built-in verification layer. Ensure agents only deliver services after confirming payment (critical for monetization).
  Example verification:

  # Verify Agent B's payment via AP2
  is_paid = ap2_handler.verify_payment(
      payment_id="ap2-payment-789",
      expected_amount="0.02 USDC",
      expected_recipient="spoonos-agent-123"
  )
  
  if is_paid:
      # Deliver the service (e.g., send cross-chain swap results)
      send_task_results("external-agent-456", swap_results)

• AP2-SpoonoOS Ecosystem Alignment: Integrate AP2 with SpoonOS’s existing agent framework (e.g., SpoonReactMCP):

  • Add an ap2_enabled flag to agents (default: True) to toggle AP2 functionality.
  • Auto-log AP2 payment events to SpoonOS’s session history (for auditing and debugging).
  • Ensure AP2 payments work with SpoonOS’s multi-agent coordination (e.g., a supervisor agent uses AP2 to split payments among sub-agents).

3.3 x402 + AP2 Synergy (End-to-End Agent Payment Flow)

The core value of this integration lies in linking AP2’s "agent-to-agent payment logic" with x402’s "web-native payment execution"—creating a closed-loop for agent monetization. Example end-to-end flow:

1. AP2 Request: A third-party agent (e.g., a LangChain agent) sends an AP2 payment request to a SpoonOS agent, asking for real-time crypto data (cost: 0.01 USDC).
2. AP2 Acceptance: The SpoonOS agent accepts the request via AP2 and shares its x402 wallet address.
3. x402 Payment: The third-party agent uses x402 to send 0.01 USDC to the SpoonOS agent (instant settlement via x402).
4. AP2 Verification: The SpoonOS agent uses AP2 to verify the x402 payment is complete.
5. Service Delivery: The SpoonOS agent sends the requested crypto data to the third-party agent.

4. Developer Experience (DX) Enhancements

1. x402 Quick Start Examples: Add examples/payments/x402/ to SpoonOS’s examples/ directory (consistent with its docs structure) with:

   • x402_accept_payments.py: Demo of a SpoonOS agent exposing an API with x402 payments.
   • x402_pay_for_api.py: Demo of a SpoonOS agent paying for a third-party x402 API.

2. AP2 Demo: Add examples/payments/ap2/agent_to_agent_payment.py to show AP2 payment requests between two SpoonOS agents (or a SpoonOS agent and an external AP2 agent).

3. CLI Tools: Extend SpoonOS’s CLI (entry point: main.py) to simplify x402/AP2 setup:

   # Configure x402 recipient wallet
   > action payment x402 set_recipient 0xYourWalletAddress
   # List AP2 payment history
   > action payment ap2 list_history
   # Test x402 payment to a test API
   > action payment x402 test_payment https://test-api.x402.org 0.001 USDC

4. Documentation Updates: Align with SpoonOS’s developer docs structure by adding:

   • docs/payments/x402.md: Step-by-step guide to enable x402 payments (with code snippets from x402.org).
   • docs/payments/ap2.md: How to integrate AP2 for agent-to-agent payments (linking to Google’s AP2 resources).
   • docs/payments/x402_ap2_synergy.md: Examples of end-to-end payment flows (AP2 + x402).

5. Use Cases Enabled (Tied to SpoonOS’s "Sentient Economy" Vision)

1. Monetized Agent APIs: Developers build SpoonOS agents that expose paid APIs (e.g., DeFi strategy analysis) via x402—no need for subscriptions or ads (aligns with x402’s "micropayments for content" goal).
2. Agent-to-Agent Service Marketplaces: SpoonOS agents offer services to other agents (e.g., a "NFT minting agent" helping a "collector agent") and settle payments via AP2 + x402—creating a self-sustaining agent ecosystem.
3. Frictionless Third-Party Data Access: SpoonOS agents pay for real-time data (e.g., crypto prices, news) via x402 without manual API keys or registration—critical for autonomous agent operation.
4. Multi-Agent Payment Splits: A SpoonOS supervisor agent uses AP2 to split payments among sub-agents (e.g., 70% to a "trading agent", 30% to a "risk analysis agent") after completing a client task.

6. Technical Dependencies (Leveraging SpoonOS’s Existing Stack)

Dependency	Purpose	Alignment with SpoonOS
x402 Protocol Libraries	Implement x402 middleware and payment client	Use lightweight, open-source x402 libraries (consistent with x402.org’s "open standard" ethos) to avoid bloating SpoonOS.
SpoonOS Web3 Infrastructure	Handle crypto payments (e.g., USDC transfers) for x402/AP2	Reuse SpoonOS’s existing wallet (Turnkey SDK), RPC endpoints, and blockchain explorer integrations—no new Web3 setup.
FastAPI	Expose x402/AP2 endpoints for agents	SpoonOS’s Python stack already supports async frameworks; FastAPI is ideal for HTTP-based x402 middleware.
AP2 Reference Implementations	Build AP2 payment logic	Integrate with Google’s open AP2 reference code (once available) to ensure compliance with the protocol.
SpoonOS CLI Framework	Add x402/AP2 CLI commands	Extend the existing CLI (from main.py) to avoid breaking developer workflows.

[veithly]

#170 #194