feat: add Tutorial 08 — OpenClaw Agent with AgentCore Payments (zero-code)

[wirjo]

Summary

Adds Tutorial 08 for using AWS AgentCore Payments from OpenClaw with x402 v2. The tutorial installs the published @aws/aws-agents-pay package from ClawHub and keeps payment administration outside the model-facing runtime.

The tutorial does not carry a plugin source snapshot. The canonical package and bundled agents-pay skill are maintained in aws/agent-toolkit-for-aws.

Added an architecture diagram (converse-with-openclaw-agent/images/architecture_openclaw_agent.png) showing the human-operated admin path (IAM/session/spend-limit setup, dashed/out-of-band) versus the agent-facing runtime path (bounded ProcessPayment calls, no direct wallet access) — verified consistent with the README and the skill's security-model doc.

Install

openclaw plugins install clawhub:@aws%2Faws-agents-pay
openclaw plugins inspect aws-agents-pay

The runtime exposes exactly:

• get_payment_session_status
• get_paid_content

Validation

• Repository JavaScript lint: pass
• Repository Python lint: pass
• Repository scan: pass
• CodeQL JavaScript/TypeScript: pass
• CodeQL Python: pass
• Tutorial contains no duplicated plugin implementation or release artifact
• Architecture diagram checked against README + aws-agents-pay config schema (packages/openclaw/src/config.ts, openclaw.plugin.json) for human-vs-agent boundary accuracy

[wirjo]

✅ End-to-End Validation Complete

Successfully tested the full x402 payment flow on a live OpenClaw instance:

1️⃣ Probe URL → HTTP 402 + x402 v2 challenge
2️⃣ AgentCore ProcessPayment → EIP-3009 transferWithAuthorization signature ✅
3️⃣ validAfter check → EVM clock-skew prevention ✅
4️⃣ Replay with Payment-Signature header (base64 PaymentPayload) → HTTP 200 ✅

Test endpoint: https://x402-test.genesisblock.ai/api/weather (Base Sepolia, /bin/bash.001 USDC)

Plugin source updated: wirjo/agentcore-x402-payments-for-openclaw@68d5e98 with key fixes for x402 v2 compliance:

• Proper PaymentPayload envelope per x402 v2 spec
• Payment-Signature header (not X-PAYMENT) for v2 endpoints
• userId in ProcessPayment/GetPaymentSession calls
• Structured challenge payload to AgentCore (not base64 string)
• OpenClaw execute() tool interface (not handler())

[wirjo]

Updated the README to address all review comments. Key changes:

• Wallet-agnostic: Added both Coinbase CDP (Option A) and Stripe/Privy (Option B) paths
• Spending controls: Added prominent best-practice section + approval guidance at session creation
• Standalone: No dependency on Tutorial 00 — covers full setup from scratch
• Production deployment: New section covering mainnet transition, supported networks table, and production checklist
• No personal repos: Removed all personal repository references

cc @royosherove for review

[mvangara10]

Please add AgentCore CLI command to create payment manager - or links

[wirjo]

@mvangara10 @peterjiang-dev — Updated this PR to include the full plugin source code alongside the tutorial.

What changed:

The tutorial now offers two installation paths:

1. Option A: Install from ClawHub (zero-code, recommended for end users)

   openclaw plugins install clawhub:@aws/openclaw-x402-payments

2. Option B: Build from source (for development, customization, or review)

   cd plugin && npm install && npm run build
   openclaw plugins install --link .

New plugin/ directory added:

plugin/
├── openclaw.plugin.json            # Runtime plugin manifest
├── package.json / tsconfig.json
├── src/
│   ├── index.ts                    # Tool registration entry point
│   ├── config.ts                   # Config management
│   ├── payments.ts                 # AgentCore Payments API integration
│   └── x402.ts                     # x402 protocol handling (v1 + v2)
└── skills/x402-payments/
    ├── SKILL.md                    # Agent-agnostic skill instructions
    └── references/
        ├── protocol.md             # x402 protocol details
        ├── setup.md                # Prerequisites + IAM setup
        └── debugging.md            # Common issues + diagnostics

