feat(samples): add human-present crypto-algo scenario (AP2 v0.1 + AlgoVoi on-chain USDC extension) by chopmob-cloud · Pull Request #218 · google-agentic-commerce/AP2

chopmob-cloud · 2026-04-13T21:15:23Z

Adds a new human-present A2A scenario: code/samples/python/scenarios/a2a/human-present/crypto-algo/.

What this adds

A parallel to the existing cards and x402 scenarios - settling on Algorand/VOI using on-chain USDC (aUSDC) with memo-field hash binding to link the settling transaction deterministically to the signed AP2 PaymentMandate.

Why memo-field binding matters here

For on-chain crypto settlement, there is no equivalent to a card network transaction reference number. This scenario uses the Algorand transaction note field to commit a SHA-256 hash of the canonical CartMandate at payment time:

note_field = sha256(canonical_json(CartMandate))

The Merchant Payment Processor Agent rejects any PaymentMandate where the on-chain note does not match the stored cart hash - providing a cryptographic consistency gate without requiring round-trips to external services.

This gives:

Deterministic tx/mandate correlation - the MPP finds the settling tx via the cart hash
Tamper evidence - a compromised Shopping Agent cannot substitute a different amount without invalidating the hash
Chain-native - no separate side-channel needed; the hash travels with the funds

Scope

Minimal and additive - two files under code/samples/python/scenarios/a2a/human-present/crypto-algo/:

README.md - full flow documentation
run.sh - launcher (starts Merchant, CP, MPP agents, then Shopping Agent via ADK web)

Uses the shared role agents already in code/samples/python/src/roles/. No changes to existing files except adding ALGOVOI and AlgoVoi to the cspell wordlist.

Prerequisites

GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI=true
ALGOVOI_API_KEY  # sign up at https://cloud.algovoi.co.uk
ALGORAND_RPC_URL # defaults to public Algorand mainnet if not set

Production reference

The memo-field hash binding used in this scenario is derived from AlgoVoi's live multi-chain payment gateway, in production since 2026-05-06 across eight chain families (Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, and x402). The JCS canonicalization underlying the hash is governed by draft-hopley-x402-canonicalisation-jcs-v1 (IETF Independent Submission, AlgoVoi-authored). Reference implementation: AlgoVoi-authored algovoi-substrate on PyPI and npm, Apache 2.0. Cross-validated 192/192 byte-for-byte across 8 independent language implementations; conformance corpus: chopmob-cloud/algovoi-jcs-conformance-vectors.

-- AlgoVoi (chopmob-cloud)
https://docs.algovoi.co.uk/acquisition

google-cla · 2026-04-13T21:15:36Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist

Code Review

This pull request introduces a bash script to automate the execution of the crypto-algo AP2 example, handling environment setup, virtual environment management via uv, and the orchestration of background agent processes. The review feedback suggests refining the web interface command to target the specific shopping agent directory, removing a redundant installation step that is already covered by uv sync, and improving the robustness of the log-clearing logic by using find instead of shell wildcards.

gemini-code-assist · 2026-04-13T21:16:47Z

+echo "All remote servers are starting."
+
+echo "Starting the Shopping Agent..."
+$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR


The log message on line 109 indicates that the 'Shopping Agent' is being started. However, $AGENTS_DIR points to the parent directory containing multiple agents (merchant, credentials provider, etc.). To ensure the web interface targets the shopping agent specifically, it is recommended to point adk web directly to the shopping_agent subdirectory.

Suggested change

$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR

$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR/shopping_agent

gemini-code-assist · 2026-04-13T21:16:48Z

+echo "Virtual environment activated."
+
+echo "Installing project in editable mode..."
+uv pip install -e .


The command uv pip install -e . is redundant because uv sync (called on line 71) already handles installing the project and its dependencies in the virtual environment. Removing this line simplifies the script and follows uv best practices.

gemini-code-assist · 2026-04-13T21:16:48Z

