Agent integration

Full spec: /api/openapi.json (OpenAPI 3.1). Error bodies: {error:{code,message,details}} with stable codes (domain_taken, payment_pending, payment_invalid, checkout_unavailable, registration_failed, rate_limited…). Every order response includes next_actions.

# 1. search + quote (no auth)
curl "$BASE/api/v1/search?q=myagent"
curl "$BASE/api/v1/quote?domain=myagent.com&years=1"

# 2. auth: SIWE once (GET /api/v1/auth/nonce, sign EIP-4361, POST /api/v1/auth/verify {message,signature,issue_api_key:true})
#    → returns api_key. Then: -H "Authorization: Bearer sd_live_..."

# 3. create order (idempotent) → HTTP 402 + x402 paymentRequirements
curl -X POST "$BASE/api/v1/orders" -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: my-uuid-1" -H "content-type: application/json" \
  -d '{"domain":"myagent.com","years":1,"chain":"base","token":"USDC"}'
# accepts[0] = {scheme:"exact", network:"base", asset:<USDC>, payTo, maxAmountRequired:"13991234"}

# chain: base | ethereum | arbitrum | polygon | hyperevm | bsc | solana (if enabled), token: USDC | USDT  (see GET /api/v1/health)
# hyperevm: USDT = USDT0. bsc: tokens use 18 decimals, so amount_units has 18 decimals; always send amount_units exactly.

# 4a. pay: transfer EXACTLY the order amount (accepts[] "transfer" entry / order.payment.amount_units) to payTo
# 4b. or gasless x402 (USDC on Base only): sign EIP-3009 transferWithAuthorization for accepts[0] (scheme "exact"),
#     base64 the x402 payload and retry the SAME request with the same Idempotency-Key:
curl -X POST "$BASE/api/v1/orders" -H "Authorization: Bearer $KEY" -H "Idempotency-Key: my-uuid-1"   -H "X-PAYMENT: <base64 {x402Version:1,scheme:'exact',network,payload:{signature,authorization}}>" -d '...same body...'
#     (or POST /api/v1/orders/$ORDER/pay with X-PAYMENT). Any x402 client library (x402-fetch, x402-axios) works.

# 5. retry with proof (or just poll — payments are auto-detected every minute)
curl -X POST "$BASE/api/v1/orders/$ORDER/pay" -H "X-PAYMENT-TX: 0x<txhash>"
curl "$BASE/api/v1/orders/$ORDER"   # status: awaiting_payment → paid → registering → completed

# prepaid balance (fastest for agents): top up once, then buy without a payment round-trip
curl -X POST "$BASE/api/v1/balance/topup" -H "Authorization: Bearer $KEY" -H "Idempotency-Key: t1" -d '{"amount_usd":50}'   # → 402, pay as above
curl -X POST "$BASE/api/v1/orders" -H "Authorization: Bearer $KEY" -H "Idempotency-Key: b1" -d '{"domain":"myagent.com","pay_with":"balance"}'
curl "$BASE/api/v1/balance" -H "Authorization: Bearer $KEY"

# MCP (Streamable HTTP): add server URL $BASE/api/mcp with header Authorization: Bearer $KEY
#   tools: search_domains, quote_domain, create_order, buy_with_balance, check_order, pay_order, get_balance, topup_balance, list_domains

# 6. manage
curl -X PUT "$BASE/api/v1/domains/myagent.com/dns" -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"records":[{"type":"A","name":"@","value":"76.76.21.21"}]}'
curl -X POST "$BASE/api/v1/domains/myagent.com/renew" -H "Authorization: Bearer $KEY" -H "Idempotency-Key: r1" -d '{"years":1}'