This makes the tutorial fully self-contained — reviewers can inspect the complete implementation without needing an external repo.

The same source code has also been submitted to awslabs/agent-plugins#243 as the aws-agent-payments plugin for the official Agent Plugins for AWS collection.

[github-actions]

Latest scan for commit: 1671fdb | Updated: 2026-08-04 04:59:25 UTC

Security Scan Results

Scan Metadata

• Project: ASH
• Scan executed: 2026-08-04T04:51:32+00:00
• ASH version: 3.0.0

Summary

Scanner Results

The table below shows findings by scanner, with status based on severity thresholds and dependencies:

Column Explanations:

Severity Levels (S/C/H/M/L/I):

• Suppressed (S): Security findings that have been explicitly suppressed/ignored and don't affect the scanner's pass/fail status
• Critical (C): The most severe security vulnerabilities requiring immediate remediation (e.g., SQL injection, remote code execution)
• High (H): Serious security vulnerabilities that should be addressed promptly (e.g., authentication bypasses, privilege escalation)
• Medium (M): Moderate security risks that should be addressed in normal development cycles (e.g., weak encryption, input validation issues)
• Low (L): Minor security concerns with limited impact (e.g., information disclosure, weak recommendations)
• Info (I): Informational findings for awareness with minimal security risk (e.g., code quality suggestions, best practice recommendations)

Other Columns:

• Time: Duration taken by each scanner to complete its analysis
• Action: Total number of actionable findings at or above the configured severity threshold that require attention

Scanner Results:

• PASSED: Scanner found no security issues at or above the configured severity threshold - code is clean for this scanner
• FAILED: Scanner found security vulnerabilities at or above the threshold that require attention and remediation
• MISSING: Scanner could not run because required dependencies/tools are not installed or available
• SKIPPED: Scanner was intentionally disabled or excluded from this scan
• ERROR: Scanner encountered an execution error and could not complete successfully

Severity Thresholds (Thresh Column):

• CRITICAL: Only Critical severity findings cause scanner to fail
• HIGH: High and Critical severity findings cause scanner to fail
• MEDIUM (MED): Medium, High, and Critical severity findings cause scanner to fail
• LOW: Low, Medium, High, and Critical severity findings cause scanner to fail
• ALL: Any finding of any severity level causes scanner to fail

Threshold Source: Values in parentheses indicate where the threshold is configured:

• (g) = global: Set in the global_settings section of ASH configuration
• (c) = config: Set in the individual scanner configuration section
• (s) = scanner: Default threshold built into the scanner itself

Statistics calculation:

• All statistics are calculated from the final aggregated SARIF report
• Suppressed findings are counted separately and do not contribute to actionable findings
• Scanner status is determined by comparing actionable findings to the threshold

Scanner	S	C	H	M	L	I	Time	Action	Result	Thresh
bandit	0	0	0	0	0	0	342ms	0	PASSED	MED (g)
cdk-nag	0	0	0	0	0	0	7.7s	0	PASSED	MED (g)
cfn-nag	0	0	0	0	0	0	221ms	0	PASSED	MED (g)
checkov	0	0	0	0	0	0	7.0s	0	PASSED	MED (g)
detect-secrets	0	0	0	0	0	0	1.0s	0	PASSED	MED (g)
grype	0	0	0	0	0	0	57.4s	0	PASSED	MED (g)
npm-audit	0	0	0	0	0	0	1.5s	0	PASSED	MED (g)
opengrep	0	0	0	0	0	0	<1ms	0	SKIPPED	MED (g)
semgrep	0	0	0	0	0	0	<1ms	0	MISSING	MED (g)
syft	0	0	0	0	0	0	2.3s	0	PASSED	MED (g)

[wirjo]

Addressing all @mvangara10 feedback

Q: "Include both Privy and CDP, be wallet agnostic"

A: Done — the tutorial has had both paths since the 3rd revision:

• Option A: Coinbase CDP (Step 2, full walkthrough)
• Option B: Stripe/Privy (Step 2, full walkthrough)