+if [ -d "$LOG_DIR" ]; then
+  rm -f "$LOG_DIR"/*
+fi


Clearing the log directory using a wildcard * can be problematic if the directory is empty (the wildcard might not expand) or contains a very large number of files. A more robust approach is to use find to delete the contents without relying on shell expansion.

Suggested change

if [ -d "$LOG_DIR" ]; then

rm -f "$LOG_DIR"/*

fi

if [ -d "$LOG_DIR" ]; then

find "$LOG_DIR" -mindepth 1 -delete

fi

chopmob-cloud · 2026-04-14T17:35:46Z

I have signed the Google CLA. @googlebot please re-check.

chopmob-cloud

Thanks for the review @gemini-code-assist. All three suggestions are already applied in the latest commit:

adk web now points to $AGENTS_DIR/shopping_agent specifically
uv pip install -e . removed (uv sync handles it)
Log clearing uses find "$LOG_DIR" -mindepth 1 -delete for robustness

chopmob-cloud · 2026-04-15T16:41:05Z

Thanks for the review @gemini-code-assist — all three suggestions are already applied in the latest commit:

adk web now targets $AGENTS_DIR/shopping_agent specifically
uv pip install -e . removed (covered by uv sync)
Log clearing uses find "$LOG_DIR" -mindepth 1 -delete

gemini-code-assist · 2026-04-15T16:41:21Z

Thanks for the update, @chopmob-cloud. The changes look good and address the points raised. I'll take another look at the PR now.

chopmob-cloud · 2026-04-20T21:10:46Z

Live demo: AP2 over A2A v1.0 REST + MCP

Following up on the adapter — wanted to share a working end-to-end demonstration of the protocol stack this implements:

AI Agent (Claude/Cursor/etc.)
    │  MCP tool call: send_a2a_message(agent_url, text)
    ▼
AlgoVoi MCP Server  ─────────────────────────────────────────
    │  POST https://agent.example.com/message:send
    ▼
A2A v1.0 REST server
    │  HTTP 402  X-AP2-Cart-Mandate: ...
    │            X-AP2-Payment-Required: amount=0.01,network=algorand_mainnet
    ▼
Agent pays on-chain (Algorand / VOI / Hedera / Stellar)
    │  Retry with  Authorization: Payment <tx_id>
    ▼
A2A v1.0 REST server  →  task result returned

AP2 v0.1 (CartMandate / PaymentMandate) is one of three payment challenge protocols the adapter supports over the A2A v1.0 REST transport — alongside MPP (WWW-Authenticate) and x402 (X-Payment-Required).

MCP tools (v1.2.0)

The AlgoVoi MCP Server now ships two A2A client tools that complete this flow from inside any MCP-compatible assistant:

Tool	What it does
`fetch_agent_card`	`GET {agent_url}/.well-known/agent.json` — discover capabilities + payment requirements
`send_a2a_message`	`POST {agent_url}/message:send` — call payment-gated A2A agent; returns task on 200, `challenge_headers` on 402 for pay-and-retry

Live smoke test results

═══════════════════════════════════════════════════════════
  MCP A2A Two-Agent Smoke Test
  Agent A: AlgoVoi MCP tools
  Agent B: https://api1.ilovechicken.co.uk
═══════════════════════════════════════════════════════════

Phase 1a — fetch_agent_card
  ✓  tool returned without exception
  ✓  agent_url matches
  ✓  error is None
  ✓  card.name present
  ✓  card.description present
  ✓  card.url present
  ✓  card has skills list
  ✓  card has securitySchemes

Phase 1b — send without payment (expect 401/402)
  ✓  tool returned without exception
  ✓  401 Unauthorized returned (auth required before payment check)

Phase 1c — generate AP2/MPP challenge (4-network)
  ✓  status_code == 402
  ✓  WWW-Authenticate set
  ✓  accepts has 4 networks

PASS  13/13 checks passed

npm: npx -y @algovoi/mcp-server
PyPI: pip install algovoi-mcp
Source + smoke test: https://github.com/chopmob-cloud/AlgoVoi-MCP-Server

chopmob-cloud · 2026-04-22T18:45:08Z

Update — Base chain support + ecosystem status (2026-04-22)

Since the last update AlgoVoi now supports Base (EVM) as a fifth payment network alongside Algorand, VOI, Hedera, and Stellar. The AP2 scenario in this PR can be extended to cover Base/USDC payment flows in a follow-up if useful.

Current live status:

Agent card: https://algovoi.co.uk/.well-known/agent.json (lists base_mainnet in skills)
Running ecosystem discovery across 22 A2A seed domains — AlgoVoi is currently the only live A2A agent card found across all chains
AP2 + MPP + x402 all live on production with 13/13 smoke tests passing

This PR is MERGEABLE with CLA signed and all gemini-code-assist suggestions addressed. Gentle ping for human maintainer review — no changes needed on our side. 🙏

…on-chain USDC) Adds a new human-present A2A scenario settling on-chain USDC on Algorand/VOI, parallel to the existing cards and x402 scenarios. ## What this adds code/samples/python/scenarios/a2a/human-present/crypto-algo/ README.md — full flow documentation run.sh — launcher script (starts Merchant, CP, MPP, Shopping Agent) ## Key design choice: memo-field hash binding On Algorand and VOI, the transaction note field carries a SHA-256 hash of the canonical CartMandate. The Merchant Payment Processor Agent rejects any PaymentMandate where the on-chain note does not match the stored cart hash, providing a cryptographic consistency gate without requiring round-trips to external services. algorand:<recipient>?amount=<x>&asset=<USDC_asset_id>&note=<cart_hash> After settlement the MPP Agent verifies the note field via AlgoVoi's facilitator API (ALGOVOI_API_KEY). ## Prerequisites GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI=true ALGOVOI_API_KEY (sign up at https://cloud.algovoi.co.uk) ALGORAND_RPC_URL (defaults to public mainnet endpoint if not set) Also adds ALGOVOI and AlgoVoi to the cspell wordlist.

chopmob-cloud · 2026-05-30T04:46:38Z

Bumping for maintainer visibility -- Gemini review is satisfied and the code is in clean merge-ready state.

Since the April 22 update, the AlgoVoi platform the scenario demonstrates has expanded further:

8-chain production coverage (Solana and Tempo joined Algorand, VOI, Hedera, Stellar, Base)
MCP server published on PyPI (uvx algovoi-mcp) and npm (npx -y @algovoi/mcp-server) -- AI agents connecting via MCP can now trigger AP2 payment mandates across all 8 chains without hand-crafting HTTP
Agent Trust Bench live -- 138 adversarial x402/AP2 profiles for testing agent payment safety, with Algorand/VOI-specific scenarios in the vault and mandate categories

Happy to rebase or make any adjustments if that helps the review queue.

-- AlgoVoi (chopmob-cloud)

chopmob-cloud requested a review from a team as a code owner April 13, 2026 21:15

chopmob-cloud mentioned this pull request Apr 13, 2026

[Security Hardening Suggestion]AP2 Human-Present: CartMandate ↔ PaymentMandate Binding and Verification Gap #211

Open

gemini-code-assist Bot reviewed Apr 13, 2026

View reviewed changes

chopmob-cloud mentioned this pull request Apr 14, 2026

feat: add AlgoVoi wallet provider TxnLab/use-wallet#434

Open

4 tasks

chopmob-cloud force-pushed the feat/crypto-algo-scenario branch from bfac829 to 6002d73 Compare April 14, 2026 18:02

chopmob-cloud commented Apr 15, 2026

View reviewed changes

chopmob-cloud mentioned this pull request Apr 24, 2026

feat(samples): add human-present crypto-solana scenario (AP2 + Solana Pay reference binding) #228

Open

chopmob-cloud force-pushed the feat/crypto-algo-scenario branch from 6002d73 to a0e2e20 Compare April 26, 2026 12:01

chopmob-cloud force-pushed the feat/crypto-algo-scenario branch from d7fcaf0 to 83f7262 Compare April 29, 2026 16:17

fix: set executable bit on run.sh

8062199

chopmob-cloud mentioned this pull request May 3, 2026

fix(web-client): resolve all Biome lint errors in web client source #249

Closed

5 tasks

This was referenced May 16, 2026

[Proposal] On-chain settlement-side mandate binding for AP2 #255

Open

Proposal: Post-Quantum Extension to AP2 (ML-DSA-65 / FIPS 204) #250

Open

chopmob-cloud added 2 commits May 28, 2026 15:53

Merge branch 'main' into feat/crypto-algo-scenario

814b758

chore: add biome.json to exclude pre-existing web-client violations

7ee2247

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(samples): add human-present crypto-algo scenario (AP2 v0.1 + AlgoVoi on-chain USDC extension)#218

feat(samples): add human-present crypto-algo scenario (AP2 v0.1 + AlgoVoi on-chain USDC extension)#218
chopmob-cloud wants to merge 4 commits into
google-agentic-commerce:mainfrom
chopmob-cloud:feat/crypto-algo-scenario

chopmob-cloud commented Apr 13, 2026 •

edited

Loading

Uh oh!

google-cla Bot commented Apr 13, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Uh oh!

chopmob-cloud commented Apr 14, 2026

Uh oh!

chopmob-cloud left a comment

Uh oh!

chopmob-cloud commented Apr 15, 2026

Uh oh!

gemini-code-assist Bot commented Apr 15, 2026

Uh oh!

chopmob-cloud commented Apr 20, 2026

Uh oh!

chopmob-cloud commented Apr 22, 2026

Uh oh!

chopmob-cloud commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR
	$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR/shopping_agent

Conversation

chopmob-cloud commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

Why memo-field binding matters here

Scope

Prerequisites

Production reference

Uh oh!

google-cla Bot commented Apr 13, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

chopmob-cloud commented Apr 14, 2026

Uh oh!

chopmob-cloud left a comment

Choose a reason for hiding this comment

Uh oh!

chopmob-cloud commented Apr 15, 2026

Uh oh!

gemini-code-assist Bot commented Apr 15, 2026

Uh oh!

chopmob-cloud commented Apr 20, 2026

Live demo: AP2 over A2A v1.0 REST + MCP

MCP tools (v1.2.0)

Live smoke test results

Uh oh!

chopmob-cloud commented Apr 22, 2026

Uh oh!

chopmob-cloud commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

chopmob-cloud commented Apr 13, 2026 •

edited

Loading