AP2 Checkout (mock)#

Drive the AP2 unified demo purchase flow via mcporter against local mock MCP servers (merchant, buyer, credentials provider, MPP). All settlement is simulated.

One-command install (recommended for demo)#

From your AP2 clone (installs skill, patches OpenClaw, starts mock backend):

bash

cd "$AP2_HOME"
npx -y file:code/samples/python/scenarios/a2a/unified/clawhub/npm/ap2-agent-checkout install

Then restart the OpenClaw gateway. Manual steps below are only needed if you skip the installer.

First-time setup (manual)#

1. Clone AP2 and set AP2_HOME to the repository root (the folder that contains code/):

bash

export AP2_HOME="/path/to/AP2"

1. Start the mock backend (triggers 8091–8094, MCP HTTP 8100–8103):

bash

cd "$AP2_HOME/code/samples/python/scenarios/a2a/unified"
chmod +x openclaw/start_ap2_backend.sh openclaw/stop_ap2_backend.sh
./openclaw/start_ap2_backend.sh

1. Point mcporter at this skill's mcporter.json (after ClawHub install, use the skill directory):

bash

# After clawhub install (adjust if your skills dir differs):
export MCPORTER_CONFIG="$HOME/.openclaw/workspace/skills/ap2-checkout/mcporter.json"

1. Enable skills in ~/.openclaw/openclaw.json: mcporter and ap2-checkout → enabled: true. Restart the gateway.

2. Verify (optional): run scripts/check-backend.sh from this skill folder with AP2_HOME set.

See references/setup.md for ports and troubleshooting.

Session identity#

Use a stable session_id per chat (Feishu channel + peer id, or any unique string). Pass it to every ap2-buyer.* tool.

bash

mcporter list ap2-buyer --schema
mcporter list ap2-merchant --schema

Mode selection (always first)#

User intentpresence_modepayment_methodDrop / monitor / buy when price dropshnp``card or x402 if user says cryptoBuy now / in stock todayhp``card or x402 if user says sobash

mcporter call ap2-buyer.set_ap2_session_config_tool \
  session_id=CHAT_ID presence_mode=hnp payment_method=card merchant=shoe
mcporter call ap2-buyer.get_ap2_session_config_tool session_id=CHAT_ID

Follow merchant_instruction from get_ap2_session_config.

Trusted Surface (user approval)#

Before signing mandates, show a clear summary (item, price cap, payment rail). Wait for explicit yes / approve / 确认.

bash

mcporter call ap2-buyer.register_trusted_surface_approval \
  session_id=CHAT_ID price_cap=200 payment_method=card \
  item_id=supershoe_limited_edition_gold_sneaker_womens_9_0

Plain-text budget or "pay by card" alone is not approval.

HNP flow (delegated drop)#

1. Set config → hnp + card or x402.
2. Build item_id as <slug>_0 (lowercase, non-alphanumeric → _). Do not call search_inventory for shoes.
3. mcporter call ap2-merchant.check_product item_id=... constraint_price_cap=200
4. Mandate summary → user approval → register_trusted_surface_approval.
5. Sign mandates — mandate_request must be a JSON string inside --args:

bash

mcporter call ap2-buyer.assemble_and_sign_mandates --args '{
  "session_id": "CHAT_ID",
  "mandate_request": "{\"item_id\":\"...\",\"price_cap\":200,\"qty\":1}"
}'

1. Poll: mcporter call ap2-buyer.check_constraints session_id=CHAT_ID price=299 available=false
2. If stock 0, user runs (replace ITEM_ID and PRICE from tool results):

bash

curl -X POST "http://127.0.0.1:8091/trigger-price-drop?item_id=ITEM_ID&price=199&stock=10"

1. When meets_constraints is true: assemble_cart → create_checkout → payment/checkout presentations → issue_payment_credential ( presence_mode=hnp) → complete_checkout → verify_checkout_receipt_tool. Emit purchase_complete JSON and stop.

HP flow (buy now)#

1. Set config → hp + card or x402.
2. search_inventory or check_product → assemble_cart.
3. Once: create_hp_open_mandates (no checkout_jwt yet).
4. create_checkout with open_checkout_mandate_id and payment_method.
5. Checkout summary → user 确认 → register_trusted_surface_approval.
6. assemble_and_sign_immediate_mandates with checkout_jwt, checkout_jwt_hash, amount_cents, etc.
7. issue_payment_credential ( presence_mode=hp) → complete_checkout → purchase_complete.

Never call create_hp_open_mandates twice per purchase. Never re-run assemble_cart / create_checkout after user confirmed.

Payment rail switch#

set_ap2_session_config_tool with new payment_method → clear_open_mandate_session_tool → re-approve → sign again.

Stop backend#

bash

cd "$AP2_HOME/code/samples/python/scenarios/a2a/unified" && ./openclaw/stop_ap2_backend.sh