x402-hub

name	x402-hub
description	Use when the user wants to discover or call a paid API hosted on an x402 Hub instance. The hub exposes a JSON catalogue at /api/listings and each listing is reachable at /paid/<id>, which requires payment via the x402-payment skill.

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

Endpoint	Returns
GET <hub>/api/listings	JSON array of all listings
GET <hub>/api/listings/<id>	JSON metadata for one listing
GET <hub>/api/listings/<id>/usage	text/markdown usage doc (examples, request/response shape)

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

Task	Command
List all paid APIs	curl -s <hub>/api/listings
Inspect one listing	curl -s <hub>/api/listings/<id>
Read usage doc	curl -s <hub>/api/listings/<id>/usage
Call a paid API	Invoke x402-payment skill with the paid_url

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

Mistake	Fix
Scraping / HTML for listings	Use GET /api/listings JSON instead
Parsing PAYMENT-REQUIRED header manually	Delegate to x402-payment skill — it handles 402
Building X-PAYMENT header by hand	Delegate to x402-payment skill
Reconstructing /paid/<id> from pieces	Use the paid_url field from the listing JSON
Paying without confirming the match	Payment is irreversible — confirm with user if listing choice is ambiguous

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.