feat: Adding example demo showing how the Intent, Cart and Payment mandates… #43

jorellis · 2025-10-16T22:06:16Z

Adding python example to demo how Mandates from AP2 (ap2-protocol.org) can be used while facilitating an x402 transaction.

The demo steps are explain in the readme in python/examples/ap2-demo

Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

Follow the CONTRIBUTING Guide.
Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
Ensure the tests and linter pass
Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

gemini-code-assist · 2025-10-16T22:06:38Z

Summary of Changes

Hello @jorellis, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new, fully functional example that demonstrates the end-to-end process of agent-to-agent commerce using the Agent Payments Protocol (AP2) and the x402 payments extension. It provides a practical implementation of a client agent, a merchant agent, and a mock wallet, illustrating how mandates for intent, cart, and payment are created, signed, and processed to facilitate a secure and verifiable transaction flow. The example also includes necessary infrastructure for running these agents and services, along with detailed instructions for setup and execution.

Highlights

New AP2 & x402 Demo: Introduced a comprehensive Python example demonstrating the Agent Payments Protocol (AP2) integrated with the x402 payments extension, showcasing an 'Embedded Flow' for agent-to-agent transactions.
Client Agent Implementation: Added a Client Agent built with the Google Agent Development Kit (ADK) that orchestrates the purchase flow, handles user interaction, and manages the sequence of digitally signed mandates.
Mock Wallet Service: Implemented a Flask-based Mock Wallet service responsible for simulating a user's wallet, capable of signing both standard AP2 mandates and EIP-712 typed data for x402 transactions.
Merchant Agent & Payment Processing: Developed a Merchant Agent that can create product carts, generate CartMandates with x402 payment requirements, and process PaymentMandates by interacting with a Mock Facilitator for settlement.
EIP-712 Signing Refinement: Refactored the x402_a2a/core/wallet.py to directly construct and sign EIP-712 typed data for EIP-3009 transferWithAuthorization transactions, improving clarity and directness of the signing process.
Server Executor State Management: Adjusted the x402ServerExecutor in x402_a2a/executors/server.py to manage _payment_requirements_store as an instance-level attribute rather than a class-level attribute, enhancing isolation and preventing unintended state sharing across requests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request adds a comprehensive example demonstrating an agent-to-agent payment flow using AP2 mandates and the x402 protocol. The changes are extensive, introducing a client agent, a merchant agent, and a mock wallet. My review focuses on improving security, correctness, and maintainability. Key findings include a critical security issue with a hardcoded API key, incorrect function calls that will lead to runtime errors, improper nonce generation, and several areas where the code can be made more robust and maintainable by removing hardcoded values and using Pydantic models for validation.

gemini-code-assist · 2025-10-16T22:09:05Z

python/x402_a2a/core/wallet.py

+    return process_payment(
+        selected_requirement,
+        account,
+        rpc_url,
+        ASSET_CONTRACT_ADDRESS,
+        ASSET_ABI,
+        max_value,
+        valid_after,
+        valid_before,
+    )


The process_payment function is called with incorrect arguments. Its new signature is (requirements, account, max_value, valid_after, valid_before), but it's being called here with rpc_url, ASSET_CONTRACT_ADDRESS, and ASSET_ABI as extra arguments. This will raise a TypeError at runtime.

return process_payment( selected_requirement, account, max_value, valid_after, valid_before, )

python/x402_a2a/core/wallet.py

python/examples/ap2-demo/client_agent/_remote_agent_connection.py

gemini-code-assist · 2025-10-16T22:09:06Z

python/examples/ap2-demo/client_agent/client_agent.py

+                value=value,
+                valid_after=valid_after,
+                valid_before=valid_before,
+                nonce="0x" + os.urandom(32).hex(),  # Pass nonce as a hex string


A random nonce is generated using os.urandom(). For EIP-3009 transferWithAuthorization, the nonce must be a sequential, on-chain value fetched from the smart contract for the user's address to prevent replay attacks. Using a random nonce is incorrect and insecure. You should fetch the nonce from the USDC contract using the nonces function, which is already defined in your USDC_ABI.

Suggested change

nonce="0x" + os.urandom(32).hex(), # Pass nonce as a hex string

