x402 on StableDomains

Discovery

• /.well-known/x402: paid resources (x402Version 2). Today: GET /api/v1/drops/full ($0.01), GET /api/v1/suggest/bulk ($0.02), POST /api/v1/orders (price of the domain).
• /api/openapi.json: full OpenAPI with request and response schemas.

1. Request, get 402

curl -i "https://stabledomains.net/api/v1/drops/full?limit=1"

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi... (base64 JSON)

Decoded payment-required (real response, trimmed):

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xf773ea4A371114f12A4b82B6dE0b5ED3A6e2504B",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

amount is in USDC base units (6 decimals): 10000 = $0.01.

2. Sign and retry with the payment header

The client signs an EIP-3009 transferWithAuthorization for exactly that amount to payTo, base64-encodes the payload and repeats the request:

curl -i "https://stabledomains.net/api/v1/drops/full?limit=1" \
  -H "PAYMENT-SIGNATURE: <base64 payload>"     # X-PAYMENT also accepted

HTTP/2 200
payment-response: <base64 settlement receipt>

Any x402 client library (for example @x402/fetch) does the sign-and-retry for you.

3. Domain orders

curl -s -c jar -X POST https://stabledomains.net/api/v1/auth/guest
curl -i -b jar -X POST https://stabledomains.net/api/v1/orders \
  -H "content-type: application/json" -H "Idempotency-Key: k1" \
  -d '{"domain":"example-name.xyz","chain":"base","token":"USDC"}'
# HTTP 402, body: { x402Version, accepts:[{scheme:"exact",...},{scheme:"transfer",...}], order:{id,...} }
#                 header X-PAYMENT-REQUIRED: base64 of the same requirements

# gasless: repeat the same request (same Idempotency-Key) with
  -H "X-PAYMENT: <base64 EIP-3009 payload>"
# or pay the order resource directly:
curl -b jar -X POST https://stabledomains.net/api/v1/orders/<id>/pay -H "X-PAYMENT: <payload>"
# plain transfer on any chain/token, then:
curl -b jar -X POST https://stabledomains.net/api/v1/orders/<id>/pay -H "X-PAYMENT-TX: <tx hash or Solana signature>"

Poll GET /api/v1/orders/{id} until status is completed. Use an API key (Authorization: Bearer) instead of the guest cookie for agents.

FAQ