x402-payment

name	x402-payment
description	Pay x402-compatible URLs by opening a local browser page for MetaMask signing. Use when a URL returns HTTP 402 or when you know a URL requires 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

Argument	Default	Description
url	(required)	The x402-compatible URL to call
--method	GET	HTTP method
--body	none	Request body as JSON string
--headers	none	Additional HTTP headers as JSON string
--timeout	120	Seconds to wait for MetaMask signing
--port	18402	Preferred port for the local signing server
--network	none	Filter payment options by network (e.g. eip155:84532 for Base Sepolia)
--cheapest	off	Auto-select the cheapest standard payment option (excludes batched/gateway schemes)

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