nonce=usdc_contract.functions.nonces(self._wallet_address).call().to_bytes(32, 'big'), # Fetch on-chain nonce

gemini-code-assist · 2025-10-16T22:09:06Z

python/examples/ap2-demo/client_agent/_task_store.py

+            current_temp_artifact = self._artifact_chunks[artifact.artifactId][-1]
+            # TODO handle if current_temp_artifact is missing


Accessing self._artifact_chunks[artifact.artifactId][-1] is unsafe and will raise an IndexError if the list of chunks for that artifactId is empty. This could occur if an append event is received before the initial chunk. You should add a check to handle this edge case gracefully to prevent the agent from crashing.

if not self._artifact_chunks.get(artifact.artifactId): logger.warning( "Received an append chunk for an artifact ID (%s) that has no initial chunk. Discarding.", artifact.artifactId, ) return current_temp_artifact = self._artifact_chunks[artifact.artifactId][-1]

python/examples/ap2-demo/client_agent/client_agent.py

python/examples/ap2-demo/server/agents/mock_facilitator.py

gemini-code-assist · 2025-10-16T22:09:07Z

python/examples/ap2-demo/server/agents/mock_facilitator.py

+        self.facilitator_private_key = (
+            os.getenv(
+                "FACILITATOR_PRIVATE_KEY",
+                "0000000000000000000000000000000000000001")
+        )


A default private key is hardcoded in the source code. While this is for a facilitator in a demo, it's a bad practice to have private keys, even test ones, directly in the code. It's better to raise an error if the FACILITATOR_PRIVATE_KEY environment variable is not set, ensuring it's configured explicitly.

self.facilitator_private_key = os.getenv("FACILITATOR_PRIVATE_KEY") if not self.facilitator_private_key: raise ValueError("FACILITATOR_PRIVATE_KEY environment variable not set.")

python/examples/ap2-demo/client_agent/_task_store.py

python/examples/ap2-demo/client_agent/_remote_agent_connection.py

kunalsekhriG · 2025-10-16T22:35:54Z

python/x402_a2a/core/wallet.py

