AgentSkillsCN

x402

为 HTTP API 与 MCP 工具实现并调试 x402 v2 支付流程。适用于涉及 402 Payment Required 处理、PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE 头部、x402 MCP _meta 键（x402/payment、x402/payment-response）、Rust x402-rs crate（x402-axum/x402-reqwest/x402-types）、促进者验证/结算流程、CAIP-2 网络 ID，或从 x402 v1 头部迁移相关任务时使用。

SKILL.md
--- frontmatter
name: x402
description: "Implement and debug x402 v2 payment flows for HTTP APIs and MCP tools. Use when tasks involve 402 Payment Required handling, PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE headers, x402 MCP _meta keys (x402/payment, x402/payment-response), Rust x402-rs crates (x402-axum/x402-reqwest/x402-types), facilitator verify/settle flows, CAIP-2 network IDs, or migration from x402 v1 headers."
license: MIT
metadata:
  author: lommaj
  version: "1.0.0"

Install

bash
npx skills add lommaj/x402-skill

x402

Implement x402 as a transport contract plus scheme wiring. Keep protocol shape exact, then layer business logic and agent approval policy.

Quick Workflow

  1. •Identify the transport, role, and stack.
  • •Rust HTTP server/client (axum, reqwest, x402-* crates): start with references/rust-playbook.md, then cross-check references/protocol-contract.md.
  • •TypeScript/Node HTTP or MCP: start with references/implementation-playbook.md, then cross-check references/protocol-contract.md.
  • •MCP always uses _meta and structured error flow from references/protocol-contract.md.
  1. •Lock the wire contract before adding app logic.
  • •Keep x402Version: 2.
  • •Keep required object shapes for PaymentRequired, PaymentPayload, and SettlementResponse.
  • •Keep network IDs in CAIP-2 format (example: eip155:84532).
  • •Treat header names as case-insensitive on read, but emit canonical v2 names on write.
  1. •Implement server-side payment boundary.
  • •Return payment required signal on unpaid requests.
  • •Verify payment.
  • •Execute protected work.
  • •Settle payment.
  • •Return resource with settlement proof.
  • •Choose settlement timing intentionally: settle before execution for strict prepay; settle after successful work for pay-on-success.
  1. •Implement client-side payment retry loop.
  • •Detect payment-required signal.
  • •Select accepted requirement.
  • •Create signed payment payload.
  • •Retry with payment attached.
  • •Read settlement response and surface receipt/tx id.
  • •For Rust clients, prefer x402-reqwest if available; otherwise implement manual retry loop.
  1. •Add agent safety policy.
  • •Default to explicit payment approval unless user asked for autopay.
  • •Enforce allowlist for networks/assets and max spend per call.
  • •Refuse unknown scheme/network pairs.
  1. •Validate end-to-end non-interactively.
  • •Exercise free and paid paths.
  • •Verify headers or _meta objects exactly.
  • •Confirm settlement response exists on success.

Transport Rules

HTTP v2

  • •Payment required signal: HTTP 402 + PAYMENT-REQUIRED (base64 JSON).
  • •Payment submission: PAYMENT-SIGNATURE (base64 JSON).
  • •Settlement confirmation: PAYMENT-RESPONSE (base64 JSON).

MCP v2

  • •Payment required signal: tool result with isError: true and payment data in both:
  • •structuredContent (object)
  • •content[0].text (JSON string)
  • •Payment submission: request _meta["x402/payment"].
  • •Settlement confirmation: response _meta["x402/payment-response"].

Implementation Notes

  • •Prefer official wrappers before custom protocol code:
  • •Rust server: x402-axum (X402Middleware, with_price_tag, with_dynamic_price, settle timing controls).
  • •Rust client: x402-reqwest (or manual retry if wrapper is unavailable).
  • •Rust protocol types: x402-types::proto::{v2::PaymentRequired, VerifyRequest, SettleRequest}.
  • •TS/HTTP: @x402/fetch, @x402/axios, @x402/express, @x402/hono, @x402/next.
  • •TS/MCP: @x402/mcp (createPaymentWrapper, createx402MCPClient).
  • •Register schemes explicitly for each network family you support.
  • •Use facilitator integration for verification/settlement unless you intentionally run local settlement.
  • •Warm facilitator capability data from /supported at startup when possible.

Common Failure Points

  • •Mixing v1 and v2 headers (X-PAYMENT* vs PAYMENT-*).
  • •Non-CAIP-2 network IDs.
  • •Returning only one MCP payment-required representation instead of both structuredContent and content[0].text.
  • •Dropping extensions fields when echoing from PaymentRequired to PaymentPayload.
  • •Not matching PaymentPayload.accepted exactly to one offered accepts[] requirement before verify/settle.
  • •Assuming only one settlement header spelling in mixed environments (support read fallback where needed).
  • •Treating probe calls as side-effect free in MCP (probing can execute free tools).

Debugging Utilities

  • •Use scripts/inspect_x402.py for quick decode and inspection:
bash
python scripts/inspect_x402.py decode --value "$PAYMENT_REQUIRED_B64" --expect payment-required
python scripts/inspect_x402.py inspect-mcp --file mcp-result.json
python scripts/inspect_x402.py inspect-http --file http-exchange.json

References

  • •Use references/protocol-contract.md for required field-level protocol shape.
  • •Use references/rust-playbook.md for Rust x402-rs implementation patterns.
  • •Use references/implementation-playbook.md for practical TypeScript/Node + MCP implementation patterns.
  • •Use references/migration-v1-to-v2.md when touching legacy integrations.
  • •Use references/source-map.md to jump to canonical spec and SDK source files.