second-state/x402-skill/x402

x402 Payment Skill

When an HTTP request returns 402 Payment Required with x402 payment info, automatically retry using x402curl.

Detection

Only activate when all of the following are true:

• HTTP status code is 402
• At least one of:
• Response contains an X-Payment header
• Response body contains "x402Version" in JSON

If a 402 response lacks these markers, inform the user it requires payment but do not retry — it is not an x402 endpoint.

Workflow

Step 1: Inform the user (one line):

This endpoint requires payment via x402. Retrying with x402curl...

Step 2: Transform the original curl command into an x402curl command.

Replace curl with {baseDir}/scripts/x402curl and adjust flags:

Preserve these flags as-is: -X, -H, -d, --data, --data-binary, -o, -F, -u, -L, -f

Drop these flags (x402curl manages its own output): -v, --verbose, -s, --silent

# Original
curl -X POST -s https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'
 
# Transformed
{baseDir}/scripts/x402curl -X POST https://api.example.com/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Step 3: Execute and return the result. On success, show the response without mentioning payment again.

Error Handling

Map x402curl exit codes to user-friendly messages:

Balance Check

When a user asks to check their wallet balance:

Step 1: Run with defaults (Base mainnet USDC):

{baseDir}/scripts/x402curl --x402-balance

Step 2: Show the result to the user.

Step 3: Ask: "Would you like to check a balance on a different network or token?"

If yes, ask for the RPC URL and token contract address. Then run:

{baseDir}/scripts/x402curl --x402-balance --x402-rpc-url <url> --x402-token <address>

Examples

Simple GET

# 1. Original request returns 402
curl https://paid-api.example.com/data
# → 402 with X-Payment header
 
# 2. Retry with x402curl
{baseDir}/scripts/x402curl https://paid-api.example.com/data
# → 200 with data

POST with JSON body

# 1. Original
curl -X POST https://translate.example.com/v1 \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target": "es"}'
# → 402 with x402Version in body
 
# 2. Retry
{baseDir}/scripts/x402curl -X POST https://translate.example.com/v1 \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "target": "es"}'
# → 200 with translation

File upload

# 1. Original
curl -X POST https://ocr.example.com/extract -F "file=@document.pdf"
# → 402
 
# 2. Retry
{baseDir}/scripts/x402curl -X POST https://ocr.example.com/extract \
  -F "file=@document.pdf"

Output to file

# 1. Original
curl -o result.json https://paid-api.example.com/report
# → 402
 
# 2. Retry
{baseDir}/scripts/x402curl -o result.json https://paid-api.example.com/report