x402-payment - SKILL.md Agent Skill

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

The script calls the target URL
If no 402 → returns the response directly (no payment needed)
If 402 → opens a browser page showing payment details (amount, token, chain)
User signs the payment in MetaMask
Script retries the URL with the signed payment header
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