second-state/x402/x402-payment

x402 Payment Skill

When you need to access a URL that requires x402 payment (HTTP 402 Payment Required), use this skill to handle the full payment flow. The script opens a temporary browser page for the user to sign the payment with MetaMask, then retries the request with the signed payment header.

When to Use

• A URL returns HTTP 402 Payment Required
• The user asks you to pay for / access an x402-gated resource
• The user provides a URL that you know requires x402 payment

How to Invoke

Run the payment script using Bash:

python3 SKILL_DIR/x402_pay.py <url> [--method METHOD] [--body '{"key":"value"}'] [--headers '{"Authorization":"Bearer xxx"}'] [--timeout 120]

Replace SKILL_DIR with the absolute path to this skill's directory.

Arguments

What Happens

1. The script calls the target URL
2. If no 402 → returns the response directly (no payment needed)
3. If 402 → opens a browser page showing payment details (amount, token, chain)
4. User signs the payment in MetaMask
5. Script retries the URL with the signed payment header
6. Returns the final API response

The user must have MetaMask installed in their browser with a funded wallet.

Reading the Output

The script outputs a single JSON line to stdout:

Success (payment completed)

{
  "success": true,
  "status_code": 200,
  "url": "https://api.example.com/endpoint",
  "body": "response from the paid API",
  "payment_header": "base64-encoded-payment"
}

Success (no payment needed)

{
  "success": true,
  "status_code": 200,
  "url": "https://api.example.com/endpoint",
  "body": "response body"
}

Failure

{
  "success": false,
  "error": "Payment signing timed out after 120 seconds",
  "url": "https://api.example.com/endpoint"
}

Error Scenarios

• Timeout: User did not complete signing within the timeout period
• User rejection: User clicked Reject in MetaMask (will show as timeout or error)
• API error after payment: success will be false, check status_code and body
• MetaMask not installed: Script will time out; stderr will note the browser was opened

Example

# Pay for an x402-gated API
python3 /path/to/skills/x402-payment/x402_pay.py https://api.example.com/paid-resource
 
# POST with body and custom headers
python3 /path/to/skills/x402-payment/x402_pay.py https://api.example.com/paid-resource \
  --method POST \
  --body '{"query": "hello"}' \
  --headers '{"X-Custom": "value"}'
 
# Pick the cheapest Base Sepolia option (useful when a service offers multiple tiers)
python3 /path/to/skills/x402-payment/x402_pay.py https://x402.quicknode.com/base-sepolia/ \
  --method POST \
  --body '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  --network "eip155:84532" --cheapest