Agent skill
ucp-ap2-mandates
Implement UCP AP2 Mandates extension — cryptographic payment mandates for fully autonomous agent commerce using SD-JWT credentials, merchant authorization signatures, and the Agent Payments Protocol. Use when building autonomous agent payment flows without human-in-the-loop.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ucp-ap2-mandates
SKILL.md
UCP AP2 Mandates Extension
Before writing code
Fetch live spec:
- Web-search
site:ucp.dev specification ap2-mandatesfor the extension schema - Fetch https://ucp.dev/2026-01-23/documentation/ucp-and-ap2/ for the conceptual relationship
- Web-search
site:ap2-protocol.orgfor the AP2 protocol specification
Conceptual Architecture
What AP2 Enables
AP2 (Agent Payments Protocol) enables fully autonomous agent commerce — the agent can authorize payments cryptographically without requiring real-time human approval for each transaction. The user pre-authorizes spending parameters, and the agent proves authorization via signed credentials.
Two Mandate Artifacts
-
Checkout Mandate (
ap2.checkout_mandate): An SD-JWT+kb (Selective Disclosure JWT with Key Binding) credential that proves the user authorized the agent to complete this specific checkout at these specific terms. -
Payment Mandate (
payment_data.token): A separate credential proving payment authorization, verified by the PSP (not the Business).
Merchant Authorization
Before the Platform generates mandates, the Business must sign the checkout terms:
- Format: JWS Detached Content (RFC 7515 Appendix F) —
<header>..<signature> - Canonicalization: JSON Canonicalization Scheme (RFC 8785)
- Algorithms: ES256, ES384, ES512 (elliptic curve)
The Business returns this merchant_authorization in the checkout response.
7-Step Flow
- Discovery — Business publishes AP2 support in capabilities
- Session Activation — Platform signals AP2 intent
- Business Signing — Business returns checkout +
merchant_authorization(JWS detached content) - Authorization Generation — Platform creates CheckoutMandate (SD-JWT-VC) + PaymentMandate
- Submission — Platform sends both mandates in the
complete_checkoutcall - Verification — Business verifies checkout mandate; PSP verifies payment mandate
- Confirmation — Order confirmed
Security Lock
Once AP2 is negotiated for a checkout session, a Security Lock is activated: neither party may revert to a standard (non-AP2) checkout flow for that session. This prevents downgrade attacks where a malicious actor could bypass the cryptographic mandate requirements by falling back to a simpler payment flow.
Error Codes
AP2-specific errors:
mandate_required— AP2 mandates needed but not providedagent_missing_key— Agent's signing key not foundmandate_invalid_signature— Signature verification failedmandate_expired— Mandate past validity windowmandate_scope_mismatch— Mandate doesn't match checkout termsmerchant_authorization_invalid— Business signature invalidmerchant_authorization_missing— Business didn't sign terms
Implementation Guidance
This is the most complex UCP extension. Before implementing:
- Understand SD-JWT-VC (Selective Disclosure JWT Verifiable Credentials) — this is the credential format
- Understand JWS Detached Content (RFC 7515 Appendix F) — this is the merchant signing format
- Understand JSON Canonicalization (RFC 8785) — deterministic JSON serialization for signing
- Fetch the latest AP2 protocol spec from https://ap2-protocol.org for the full mandate lifecycle
- Check the conformance test suite: https://github.com/Universal-Commerce-Protocol/conformance (ap2_test.py)
This extension is intended for advanced autonomous agent scenarios. Most initial implementations should start with standard payment handlers (Google Pay, Shop Pay) before adding AP2.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?