+# Contract address for the asset being used. Can be overridden by an environment variable.
+# Defaults to the Base Sepolia USDC Asset Contract
+ASSET_CONTRACT_ADDRESS = os.getenv(
+    "ASSET_CONTRACT_ADDRESS", "0x036CbD53842c5426634e7929541eC2318f3dCF7e"


create fallback Base sepolia USDC asset contract as const? Shouldnt this be a mandatory check during the flow that would avoid it being hardcoded fallback value and also keep code agnostic of any specifc contract?

python/examples/ap2-demo/client_agent/_remote_agent_connection.py

python/examples/ap2-demo/local_wallet.py

python/examples/ap2-demo/server/agents/mock_facilitator.py

prkumar · 2025-10-16T22:40:13Z

python/x402_a2a/core/wallet.py

+ASSET_CONTRACT_ADDRESS = os.getenv(
+    "ASSET_CONTRACT_ADDRESS", "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+)
+ASSET_ABI = json.loads(


Is this ABI for EIP-3009?

prkumar · 2025-10-16T22:40:51Z

python/x402_a2a/core/wallet.py

+    return process_payment(
+        selected_requirement,
+        account,
+        rpc_url,
+        ASSET_CONTRACT_ADDRESS,
+        ASSET_ABI,
+        max_value,
+        valid_after,
+        valid_before,
+    )


prkumar · 2025-10-16T22:41:44Z

python/x402_a2a/core/wallet.py

+        x402_version=x402_VERSION,
+        scheme="exact",
+        network=requirements.network,


Are we intentionally only allowing exact scheme?

This is in the core library, so it'll be a breaking change, if I understand correctly.

prkumar · 2025-10-16T22:42:01Z

python/x402_a2a/core/wallet.py

+        valid_before=auth_data["valid_before"],
+        nonce=auth_data["nonce"],
+        chain_id=chain_id,
+        contract_address=ASSET_CONTRACT_ADDRESS,


hard-coded or should be passed in?

prkumar · 2025-10-16T22:43:37Z

python/x402_a2a/core/wallet.py

 ) -> PaymentPayload:
-    """Create PaymentPayload using proper x402.exact signing logic.
-    Same as create_payment_header but returns PaymentPayload object (not base64 encoded).
+    """Creates a PaymentPayload containing a valid EIP-3009 signature."""


Is it intentionally to make the reference library to only support EIP-3009 signatures? Is this a core constraint imposed by x402, regardless of whether the flow is embedded or standalone?

lingzhong · 2025-10-16T22:46:52Z

python/examples/ap2-demo/README.md

+
+This directory contains a demonstration of the Agent Payments Protocol (AP2) integrated with the x402 payments extension. It showcases the "Embedded Flow," where a client agent orchestrates a purchase from a merchant agent using a sequence of digitally signed mandates.
+
+The demo consists of three main components:


This missed the mention of the facilitor component.

python/examples/ap2-demo/client_agent/_task_store.py

lingzhong · 2025-10-16T22:57:46Z

python/examples/ap2-demo/server/agents/local_facilitator.py

+            Web3.HTTPProvider(base_sepolia_rpc_url, request_kwargs={"timeout": 120})
+        )
+        # TODO: Replace with your facilitator's private key
+        self.facilitator_private_key = os.getenv(


nit: storing secrets in class public member is highly unsafe.

It's unclear if it's overkill to worry about security best practices in this demo, but people do unfortunately use the same testnet private key as mainnet. There isn't a quick way to fully address this, but consider using Double leading underscore to make the member private to obfuscate the variable in runtime memory.

+1 to using double underscore convention here (and for different reason, renaming w3 field to _w3)

To be pedantic: double underscore does not necessary hide this data from callers; for example, the caller can read the key by passing the instance into the built-in vars function.

Yep. The moment it's in memory, it's just one line away from python reflection to grab it. Double leading underscore probably the best bang for the buck for this demo repo.

lingzhong · 2025-10-28T02:05:10Z

The current branch state fails to start up 2 (wallet, server) out of the 3 services. I've identified issues with missing ap2 source dependencies, and environment variable template set ups.

I'm also seeing a lot of 3.11 incompatibility errors, but I'll try to get the initial fixes in to unbreak the wallet and server start up.

lingzhong · 2025-10-28T02:13:11Z

All 3 services can start up now. Also fixed formatting issues causing lint errors since start of PR.

However upon interaction via the client agent, python incompatibility prevents user from starting the demo flow.

{"error": "Fail to load 'client_agent' module. name 'number' is not defined"}

lingzhong · 2025-10-28T02:31:21Z

Fixed the number type issue and the demo flow works again now.

However I noticed several other Python 3.11 compatibility issues while digging around. The pyproject.toml says we support 3.11+, but there are a handful of Python 3.12-only features being used:

Issues:

The @override decorator (used in adk_merchant_agent.py, local_facilitator.py, x402_merchant_executor.py) - this was added in Python 3.12
The new type alias syntax in _remote_agent_connection.py:32 - also 3.12+
Invalid number type hint in _remote_agent_connection.py:49 - should be int

Potential fixes:

Add typing_extensions to dependencies and make these small changes:
Import override from typing_extensions instead of typing
Replace type TaskCallbackArg = ... with TaskCallbackArg = Union[...]

There may be additional 3.11 incompatibility issues I haven't spot, so perhaps the quickest practical route to take is to mark this demo as 3.12+ instead of 3.11+, which I'm in favor of.

… from AP2 can be used while facilitating an x402 transaction

…ke actual calls to the base sepolia network by default

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Replace synchronous httpx.post() with async self.httpx_client.post() in: - sign_payment_request() - sign_payment_mandate() - sign_intent_mandate() Prevents event loop blocking and enables concurrent request handling.

jorellis requested a review from a team as a code owner October 16, 2025 22:06

jorellis changed the title ~~Adding example demo showing how the Intent, Cart and Payment mandates…~~ feat: Adding example demo showing how the Intent, Cart and Payment mandates… Oct 16, 2025

gemini-code-assist bot reviewed Oct 16, 2025

View reviewed changes

kunalsekhriG reviewed Oct 16, 2025

View reviewed changes

prkumar reviewed Oct 16, 2025

View reviewed changes

lingzhong reviewed Oct 16, 2025

View reviewed changes

lingzhong previously approved these changes Nov 1, 2025

View reviewed changes

Jordan Ellis and others added 18 commits November 3, 2025 09:42

Adding example demo showing how the Intent, Cart and Payment mandates…

529ac32

… from AP2 can be used while facilitating an x402 transaction

ruff formatting

89f6e05

fix rpc endpoing defaults

b192b96

rename mock wallet and facilitator to local since they are able to ma…

1f4df1f

…ke actual calls to the base sepolia network by default

Update python/examples/ap2-demo/client_agent/client_agent.py

44f42fa

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

clean up logging

97063e4

Update python/examples/ap2-demo/client_agent/_task_store.py

153fd7d

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update python/examples/ap2-demo/client_agent/_remote_agent_connection.py

7473fea

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Update local_wallet.py to include copyright

a47a63d

chore: allow .env.example files to be tracked in git

780b22b

feat: add missing .env.example template for ap2-demo setup

7abf21f

fix: server build break due to missing ap2 source dependency

4c67458

docs: add GOOGLE_API_KEY requirement to ap2-demo setup instructions

4fb122f

style: format wallet.py with ruff

7c4552f

fix: replace invalid 'number' type with 'int' in type hint

ca94630

fix: add missing logger import in _task_store.py

bed8f7e

security: use double underscore prefix for private key variables

89dbf74

fix: replace blocking HTTP calls with async in client agent methods

71056ad

Replace synchronous httpx.post() with async self.httpx_client.post() in: - sign_payment_request() - sign_payment_mandate() - sign_intent_mandate() Prevents event loop blocking and enables concurrent request handling.

Jordan Ellis added 2 commits November 3, 2025 09:42

responding to ap2-demo PR comments

58418a9

remove ap2 local dependency and point to github repo

bc8d2da

lingzhong force-pushed the feature/ap2-demo branch from 201b71e to bc8d2da Compare November 3, 2025 17:42

chore: bump Python version requirement to >=3.13 for ap2-demo

33b2f89

lingzhong dismissed their stale review via 33b2f89 November 3, 2025 18:04

docs: update Python version requirement to 3.13+ in README

8183020

lingzhong previously approved these changes Nov 3, 2025

View reviewed changes

update readme docs

2a7d0bc

jorellis dismissed lingzhong’s stale review via 2a7d0bc November 4, 2025 00:21

Move hard coded wallet address to env variable

2b516f7

lingzhong previously approved these changes Nov 4, 2025

View reviewed changes

clean up comments

c908e3e

jorellis dismissed lingzhong’s stale review via c908e3e November 4, 2025 01:01

lingzhong approved these changes Nov 4, 2025

View reviewed changes

Merge branch 'main' into feature/ap2-demo

cb73d94

jorellis merged commit 46dd48b into main Nov 4, 2025
4 checks passed

jorellis deleted the feature/ap2-demo branch November 4, 2025 16:05

a2a-bot mentioned this pull request Nov 4, 2025

chore(main): release 0.2.0 #44

Open

	nonce="0x" + os.urandom(32).hex(), # Pass nonce as a hex string
	nonce=usdc_contract.functions.nonces(self._wallet_address).call().to_bytes(32, 'big'), # Fetch on-chain nonce

		current_temp_artifact = self._artifact_chunks[artifact.artifactId][-1]
		# TODO handle if current_temp_artifact is missing


		This directory contains a demonstration of the Agent Payments Protocol (AP2) integrated with the x402 payments extension. It showcases the "Embedded Flow," where a client agent orchestrates a purchase from a merchant agent using a sequence of digitally signed mandates.

		The demo consists of three main components:

feat: Adding example demo showing how the Intent, Cart and Payment mandates… #43

feat: Adding example demo showing how the Intent, Cart and Payment mandates… #43

Conversation

jorellis commented Oct 16, 2025

Description

Uh oh!

gemini-code-assist bot commented Oct 16, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lingzhong commented Oct 28, 2025

Uh oh!

lingzhong commented Oct 28, 2025

Uh oh!

lingzhong commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

lingzhong commented Oct 28, 2025 •

edited

Loading