second-state/x402/x402-hub

x402 Hub Skill

An x402 Hub hosts a catalogue of paid APIs. Each listing has a /paid/<id> URL that returns HTTP 402 on first hit; paying unlocks the upstream response.

This skill covers discovery of listings on the hub. For the payment + call step, always delegate to the x402-payment skill — it handles the 402 header parsing, MetaMask signing, and retry automatically. Do not parse PAYMENT-REQUIRED headers yourself.

Hub Instance

• Server: https://x402-hub.secondstate.io
• GitHub: https://github.com/second-state/x402-hub

When to Use

• User asks "what paid APIs are available on the hub?"
• User asks to use/call a paid API on the x402 Hub
• User gives a hub base URL and wants to do something with it
• You have a /paid/<id> URL and need to know what it does before calling

Two-Step Flow

1. Discover — hit the hub's JSON API to list/inspect listings
2. Pay & call — invoke the x402-payment skill with the paid_url

Step 1: Discover via JSON API

Prefer the JSON API over scraping the HTML catalogue at `/`.

Listing JSON shape:

{
  "id": "demo-add",
  "title": "Add Demo",
  "description": "Sum two numbers ...",
  "upstream_url": "https://x402-hub.secondstate.io/demo/add",
  "paid_url": "https://x402-hub.secondstate.io/paid/demo-add",
  "price": "0.1",
  "pay_to": "0x1cc2...",
  "created_at": "2026-04-22T..."
}

Use paid_url directly — don't reconstruct /paid/<id> manually.

For non-trivial calls (unknown method, body shape, query params), read the usage markdown first:

curl -s https://x402-hub.secondstate.io/api/listings/<id>/usage

Step 2: Pay and call

Delegate to the x402-payment skill. Pass the paid_url plus whatever method/body/headers the usage doc specifies.

python3 /Users/dm4/work/secondstate/x402-hub/skills/x402-payment/x402_pay.py \
  <paid_url> \
  [--method METHOD] [--body 'JSON'] [--headers 'JSON']

The payment script:

• Sends the request
• If 402 → opens browser for MetaMask signing, then retries with the signed header
• If not 402 → returns the response directly
• Outputs a single JSON line with success, status_code, body

Never try to parse the `PAYMENT-REQUIRED` header or build an `X-PAYMENT` header yourself. The x402-payment skill is the only correct path.

For the full flag list (--timeout, --port, output JSON schema, etc.), read the x402-payment skill's SKILL.md directly — this skill only covers the hub-discovery half.

Quick Reference

Picking a Listing

When the user describes what they want ("sum two numbers", "echo my payload"), match against the title and description fields of listings. If multiple match or none clearly match, show the candidates to the user and ask before paying — payment is irreversible.

Example: End-to-end (GET)

User: "Use the hub to compute 3 + 5."

# 1. Discover
curl -s https://x402-hub.secondstate.io/api/listings
# → find listing with description "Sum two numbers..."; id=demo-add, paid_url=https://x402-hub.secondstate.io/paid/demo-add
 
# 2. Check how to call it
curl -s https://x402-hub.secondstate.io/api/listings/demo-add/usage
# → shows GET ?a=&b= or POST JSON
 
# 3. Pay and call (via x402-payment skill)
python3 /Users/dm4/work/secondstate/x402-hub/skills/x402-payment/x402_pay.py \
  "https://x402-hub.secondstate.io/paid/demo-add?a=3&b=5"
# → browser opens for MetaMask signing, then returns {"a":3,"b":5,"sum":8}

Example: POST with JSON body

User: "Echo this payload via the hub's echo API: {\"hello\": \"world\"}"

# 1. Discover → find demo-echo listing, paid_url=https://x402-hub.secondstate.io/paid/demo-echo
# 2. Usage doc says POST with JSON body
# 3. Pay and call
python3 /Users/dm4/work/secondstate/x402-hub/skills/x402-payment/x402_pay.py \
  https://x402-hub.secondstate.io/paid/demo-echo \
  --method POST \
  --body '{"hello": "world"}' \
  --headers '{"Content-Type": "application/json"}'

Shortcut: user already has a paid_url

If the user hands you a /paid/<id> URL directly (e.g. from the hub's HTML detail page), you can skip step 1. Still fetch /api/listings/<id>/usage if the call shape (method, body, query params) isn't obvious. Then pay + call via x402-payment.

Common Mistakes

Hub Defaults (MVP)

• Network: Base Sepolia (eip155:84532)
• Payment asset: USDC (testnet)
• Listings are immutable; a new version = a new listing id
• Upstreams must be publicly reachable; no credential forwarding

Prerequisites for the user

The x402-payment skill opens MetaMask to sign. For that to succeed the user needs:

• MetaMask installed in the default browser
• Wallet on Base Sepolia (eip155:84532)
• Enough testnet USDC to cover the listing's price

If signing fails with a timeout, the wallet is almost always the cause.