The README and plugin are wallet-agnostic by design.

---

Q: "Add AgentCore CLI command to create payment manager"

A: Done — Prerequisites now includes the aws iam create-role command and links to AgentCore Payments IAM setup. The plugin auto-creates the payment manager using the IAM role ARN provided during setup.

---

Q: "Clean up this PR with everything that is already in the docs and add relevant docs link"

A: Added canonical source links to the top of each reference file (commit 5d53837):

• protocol.md → links to x402 Specification v2
• setup.md → links to AgentCore Payments Getting Started, IAM Roles, Regions
• debugging.md → links to AgentCore Payments Troubleshooting

Why we keep the reference files: These are not human documentation — they are agent-optimized extracts used at runtime by the AI agent. The skill system (SKILL.md + references/) follows the AgentSkills progressive disclosure pattern: SKILL.md loads first (~5KB), references load on-demand only when the agent encounters a specific situation. Replacing them with raw doc URLs would require the agent to fetch and parse full documentation pages at runtime, degrading performance and reliability.

---

Q: "Is that a part of openclaw skill?"

A: Yes. The plugin/skills/x402-payments/ directory follows the OpenClaw skill format:

• SKILL.md — agent instructions (loaded on activation)
• references/ — supplementary context (loaded on-demand)

This is the standard structure for OpenClaw plugins that include agent guidance alongside executable tools. It is published as-is to ClawHub.

---

Q: "The folder does not have the sample? Can we consolidate the sample that uses this skill?"

A: This tutorial is intentionally conversational/zero-code — unlike the other tutorials (00–07) which are Python scripts, this one demonstrates installing a plugin and using it through natural language conversation. The "sample" is the conversation flow documented in the README (Steps 2–6), and the plugin/ directory contains the full source code.

The folder structure is:

08-openclaw-payments-plugin/
├── README.md          ← The tutorial (conversational walkthrough)
└── plugin/            ← Full plugin source (runnable via "openclaw plugins install --link .")

There is no separate Python script because the entire point is zero-code operation through an installed plugin.

[wirjo]

Addressed: Folder rename + skill naming + consistency

Changes (commit 40e11a3):

Q: Folder naming consistency with other tutorials
A: Renamed to 08-openclaw-agent-with-agentcore-payments — follows the repo pattern of describing an agent + capability (like 05-agent-with-browser-tool-pay-for-content).

Q: Skill name should be generic
A: Renamed skill from x402-payments → agentcore-payments. The directory is now plugin/skills/agentcore-payments/ and the SKILL.md name: field is agentcore-payments. This is generic despite being an internal OpenClaw skill name — it describes the capability (AgentCore Payments) rather than the protocol (x402).

Note: "x402" still appears in protocol descriptions, tool names (setup_x402_payments), and code filenames (x402.ts) because that is the actual protocol name — similar to how you'd reference "OAuth" or "SAML" in tool implementations.

Q: "08 folder will have the tutorial of a sample openclaw agent with agentcore payments which uses/maps to the openclaw skill within the folder"
A: Exactly right. The structure is now:

08-openclaw-agent-with-agentcore-payments/
├── README.md                              ← Tutorial (sample agent walkthrough)
└── plugin/
    ├── skills/agentcore-payments/         ← The skill the agent uses
    │   ├── SKILL.md
    │   └── references/
    ├── src/                               ← Runtime implementation
    └── openclaw.plugin.json               ← Plugin manifest

The README explicitly notes: "This tutorial uses the agentcore-payments skill included in the plugin/ directory."

[mvangara10]

@peterjiang-dev

[wirjo]

Updated the tutorial README:

• IAM roles: Use canonical ManagementRole / ProcessPaymentRole naming with explicit separation rules (cannot combine both; runtime must exclude CreatePaymentSession)
• Skill link: Reworded to describe what the bundled agents-pay skill contains (operator guide, IAM reference, security model, troubleshooting, admin CLI)
• Removed stale note: "encoded slash" sentence no longer applies after fixing install command to use plain /
• Credentials warning: Expanded to include admin CLI output and deployed state
• Config-file section: Replaced inline ~/.x402/config.json paragraph with pointer to the skill's operator guide to avoid maintaining two sources

