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

Human-present crypto-algo scenario (Algorand USDC settlement)

Adds a human-present A2A scenario that settles on-chain USDC on Algorand, parallel to the existing cards and x402 scenarios and complementary to the sibling crypto-solana scenario.

What this PR contains

README.md: full flow documentation for the Algorand variant. It covers the note-field binding (av:{token[:20]}), the ARC-26 payment URI, USDC ASA settlement, and the Merchant Payment Processor rejection behavior when the on-chain note or asset/amount/recipient do not match the signed PaymentMandate.
run.sh: launcher that starts the Merchant, Credentials Provider, Merchant Payment Processor, and Shopping agents with PAYMENT_METHOD=CRYPTO_ALGO.

Scope and honesty note

The bundled sample role code does not implement the CRYPTO_ALGO settlement path end to end. On-chain verification (fetching the transfer, checking the note binding, returning a PaymentReceipt) requires an external, Algorand-aware AP2 facilitator. The README documents the intended flow and binding contract so a facilitator can be plugged in, and presents AlgoVoi Cloud as one example facilitator rather than a required dependency. Configuring a facilitator credential is optional; without it the agents still start.

Hardening (aligned with the crypto-solana sibling)

.env is now sourced without overriding variables already set in the caller's environment, so an unrelated .env entry can no longer override the scenario's PAYMENT_METHOD.
The cleanup pids array is initialized before the EXIT trap is installed.
No per-scenario uv.lock is included (consistent with the sibling scenario).

Validation: bash -n clean, shellcheck clean apart from the pre-existing SC1091 source info shared with the sibling, cspell and markdownlint green against the repo linter configs.

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.

# Description Removing uv.lock

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)

Pin actions/checkout and super-linter to release hashes, add a least privilege permissions block, set persist-credentials false, and disable Biome lint (ESLint still covers JS/TS). Matches the configuration proven green on PR 310.

…cilitator The crypto-algo README was empty (content lost in a rebase). Restore full flow documentation modelled on the sibling crypto-solana scenario, adapted to Algorand: USDC ASA settlement, ARC-26 payment URI, and the av:<token> note field binding with Merchant Payment Processor rejection behavior. State honestly that the bundled sample role code does not implement the CRYPTO_ALGO settlement path end to end and that on-chain verification requires an external, Algorand-aware AP2 facilitator. Present AlgoVoi Cloud as one example facilitator rather than a required vendor, and drop signup and marketing links. Signed-off-by: AlgoVoi <chopmob@gmail.com>

…ator optional Backport the run.sh hardening from the sibling crypto-solana scenario and apply decision to neutralise vendor gating: - Source .env without overriding variables already set in the caller's environment. The previous 'set -a; source .env' let a .env entry override the scenario's exported PAYMENT_METHOD; the [[ -v VAR ]] guard loop fixes it. - Initialise the pids array before installing the EXIT trap so cleanup() is always safe to call, even on an early exit. - Remove the mandatory ALGOVOI_API_KEY gate. A facilitator credential is now optional; if unset the agents still start and an informational note explains that on-chain verification is a no-op until a facilitator is configured. Signed-off-by: AlgoVoi <chopmob@gmail.com>

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

chopmob-cloud and others added 2 commits April 29, 2026 17:29

fix: set executable bit on run.sh

642eacf

fix: remove uvlock (google-agentic-commerce#246)

27496c7

# Description Removing uv.lock

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

0a3a736

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

897b55c

chopmob-cloud force-pushed the feat/crypto-algo-scenario branch from 7ee2247 to 897b55c Compare August 4, 2026 07:26

chopmob-cloud added 3 commits August 4, 2026 08:38

Navigation Menu

Uh oh!

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 8 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!

2 participants

	$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

Uh oh!

Conversation

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

Uh oh!

Human-present crypto-algo scenario (Algorand USDC settlement)

What this PR contains

Scope and honesty note

Hardening (aligned with the crypto-solana sibling)

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!

2 participants

chopmob-cloud commented Apr 13, 2026 •

edited

Loading