{"openapi":"3.1.0","info":{"title":"StableDomains API","version":"2.0.0","description":"Register domains with USDC/USDT. Agent-first. Flow: search → quote → POST /orders (402 + x402 payment requirements) → transfer exact amount → POST /orders/{id}/pay with X-PAYMENT-TX (or poll; payments auto-detected) → completed. Networks: Base, Ethereum, Arbitrum, Polygon (USDC/USDT, same address), Solana when configured. Also HyperEVM (USDC/USDT0) and BNB Chain (USDC/USDT, 18 decimals). Gasless: x402 exact scheme (EIP-3009 USDC, Base only) via X-PAYMENT header on POST /orders retry or /orders/{id}/pay. Prepaid: top up /balance/topup, then POST /orders {pay_with:\"balance\"}. MCP: POST /api/mcp (JSON-RPC, streamable HTTP)."},"servers":[{"url":"https://stabledomains.net"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key sd_live_…"},"session":{"type":"apiKey","in":"cookie","name":"sd_session"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_domain","unsupported_tld","domain_taken","availability_unknown","unauthorized","forbidden","not_found","rate_limited","checkout_unavailable","payment_required","payment_pending","payment_invalid","order_expired","registration_failed","idempotency_conflict","registrar_error","internal_error"]},"message":{"type":"string"},"details":{"type":"object"}}}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"kind":{"enum":["register","renew","topup"]},"status":{"enum":["awaiting_payment","expired","abandoned","paid","registering","registration_retry","paid_awaiting_registration","completed","registration_failed"]},"domain":{"type":"string"},"years":{"type":"integer"},"price_usd":{"type":"string"},"simulated":{"type":"boolean"},"payment":{"type":"object","properties":{"chain":{"type":"string"},"token":{"type":"string"},"token_address":{"type":"string"},"pay_to":{"type":"string"},"amount":{"type":"string"},"amount_units":{"type":"string"},"tx_hash":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"eip681":{"type":["string","null"]},"solana_pay":{"type":["string","null"]},"chain_id":{"type":["integer","null"]},"method":{"enum":["transfer","x402","onramp","balance"]},"card_available":{"type":"boolean"}}},"next_actions":{"type":"object","additionalProperties":{"type":"string"}}}},"PaymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"enum":["exact","transfer"]},"network":{"type":"string"},"maxAmountRequired":{"type":"string"},"payTo":{"type":"string"},"asset":{"type":"string"},"resource":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"}}}},"order":{"$ref":"#/components/schemas/Order"}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}}}},"paths":{"/api/v1/search":{"get":{"operationId":"search_domain","summary":"Availability across all supported TLDs","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/quote":{"get":{"operationId":"get_quote","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}},{"name":"years","in":"query","schema":{"type":"integer"}},{"name":"kind","in":"query","schema":{"enum":["register","renew"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/drops":{"get":{"operationId":"find_dropping_domains","summary":"Expiring / pending-delete / just-dropped domains with backlinks and Wayback history (free, top 25)","parameters":[{"name":"tld","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["available","pending_delete","redemption","expired_grace"]}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"min_len","in":"query","schema":{"type":"integer"}},{"name":"max_len","in":"query","schema":{"type":"integer"}},{"name":"min_backlinks","in":"query","schema":{"type":"integer"}},{"name":"min_age","in":"query","schema":{"type":"integer"},"description":"years since first Wayback capture"},{"name":"min_brand","in":"query","schema":{"type":"integer"}},{"name":"max_price","in":"query","schema":{"type":"number"}},{"name":"no_hyphen","in":"query","schema":{"enum":["1"]}},{"name":"no_digits","in":"query","schema":{"enum":["1"]}},{"name":"include_spam","in":"query","schema":{"enum":["1"]},"description":"spammy names (casino, adult, pills, loans, replicas) are hidden by default"},{"name":"sort","in":"query","schema":{"enum":["score","backlinks","brand","new","drops","length"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suggest":{"post":{"operationId":"suggest_domains","summary":"Name generator: idea -> available domains with price + checkout (free, top 10)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["idea"],"properties":{"idea":{"type":"string"},"tlds":{"type":"array","items":{"type":"string"}},"max_price":{"type":"number"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suggest/bulk":{"get":{"operationId":"suggest_domains_bulk","summary":"Bulk name generator (90 checks, 50 results). x402 $0.02 USDC on Base","parameters":[{"name":"idea","in":"query","required":true,"schema":{"type":"string"}},{"name":"tlds","in":"query","schema":{"type":"string"}},{"name":"max_price","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment required","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tools/value":{"get":{"operationId":"estimate_domain_value","summary":"Heuristic domain value estimate (free)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tools/whois":{"get":{"operationId":"whois_lookup","summary":"RDAP/WHOIS lookup (free)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tools/dns":{"get":{"operationId":"dns_email_check","summary":"DNS + SPF/DKIM/DMARC check (free)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tools/dropping":{"get":{"operationId":"is_domain_dropping","summary":"Expired-domain lifecycle and drop date (free)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/drops/full":{"get":{"operationId":"find_dropping_domains_full","summary":"Full drops feed (≤500 rows, all metrics). x402: $0.01 USDC on Base, send PAYMENT-SIGNATURE header","parameters":[{"name":"tld","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"enum":["available","pending_delete","redemption","expired_grace"]}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"min_len","in":"query","schema":{"type":"integer"}},{"name":"max_len","in":"query","schema":{"type":"integer"}},{"name":"min_backlinks","in":"query","schema":{"type":"integer"}},{"name":"min_age","in":"query","schema":{"type":"integer"},"description":"years since first Wayback capture"},{"name":"min_brand","in":"query","schema":{"type":"integer"}},{"name":"max_price","in":"query","schema":{"type":"number"}},{"name":"no_hyphen","in":"query","schema":{"enum":["1"]}},{"name":"no_digits","in":"query","schema":{"enum":["1"]}},{"name":"include_spam","in":"query","schema":{"enum":["1"]},"description":"spammy names (casino, adult, pills, loans, replicas) are hidden by default"},{"name":"sort","in":"query","schema":{"enum":["score","backlinks","brand","new","drops","length"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment required (PAYMENT-REQUIRED header)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/drops/rss":{"get":{"operationId":"drops_rss","summary":"RSS of newly found drops","responses":{"200":{"description":"RSS 2.0","content":{"application/rss+xml":{}}}}}},"/api/v1/tlds":{"get":{"operationId":"list_tlds","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/orders":{"post":{"operationId":"create_order","security":[{"bearer":[]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"X-PAYMENT","in":"header","schema":{"type":"string"},"description":"x402 payload; retry with same Idempotency-Key to pay gaslessly"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"years":{"type":"integer"},"chain":{"enum":["base","ethereum","arbitrum","polygon","hyperevm","bsc","solana"]},"token":{"enum":["USDC","USDT"]},"pay_with":{"enum":["crypto","balance"],"description":"balance = debit prepaid balance, order returned paid (200/201)"},"nameservers":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"402":{"description":"Order created; pay to proceed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"409":{"description":"domain_taken / idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"checkout_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"list_orders","security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/orders/{id}":{"get":{"operationId":"check_order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/orders/{id}/pay":{"get":{"operationId":"payment_requirements","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}},"post":{"operationId":"submit_payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-PAYMENT-TX","in":"header","schema":{"type":"string"},"description":"EVM tx hash or Solana signature"},{"name":"X-PAYMENT","in":"header","schema":{"type":"string"},"description":"base64 x402 exact payload (EIP-3009 transferWithAuthorization)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"payment_pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"422":{"description":"payment_invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains":{"get":{"operationId":"list_domains","security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}":{"get":{"operationId":"get_domain","security":[{"bearer":[]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}/dns":{"get":{"operationId":"get_dns","security":[{"bearer":[]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"set_dns","security":[{"bearer":[]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"nameservers":{"type":"array","items":{"type":"string"}},"records":{"type":"array","items":{"type":"object","properties":{"type":{"enum":["A","AAAA","CNAME","TXT","MX"]},"name":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}/renew":{"post":{"operationId":"renew_domain","security":[{"bearer":[]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/auth/nonce":{"get":{"operationId":"siwe_nonce","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/auth/verify":{"post":{"operationId":"siwe_verify","description":"EIP-4361 message + signature. issue_api_key:true returns an API key (agents).","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["message","signature"],"properties":{"message":{"type":"string"},"signature":{"type":"string"},"issue_api_key":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/keys":{"get":{"operationId":"list_keys","security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"create_key","security":[{"bearer":[]},{"session":[]}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/orders/{id}/onramp":{"post":{"operationId":"card_checkout","description":"Coinbase Onramp URL (card/Apple Pay → USDC to this order). Requires CDP keys on the deployment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"503":{"description":"checkout_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/balance":{"get":{"operationId":"get_balance","security":[{"bearer":[]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/balance/topup":{"post":{"operationId":"topup_balance","security":[{"bearer":[]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_usd"],"properties":{"amount_usd":{"type":"number","minimum":5,"maximum":5000},"chain":{"type":"string"},"token":{"enum":["USDC","USDT"]}}}}}},"responses":{"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/auth/guest":{"post":{"operationId":"guest_session","description":"Browser guest session (no wallet).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp":{"post":{"operationId":"mcp","description":"MCP JSON-RPC (initialize, tools/list, tools/call). Bearer auth forwarded.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/health":{"get":{"operationId":"health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}