[wirjo]

Restructured this tutorial to fit alongside the paths added in 01-payments-skills-and-cli/ since this PR opened:

• Removed the standalone 00-getting-started/08-openclaw-agent-with-agentcore-payments/ tutorial.
• Added 01-payments-skills-and-cli/converse-with-openclaw-agent/ — a trimmed OpenClaw-specific path (install command, openclaw.json config, chat-driven validation flow, OpenClaw-specific troubleshooting), linking out to the aws-agents-pay skill's operator-guide/security-model docs instead of duplicating them.
• Added a third row to the parent README's "Choose your path" table for this no-coding-assistant path, and reworded the intro so it doesn't imply all three paths need a coding assistant.
• Rebased onto current main.
• Added a troubleshooting row covering the region-resolution fix in fix(agents-pay): resolve region and manager ARN from config, fix runtime region fallback and session-token env bypass aws/agent-toolkit-for-aws#236 (config.json's region must match the payment manager's actual deployment region; no silent us-west-2 fallback).

[wirjo]

@peterjiang-dev — architecture diagram is now added to the converse-with-openclaw-agent tutorial (images/architecture_openclaw_agent.png, commit 1e3ca69d).

Reviewed the README against the human-operated vs. agent-facing boundary you've flagged in past comments on this PR:

Diagram ↔ text: consistent

• Diagram shows the human operator connected to AgentCore Payments only via a dashed (out-of-band) line for IAM/session/spend-limit setup — matches the README's "Payment infrastructure ... must already exist -- provisioned through ... the human-only admin CLI" and the linked security-model doc.
• Runtime tool surface in the diagram ("Bounded payment processing") matches the README's explicit allowlist: only get_payment_session_status and get_paid_content, with "must not expose setup, session-creation, or raw-proof tools."
• Signing/settlement is drawn strictly between AgentCore and the wallet, never touching the agent directly — matches "Analyse paid content only through a separate component that has neither payment authority nor network access."

Up to date

• Naming is consistent post-rename (aws-agents plugin / aws-agents-pay package / agents-pay skill).
• The encoded-slash install command issue is gone (plain / now).
• The region-mismatch troubleshooting row from agent-toolkit-for-aws#236 is present.

Config casing checked against the actual plugin schema: confirmed payment_session_id is intentionally snake_case in the real aws-agents-pay schema (packages/openclaw/src/config.ts X402Config + openclaw.plugin.json configSchema in aws/agent-toolkit-for-aws) — it's the one field defined that way, required as-is, while every other field is camelCase. The tutorial's example config matches this exactly, so no change needed there.

Net: boundary story holds up and the doc looks current.

[wirjo]

@peterjiang-dev @mvangara10 — pushed changes addressing the review feedback (commit 2fe636a7):

• Region: flagged region as required with no default; called out us-east-1 in the example as a placeholder, not a fixed value
• Recipient policy: documented allowAnyRecipient: true as a mutually-exclusive alternative to allowedRecipients for broader discovery scenarios
• Per-payment ceiling vs. session budget: clarified maxPaymentAmountAtomic is the per-payment cap, distinct from the session's cumulative budget
• Tool descriptions: spelled out what get_payment_session_status and get_paid_content each do, not just their names
• Identifiers: clarified package (@aws/aws-agents-pay) vs. plugin ID (aws-agents-pay) vs. skill name (agents-pay)
• Setup UX: added the conversational entry point ("Help me set up the agents-pay skill") alongside the manual install command
• returnBody: explained the tradeoff — metadata-only by default (safer), vs. opt-in body return with prompt-injection risk noted
• Troubleshooting: added a row for the allowedRecipients/allowAnyRecipient conflict error
• Blog link: added the companion AWS blog post to References
• Parent README Resources: distinguished agents-build (source of truth for the two coding-assistant paths) from agents-pay (source of truth for this OpenClaw path) — they cover different scopes and both should be linked

Ready for another look.