diff --git a/python/examples/adk-demo/BLOG_POST.md b/python/examples/adk-demo/BLOG_POST.md new file mode 100644 index 0000000..6fc76f4 --- /dev/null +++ b/python/examples/adk-demo/BLOG_POST.md @@ -0,0 +1,97 @@ +# Building Agentic Payments with Nevermined x402, A2A, and AP2 + +## TL;DR (Product) + +Agents shouldn’t just talk—they should transact safely. Nevermined x402 adds programmable, on-chain payment permissions via smart account policies. A2A carries secure agent-to-agent messages, AP2 layers payment context, and x402 enforces what can be paid for. In the demo, a client agent buys from a merchant agent with real on-chain settlement, and every payment is explicitly approved and scoped by the user. + +## TL;DR (Engineering) + +The client agent generates x402 access tokens with `payments` ([payments-py](https://github.com/nevermined-io/payments-py)) using subscriber credentials. The merchant wraps business logic with an x402-aware executor, verifies, and settles on-chain through the Nevermined facilitator. A2A transports the payment-required/payment-submitted messages, AP2 standardizes the payment metadata, and smart account policies define what each x402 token can do: plan, agent, amount, network, and scheme. All setup and code are in [the demo README](https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md). + +--- + +## Why Agentic Payments Matter + +For product teams, agentic payments unlock real revenue moments without bolting on fragile custom logic. Every payment request is transparent to the user, explicitly approved, and tightly scoped, so you maintain trust while shipping faster. Plans, products, and pricing live in the protocol layer—meaning pricing changes or new SKUs don’t require reworking agent code. Because settlement is on-chain, you get auditable, final transactions instead of best-effort logs. And since A2A/AP2/x402 are standards-based, your agents can interoperate with partners’ agents instead of being trapped in one ecosystem. The demo illustrates this with a client (subscriber) agent buying from a merchant (seller), showing on-chain verification, settlement, and clear user consent. + +--- + +## How A2A, AP2, and x402 fit together + +A2A is the reliable messaging rail between agents. AP2 adds payment semantics to those messages—who is requesting payment, for what plan, and how much. x402 then acts as the enforceable permission layer: the client signs an x402 access token that encodes the allowed plan, agent, amount, network, and scheme. The merchant validates that token, executes business logic, and settles on-chain through Nevermined. Together, A2A keeps the conversation coherent, AP2 keeps the payment intent explicit, and x402 keeps the payment enforceable. + +## Flow overview (visual) + +```mermaid +sequenceDiagram + participant U as User + participant C as Client agent + participant M as Merchant agent + participant N as Nevermined facilitator + participant B as Blockchain + + U->>C: Buy item + M-->>C: payment-required (plan, agent, amount, network) + C->>U: Prompt for approval + U-->>C: Approve + C->>C: Generate x402 token (payments) + C->>M: payment-submitted (x402 token + requirements) + M->>N: verify token + policies + N->>B: Simulate/verify spend + N-->>M: Verified + M->>B: Settle (burn credits) + B-->>M: Tx hash + M-->>C: Receipt + result + C-->>U: Success + updated balance +``` + +--- + +## How the flow works + +1. The user asks the client agent to buy something. +2. The merchant agent responds with a payment-required message that specifies plan, agent, amount, network, and scheme (AP2). +3. The client prompts the user for approval. +4. The client calls `payments` ([payments-py](https://github.com/nevermined-io/payments-py)) to mint an x402 access token scoped by smart account policies. +5. The client sends the token and requirements to the merchant. +6. The merchant verifies via the Nevermined facilitator. +7. On success, the merchant runs business logic and settles on-chain, burning the authorized credits and returning a transaction hash. +8. The client fetches the updated balance and reports success. + +In the demo, a single merchant can expose multiple payment methods—credits plans and pay-as-you-go—under the same agent. The facilitator (see the x402 facilitator concept [here](https://x402.gitbook.io/x402/core-concepts/facilitator)) plugs into x402 to verify and settle whichever plan is in use, so the flow stays identical while pricing models change. You can see real Base Sepolia settlements from the demo for pay-as-you-go [tx](https://sepolia.basescan.org/tx/0xf88cb8217505c25d8225c803332b4da6b4c18f93a51b384d4fdc0a9205512b7c) and for credits plans [tx](https://sepolia.basescan.org/tx/0xe476f4612bd2293954f64f493f04239a7867efcbc522e00daec6732a1ce6e5f3). + +## The facilitator’s role + +The facilitator is the enforcement and settlement bridge between x402 permissions and the chain. It takes the client’s x402 token and the merchant’s requirements, verifies that the requested spend fits policy (plan, agent, amount, scheme, network), and then settles on-chain by burning the allowed credits. Because it is protocol-aware, you can swap pricing models (credits vs. pay-as-you-go) without changing the agent conversation flow. For product teams, this means a consistent UX with pluggable monetization; for engineering teams, it means a single integration point that handles verification, settlement, and receipts. + +## Smart account policies and x402 permissions + +Smart account policies are the product control plane for payments. They define which plan a token can draw from, which agent it authorizes, how many credits it can burn, and on which network and scheme. Practically, this delivers safety and predictability: a token is valid only for the named agent and plan, it cannot exceed its credit allowance, and once credits are consumed the token fails gracefully. On-chain settlement enforces these limits, giving you auditability and customer-friendly guardrails (no surprise overages). This matches the smart-account extension in the Nevermined x402 integration and the broader positioning of x402 agent payments. + +--- + +## Why this pattern scales + +Separating payment protocol from business logic keeps agents maintainable while allowing commerce rules to evolve. Scoped permissions and explicit user approval provide safety; on-chain verification and settlement provide finality. Because A2A/AP2/x402 are standards-focused, merchants, clients, and facilitators can be swapped or composed without rewriting core flows. + +--- + +## Try the demo and go deeper + +Check out the demo repository and README for setup, run instructions, and deeper technical details: [a2a-x402 demo](https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md). It covers environment setup, x402 token generation on the client side, server verification and settlement via the `payments` ([payments-py](https://github.com/nevermined-io/payments-py)) facilitator, AP2 message shapes, and full sequence diagrams and logs. + +--- + +## Key takeaways + +Agentic payments require consent, scoped permissions, and verifiable settlement—x402 plus Nevermined deliver that. Smart account policies make permissions programmable and enforceable. A2A/AP2 keep messaging and payment intent standardized so agents can coordinate cleanly. The demo is production-leaning: real on-chain verification and settlement with a clear separation between business logic and payment protocol. + +--- + +## References + +- [payments-py SDK](https://github.com/nevermined-io/payments-py) +- [a2a-x402 demo README](https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md) +- [x402 facilitator concept](https://x402.gitbook.io/x402/core-concepts/facilitator) +- [Nevermined x402 integration notes](https://github.com/nevermined-io/contracts/blob/main/docs/x402/NVM-x402_integration.md) +- [Nevermined + x402 positioning](https://www.linkedin.com/pulse/nevermined-x402-bridging-next-generation-payments-aitor-argomaniz-6ea1f/?trackingId=0kivr7zEZeiNP7jP7oAUmA%3D%3D) diff --git a/python/examples/adk-demo/BLOG_POST_v2.md b/python/examples/adk-demo/BLOG_POST_v2.md new file mode 100644 index 0000000..6d29909 --- /dev/null +++ b/python/examples/adk-demo/BLOG_POST_v2.md @@ -0,0 +1,319 @@ +# Building Agentic Payments with Nevermined x402, A2A, and AP2 + +### How agents learn to trust, transact, and settle on-chain + +AI agents today can research, negotiate, and collaborate—but when it comes to handling payments, everything suddenly becomes messy. Custom logic everywhere. Fragile approval flows. No standard way to express or enforce what an agent is allowed to spend. And worst of all, no clear trust model for users. + +Nevermined’s integration with **x402**, **A2A**, and **AP2** introduces a clean, safe, programmable way for agents to make payments with real on-chain settlement. The result is a system where users stay in control, product teams gain a consistent pricing layer, and engineers no longer have to reinvent payments inside every agent workflow. + +In our latest demo, a client agent purchases from a merchant agent with explicit user approval and verifiable settlement. The flow is simple, auditable, and fully interoperable. + +--- + +# TL;DR (Product) + +AI agents shouldn’t just communicate—they should transact safely. +Nevermined x402 introduces programmable, on-chain payment permissions enforced by smart account policies. +A2A provides secure agent-to-agent messaging, AP2 expresses payment context, and x402 guarantees that agents can only spend what the user explicitly authorizes. + +In the demo, a client agent buys from a merchant agent with real on-chain settlement. Every step—request, approval, transfer, receipt—is validated and enforced by protocol design. + +--- + +# TL;DR (Engineering) + +- The client agent mints x402 access tokens using `payments` ([payments-py](https://github.com/nevermined-io/payments-py)). +- These tokens encode scoped spend permissions: plan, agent, amount, network, scheme. +- The merchant verifies and settles through the Nevermined facilitator. +- A2A transports payment-required and payment-submitted messages. +- AP2 standardizes payment metadata. +- Smart-account policies enforce the allowed spend on-chain. + +All code is reproducible in the demo: +https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md + +--- + +# Why Agentic Payments Matter + +If agents are going to participate in real commerce, they need: + +- Clear, bounded permissions +- Explicit user approval +- Predictable pricing +- Transparent receipts +- Guardrails that prevent overspending or unauthorized actions + +Nevermined x402 provides exactly that. +AP2 standardizes payment intent, A2A transports messages, and x402 enforces permissions using smart-account policies. + +Crucially, plans, SKUs, quotas, and pricing models live in the **policy layer**, not in each agent’s code. Changing pricing or adding new products becomes a config update—no agent refactoring required. + +Because settlement is on-chain, businesses get: + +- deterministic receipts +- auditability +- finality +- reduction in payment-related integration bugs + +The demo shows a subscriber agent purchasing from a merchant agent with real settlement, verification, and user-controlled permissions. + +--- + +# How A2A, AP2, and x402 Fit Together + +### A2A — Communication Layer + +A reliable messaging rail enabling structured, secure agent-to-agent conversations. + +### AP2 — Payment Intent Layer + +A standardized schema encoding: + +- plan +- amount +- network +- pricing scheme +- merchant agent +- metadata + +### x402 — Permission + Enforcement Layer + +x402 turns intent into enforceable permissions. +The x402 token created by the client agent specifies: + +- which plan may be used +- which merchant agent is allowed +- max spend +- scheme (credits / PAYG) +- network +- validity window + +The merchant validates the token via the facilitator before executing any payment logic. + +Together they provide a clean mental model: + +> **A2A** keeps the conversation coherent +> **AP2** keeps the payment intent explicit +> **x402** keeps the spend enforceable + +--- + +# Flow Overview + +The demo implements the following transaction sequence: + +1. User instructs client agent to purchase something. +2. Merchant sends an AP2 `payment-required` message describing plan, amount, scheme, network. +3. Client asks user for approval. +4. User approves. +5. Client generates an x402 token with allowed permissions. +6. Client sends `payment-submitted` with x402 token + metadata. +7. Merchant calls facilitator to verify token/policies. +8. Facilitator simulates spend and returns validation. +9. Merchant settles on-chain (burns credits or deducts PAYG). +10. Merchant returns receipt + transaction hash. +11. Client updates the user’s balance and displays success. + +You can inspect real demo transactions: + +- Pay-as-you-go: [https://sepolia.basescan.org/tx/0xf88cb8217505c25d8225c803332b4da6b4c18f93a51b384d4fdc0a9205512b7c](https://sepolia.basescan.org/tx/0xf88cb8217505c25d8225c803332b4da6b4c18f93a51b384d4fdc0a9205512b7c) + +- Credits plan: [https://sepolia.basescan.org/tx/0xe476f4612bd2293954f64f493f04239a7867efcbc522e00daec6732a1ce6e5f3](https://sepolia.basescan.org/tx/0xe476f4612bd2293954f64f493f04239a7867efcbc522e00daec6732a1ce6e5f3) + +--- + +# Sequence Diagram + +```mermaid +sequenceDiagram + participant U as User + participant C as Client agent + participant M as Merchant agent + participant N as Nevermined facilitator + participant B as Blockchain + + U->>C: Buy item + M-->>C: payment-required (plan, agent, amount, network) + C->>U: Prompt for approval + U-->>C: Approve + C->>C: Generate x402 token (payments) + C->>M: payment-submitted (x402 token + requirements) + M->>N: Verify token + policies + N->>B: Simulate/verify spend + N-->>M: Verified + M->>B: Settle (burn credits) + B-->>M: Tx hash + M-->>C: Receipt + result + C-->>U: Success + updated balance +``` + +--- + +# The Facilitator’s Role + +The facilitator is the enforcement and settlement engine for x402. It: + +- validates x402 tokens +- checks smart-account policies +- simulates spend on-chain +- executes settlement (burn or deduct) +- returns canonical receipts + +This enables product teams to: + +- change pricing models without altering agent logic +- mix credit plans, PAYG, subscriptions, or hybrid models +- guarantee safe and predictable spending patterns + +For engineering teams, the facilitator becomes the single integration point for all settlement behavior. + +--- + +# Smart Account Policies and x402 Permissions + +Smart account policies define: + +- which plans exist +- what merchants are allowed +- how many credits a token can burn +- on which chain or scheme the payment may occur +- how long permissions remain valid + +For users, this means strong protection: + +- no paying unauthorized agents +- no accidental overspending +- no ambiguous or hidden charges + +For businesses, this means enforceable monetization with predictable guardrails. + +x402 ensures these policies are not optional—they are cryptographically enforced. + +--- + +# Why This Pattern Scales + +This architecture decouples business logic from payment logic: + +- A2A: communication +- AP2: intent semantics +- x402: permissions +- Facilitator: verification and settlement + +This modularity ensures: + +- monetization evolves independently from agent capabilities +- agents can interoperate across ecosystems +- safety and consent become core features, not add-ons +- enterprise guardrails become programmable + +This is the foundation for agentic commerce: agents that transact deliberately, safely, and verifiably. + +--- + +# Try the Demo + +Explore the full implementation here: + +👉 https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md + +The repo includes: + +- agent setup +- environment configuration +- x402 token generation +- facilitator verification +- AP2 messaging +- real Base Sepolia settlement +- logs, diagrams, and examples + +--- + +# Scaling Beyond the Demo + +With this pattern, agents can: + +- Subscribe to services +- Charge for compute or data +- Orchestrate multi-agent workflows requiring payments +- Enforce enterprise-level budget controls +- Operate in marketplaces with trusted settlement + +It unlocks a new category: **agentic commerce**. + +--- + +# Key Takeaways + +- Agents need safe, programmable ways to transact. +- x402 + Nevermined provides enforceable permissions and user-controlled spending. +- A2A/AP2 standardize communication and payment intent. +- Smart account policies act as a product-level control plane. +- The facilitator ensures verification and settlement are secure and final. +- The pattern is modular, interoperable, and ready for real-world agent commerce. + +--- + +# Future Directions: Connecting This Work With ERC-8004 + +The emerging [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) standard proposes a trustless extension of Google’s A2A protocol for on-chain agents. The specification focuses on agent identity, verifiable interactions, and secure message exchange. + +A key design choice is that ERC-8004 is intentionally scoped as a **communication and capability layer**. +The standard does [**not** define billing, credit accounting, metering, or payment settlement](https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098/16). Contributors in the Ethereum Magicians discussion explicitly position those concerns as **higher-level protocols** to be built on top of ERC-8004. + +This creates a natural point of integration with the approach demonstrated in our x402 + A2A/AP2 flow. While ERC-8004 defines **who** the agent is and **how** it communicates, the Nevermined implementation defines **what the agent is allowed to spend** and **how that spend is enforced on-chain**. + +Together, they form a complementary stack: + +### 1. Trustless agent communication and capabilities (ERC-8004) + +- Cryptographic agent identity +- Signed messages and verifiable instructions +- Capability registration and discovery + +### 2. Trustless, scoped payment permissions (x402) + +- Explicit spend limits +- Allowed merchant/agent relationships +- Plan/SKU binding +- Pricing scheme (credits, PAYG) +- Network-level constraints + +### 3. Standardized payment semantics (AP2) + +- Predictable request/response message shapes +- Plan + product identifiers +- Pricing metadata + +### 4. On-chain enforcement and settlement (Nevermined facilitator) + +- Policy verification +- Spend simulation +- Credit burning / PAYG deduction +- Canonical receipts for agents and users + +### What This Enables + +By combining ERC-8004 with x402/AP2, we unlock a trustless economic layer for agents: + +- Autonomous agents that can safely pay each other +- Agent marketplaces with verifiable settlement +- Metered compute and data APIs +- Multi-agent workflows with delegated budgets +- Composable monetization for agent ecosystems +- Enterprise agents with enforceable spending controls + +We see this as a natural extension of ERC-8004’s goals and an opportunity for deeper collaboration with the Ethereum community around **trustless agent commerce**—a foundational capability for the next generation of AI-native applications. + +--- + +# References + +- [payments-py SDK](https://github.com/nevermined-io/payments-py) +- [a2a-x402 demo README](https://github.com/nevermined-io/a2a-x402/blob/feat/a2a-nvm/python/examples/adk-demo/README.md) +- [x402 facilitator concept](https://x402.gitbook.io/x402/core-concepts/facilitator) +- [Nevermined x402 integration notes](https://github.com/nevermined-io/contracts/blob/main/docs/x402/NVM-x402_integration.md) +- [Nevermined + x402 positioning](https://www.linkedin.com/pulse/nevermined-x402-bridging-next-generation-payments-aitor-argomaniz-6ea1f/?trackingId=0kivr7zEZeiNP7jP7oAUmA%3D%3D) +- [ERC-8004: Trustless Agents](https://eips.ethereum.org/EIPS/eip-8004) +- [Ethereum Magicians ERC-8004: Trustless Agents](https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098/9)