{"openapi":"3.1.0","info":{"x-agent-policy":["Check availability and price immediately before buying (GET /api/v1/availability or search_domains); never rely on an earlier result.","Create the order (POST /api/v1/orders or create_order) to get a price-locked quote: quote.price_usd, quote.locked_until and checkout_url.","Show the human the domain, years, total price, token/chain and the lock expiry, and get explicit confirmation before paying.","If the human prefers to pay themselves, send them checkout_url (/order/{id}): a prefilled page they can pay from with any wallet, QR or card.","Always send an Idempotency-Key header (or idempotency_key) and reuse it on retries; the same key never creates or charges a second order.","Pay only the exact amount in the order before quote.locked_until; if it lapsed, create a new order rather than reusing an old address.","Poll GET /api/v1/orders/{id} (or check_order) until status is completed, then report the result to the human."],"title":"StableDomains API","version":"2.5.0","description":"Agent operating policy: Check availability and price immediately before buying (GET /api/v1/availability or search_domains); never rely on an earlier result. Create the order (POST /api/v1/orders or create_order) to get a price-locked quote: quote.price_usd, quote.locked_until and checkout_url. Show the human the domain, years, total price, token/chain and the lock expiry, and get explicit confirmation before paying. If the human prefers to pay themselves, send them checkout_url (/order/{id}): a prefilled page they can pay from with any wallet, QR or card. Always send an Idempotency-Key header (or idempotency_key) and reuse it on retries; the same key never creates or charges a second order. Pay only the exact amount in the order before quote.locked_until; if it lapsed, create a new order rather than reusing an old address. Poll GET /api/v1/orders/{id} (or check_order) until status is completed, then report the result to the human. 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). Auth options: none (keyless orders + 402/x402), Bearer API key, or OAuth 2.1 for MCP connectors; browser sign-in at /signin (email link, passkey, wallet). Affiliate programme (open to agents): pass ref on POST /orders, /cart, /transfers; details https://stabledomains.net/affiliates","contact":{"name":"StableDomains","email":"support@stabledomains.net","url":"https://stabledomains.net"}},"externalDocs":{"description":"Affiliate programme (open to agents)","url":"https://stabledomains.net/affiliates"},"servers":[{"url":"https://stabledomains.net"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key sd_live_… (Dashboard → Create API key, POST /api/v1/keys, or SIWE issue_api_key). OAuth access tokens are the same kind of key."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization code + PKCE (S256), public clients via dynamic registration. Metadata: /.well-known/oauth-authorization-server. Used by MCP connectors.","flows":{"authorizationCode":{"authorizationUrl":"https://stabledomains.net/oauth/authorize","tokenUrl":"https://stabledomains.net/api/oauth/token","scopes":{"account":"Manage domains, orders and balance"}}}},"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","transfer","topup","cart"]},"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","properties":{"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"availability":{"type":"string"},"price_usd":{"type":"string"},"renewal_usd":{"type":"string"},"premium":{"type":"boolean","description":"True for registry premium names. Price = registry premium price + 12%."},"renewal_price":{"type":"string","description":"USD per renewal year (premium names renew at a premium rate)."}}}}}}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/agents/signup":{"post":{"operationId":"agent_signup","summary":"Instant agent signup: API key, no form","description":"Returns an API key at once. Guest tier (30 req/min) until claimed by email (POST /api/v1/auth/email-start with the key) or wallet (POST /api/v1/auth/verify with claim:true). Per IP: 3/hour, 10/day.","responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string"},"user":{"type":"object"},"limits":{"type":"object"},"claim":{"type":"object"}}}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/aftermarket":{"get":{"operationId":"search_aftermarket","summary":"Aftermarket links (Atom.com, outside marketplace) for a taken name","description":"Returns affiliate links to Atom.com keyword search and premium marketplace. Atom is an outside marketplace; we may earn a commission. Exact-name listing is not verified (Atom has no public listings API).","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"marketplace":{"type":"string"},"outside_marketplace":{"type":"boolean"},"disclaimer":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"kind":{"type":"string"},"url":{"type":"string"}}}}}}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/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","properties":{"total_usd":{"type":"string"},"premium":{"type":"boolean","description":"True for registry premium names. Price = registry premium price + 12%."},"renewal_price":{"type":"string","description":"USD per renewal year (premium names renew at a premium rate)."}}}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/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":"show_parked","in":"query","schema":{"enum":["1"]},"description":"include names whose archive shows only parked/for-sale pages"},{"name":"min_quality","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"enum":["quality","value","price","length","drops","new","brand","backlinks","domain","score"]}},{"name":"order","in":"query","schema":{"enum":["asc","desc"]},"description":"sort direction; default depends on sort (quality/value desc, price/length/drops asc)"},{"name":"available_only","in":"query","schema":{"enum":["1"]},"description":"only names registrable now (same as status=available)"},{"name":"drops_within_days","in":"query","schema":{"type":"integer"},"description":"pending-delete names dropping within N days"},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"opaque next_cursor from the previous response"},{"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"}}}}},"security":[]}},"/api/v1/suggest":{"post":{"operationId":"suggest_domains","summary":"Name generator: idea -> available domains with price + checkout (free, top 10). Or {domain} -> close available alternatives to a taken name","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"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"}}}}},"security":[]}},"/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":"Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base, settled via the Coinbase CDP facilitator)"}},"x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"network":"eip155:8453","asset":"USDC"}}},"/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"}}}}},"security":[]}},"/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"}}}}},"security":[]}},"/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"}}}}},"security":[]}},"/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"}}}}},"security":[]}},"/api/v1/watch":{"post":{"operationId":"watch_domain","summary":"Alert when an expiring domain drops (webhook immediate, email double opt-in; free)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"webhook_url":{"type":"string"},"email":{"type":"string"}}}}}},"responses":{"201":{"description":"watch created"}},"security":[]}},"/api/v1/domains/{domain}/dns":{"get":{"operationId":"get_dns","security":[{"bearer":[]},{"oauth2":["account"]},{"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","summary":"Replace nameservers and/or the full record set (A, AAAA, CNAME, MX, TXT). Hosted records need NiceNIC nameservers (default).","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"nameservers":{"type":"array","items":{"type":"string"}},"records":{"type":"array","items":{"type":"object","required":["type","name","value"],"properties":{"type":{"enum":["A","AAAA","CNAME","MX","TXT"]},"name":{"type":"string","description":"@ for apex"},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer","description":"MX only"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"patch":{"operationId":"patch_dns","summary":"Merge: upsert records and delete remove[] selectors ({type,name,value?}); all other records are kept. A CNAME replaces the existing CNAME at the same name.","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","required":["type","name","value"],"properties":{"type":{"enum":["A","AAAA","CNAME","MX","TXT"]},"name":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer"},"priority":{"type":"integer"}}}},"remove":{"type":"array","items":{"type":"object","required":["type","name"],"properties":{"type":{"enum":["A","AAAA","CNAME","MX","TXT"]},"name":{"type":"string"},"value":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/availability":{"get":{"operationId":"check_availability","summary":"One domain: availability, price and (when taken) suggestions[] of close available alternatives, cheapest first (free)","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string"},"availability":{"enum":["available","taken","unknown"]},"price_usd":{"type":"string"},"suggestions":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"price_usd":{"type":"string"},"reason":{"type":"string"},"checkout_url":{"type":"string"}}}}}}}}}},"security":[]}},"/api/v1/domains/{domain}/forward":{"get":{"operationId":"list_url_forwards","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"set_url_forward","summary":"Free 301/302 URL forward for the whole domain (@, includes www) or a subdomain","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","format":"uri"},"subdomain":{"type":"string","default":"@"},"code":{"enum":[301,302]},"preserve_path":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"delete_url_forward","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"subdomain","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}/dns/template":{"get":{"operationId":"list_dns_templates","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]},"post":{"operationId":"apply_dns_template","summary":"Free one-call DNS setup: vercel, netlify, github-pages, google-workspace, microsoft-365, zoho-mail","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template"],"properties":{"template":{"enum":["vercel","netlify","github-pages","google-workspace","microsoft-365","zoho-mail"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}/renew":{"post":{"operationId":"renew_domain","summary":"Renew; 402 with USDC payment requirements, or pay_with=balance for instant","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"years":{"type":"integer"},"chain":{"type":"string"},"token":{"enum":["USDC","USDT"]},"pay_with":{"enum":["crypto","balance"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/domains/{domain}/autorenew":{"get":{"operationId":"get_auto_renew","summary":"Auto-renew vault status: enabled, renewal balance, price, shortfall, ledger","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"set_auto_renew","summary":"Toggle auto-renew and move USDC between prepaid balance and this domain's renewal balance","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"deposit_usd":{"type":"number"},"withdraw_usd":{"type":"number"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}/balance":{"get":{"operationId":"get_renewal_balance","summary":"Renewal balance for one domain vs its renewal price","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/autorenew":{"get":{"operationId":"list_auto_renew","summary":"Auto-renew status and renewal balances for all your domains","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/account/notifications":{"get":{"operationId":"get_notifications","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"set_notification_webhook","summary":"Account webhook for domain.expiring (30/7/1 days), domain.renewed, domain.transfer_completed. Emails go to the account email.","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhook_url"],"properties":{"webhook_url":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/transfers":{"post":{"operationId":"transfer_domain","summary":"Inbound transfer with auth/EPP code, paid in USDC (adds 1 year)","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain","auth_code"],"properties":{"domain":{"type":"string"},"auth_code":{"type":"string"},"years":{"type":"integer"},"chain":{"type":"string"},"token":{"enum":["USDC","USDT"]},"pay_with":{"enum":["crypto","balance"]},"ref":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/cart":{"post":{"operationId":"create_cart","summary":"Register up to 20 domains with ONE payment; failures are refunded to prepaid balance","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","items":{"type":"string"},"maxItems":20},"chain":{"type":"string"},"token":{"enum":["USDC","USDT"]},"nameservers":{"type":"array","items":{"type":"string"}},"ref":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/v1/referrals":{"get":{"operationId":"get_referral_stats","summary":"Referral stats: link, clicks, referred users, sales, earned/unpaid/pending/paid (10% of our margin, paid weekly in USDC on Base, $5 min, admin-approved)","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"attach_referrer","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ref"],"properties":{"ref":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/referrals/link":{"get":{"operationId":"get_referral_link","summary":"Your ref code and ?ref= link (30-day attribution)","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/referrals/payout-address":{"put":{"operationId":"set_payout_address","summary":"Set the Base USDC address for weekly referral payouts (null to clear)","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payout_address"],"properties":{"payout_address":{"type":["string","null"]}}}}}},"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":"show_parked","in":"query","schema":{"enum":["1"]},"description":"include names whose archive shows only parked/for-sale pages"},{"name":"min_quality","in":"query","schema":{"type":"integer"}},{"name":"sort","in":"query","schema":{"enum":["quality","value","price","length","drops","new","brand","backlinks","domain","score"]}},{"name":"order","in":"query","schema":{"enum":["asc","desc"]},"description":"sort direction; default depends on sort (quality/value desc, price/length/drops asc)"},{"name":"available_only","in":"query","schema":{"enum":["1"]},"description":"only names registrable now (same as status=available)"},{"name":"drops_within_days","in":"query","schema":{"type":"integer"},"description":"pending-delete names dropping within N days"},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"opaque next_cursor from the previous response"},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base, settled via the Coinbase CDP facilitator)"}},"x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"network":"eip155:8453","asset":"USDC"}}},"/api/v1/radar":{"get":{"operationId":"drop_radar","summary":"Domain Drop Radar (free): top 25 + summary, presets, multi-TLD/keyword/value filters, ready order/watch bodies","parameters":[{"name":"preset","in":"query","schema":{"type":"string"}},{"name":"tld","in":"query","schema":{"type":"string"}},{"name":"kw","in":"query","schema":{"type":"string"}},{"name":"starts_with","in":"query","schema":{"type":"string"}},{"name":"ends_with","in":"query","schema":{"type":"string"}},{"name":"min_len","in":"query","schema":{"type":"string"}},{"name":"max_len","in":"query","schema":{"type":"string"}},{"name":"min_value","in":"query","schema":{"type":"string"}},{"name":"max_value","in":"query","schema":{"type":"string"}},{"name":"max_price","in":"query","schema":{"type":"string"}},{"name":"min_quality","in":"query","schema":{"type":"string"}},{"name":"min_age","in":"query","schema":{"type":"string"}},{"name":"dictionary","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"new_within","in":"query","schema":{"type":"string"}},{"name":"no_hyphen","in":"query","schema":{"type":"string"}},{"name":"no_digits","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"enum":["quality","value","price","length","drops","new","brand","backlinks","domain","score"]}},{"name":"order","in":"query","schema":{"enum":["asc","desc"]}},{"name":"available_only","in":"query","schema":{"enum":["1"]}},{"name":"drops_within_days","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from previous page"}],"responses":{"200":{"description":"radar response"}},"security":[]}},"/api/v1/radar/alerts":{"post":{"operationId":"radar_alert","summary":"Save a radar; signed webhook (radar.match) and/or email. Free: 3/IP, 25/key, 20 events/alert/day","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["filters"],"properties":{"filters":{"type":"object"},"webhook_url":{"type":"string"},"email":{"type":"string"},"name":{"type":"string"}}}}}},"responses":{"200":{"description":"alert with token and secret (shown once)"}},"security":[]},"get":{"operationId":"list_radar_alerts","summary":"List alerts (API key or ?token=)","responses":{"200":{"description":"alerts"}},"security":[]},"delete":{"operationId":"delete_radar_alert","summary":"Delete (?token= or API key + ?id=)","responses":{"200":{"description":"deleted"}},"security":[]}},"/api/v1/radar/feed":{"get":{"operationId":"radar_json_feed","summary":"JSON Feed 1.1 for any radar filter (also /radar/feed.json)","responses":{"200":{"description":"JSON Feed","content":{"application/feed+json":{}}}},"security":[]}},"/api/v1/availability/bulk":{"get":{"operationId":"availability_bulk","summary":"Paid (x402, $0.10 USDC on Base): availability + price for up to 100 domains","security":[],"parameters":[{"name":"domains","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated, up to 100"}],"responses":{"200":{"description":"items[] with domain, availability, price_usd, buy_url"},"402":{"description":"Payment required (x402)"}}}},"/api/v1/valuation":{"get":{"operationId":"valuation_paid","summary":"Paid (x402, $0.02 USDC on Base): domain valuation estimate","security":[],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Domain to value"}],"responses":{"200":{"description":"estimate_usd, range_usd, availability, register_price_usd"},"402":{"description":"Payment required (x402)"}}}},"/api/v1/alerts":{"get":{"operationId":"drop_alert_paid","summary":"Paid (x402, $0.01 USDC on Base): drop alert for one domain via webhook or email","security":[],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"Domain to watch"},{"name":"webhook_url","in":"query","required":false,"schema":{"type":"string"},"description":"HTTPS webhook"},{"name":"email","in":"query","required":false,"schema":{"type":"string"},"description":"Email (needs confirmation)"}],"responses":{"201":{"description":"watch_id, unsubscribe_url"},"402":{"description":"Payment required (x402)"}}}},"/api/v1/register":{"post":{"operationId":"register_domain_x402","summary":"Register a domain name, paid in USDC via x402 (Base). Returns 402 with the exact live price; retry with PAYMENT-SIGNATURE. Premium or unavailable names are refused before payment. Idempotent per payment authorization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"example.xyz"},"years":{"type":"integer","minimum":1,"maximum":10,"default":1},"nameservers":{"type":"array","items":{"type":"string"},"maxItems":6}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"status":{"type":"string"},"domain":{"type":"string"},"years":{"type":"integer"},"price_usd":{"type":"string"},"tx_hash":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 payment required (PAYMENT-REQUIRED header)"},"409":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/radar/full":{"get":{"operationId":"radar_full","summary":"Paid full Radar dataset ($0.02 per call via x402 on Base, USDC): same filters/presets as /api/v1/radar, up to 1000 rows with all signals","responses":{"200":{"description":"Full dataset"},"402":{"description":"Payment required: x402 v2 challenge in the PAYMENT-REQUIRED header (exact scheme, USDC on Base, settled via the Coinbase CDP facilitator)"}},"x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"network":"eip155:8453","asset":"USDC"}}},"/api/v1/drops/rss":{"get":{"operationId":"drops_rss","summary":"RSS of newly found drops","responses":{"200":{"description":"RSS 2.0","content":{"application/rss+xml":{}}}},"security":[]}},"/api/v1/tlds":{"get":{"operationId":"list_tlds","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/v1/orders":{"post":{"operationId":"create_order","security":[{"bearer":[]},{"oauth2":["account"]},{"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"}},"ref":{"type":"string","description":"referrer code (first touch)"},"showcase":{"type":"boolean","description":"opt in to the public /showcase listing"},"showcase_title":{"type":"string","maxLength":80},"showcase_description":{"type":"string","maxLength":200}}}}}},"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":[]},{"oauth2":["account"]},{"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"}}}}},"security":[]}},"/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"}}}}},"security":[]},"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"}}}}},"security":[]}},"/api/v1/domains":{"get":{"operationId":"list_domains","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/domains/{domain}":{"get":{"operationId":"get_domain","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"patch":{"operationId":"set_auto_renew","summary":"Toggle auto-renew (paid from prepaid balance 7 days before expiry)","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["auto_renew"],"properties":{"auto_renew":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/auth/nonce":{"get":{"operationId":"siwe_nonce","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/v1/auth/email-start":{"post":{"operationId":"email_sign_in","summary":"Email a one-time sign-in (or, from a signed-in session, link-this-email) link. The link opens /signin/confirm; only the button POST consumes it (prefetch-safe).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]}},"/api/v1/auth/passkey/login/options":{"post":{"operationId":"passkey_login_options","summary":"WebAuthn assertion options (discoverable credentials); then POST /api/v1/auth/passkey/login/verify with the browser response. Register: /api/v1/auth/passkey/register/{options,verify} from a session.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/v1/account/identities":{"get":{"operationId":"list_sign_in_methods","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"summary":"Email, wallets and passkeys linked to this account","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/keys":{"get":{"operationId":"list_api_keys","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"create_api_key","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"summary":"Create an API key (shown once)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"revoke_api_key","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/oauth/register":{"post":{"operationId":"oauth_register_client","summary":"RFC 7591 dynamic client registration (public clients, PKCE)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect_uris"],"properties":{"redirect_uris":{"type":"array","items":{"type":"string"}},"client_name":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/oauth/token":{"post":{"operationId":"oauth_token","summary":"authorization_code + code_verifier → access_token (Bearer API key)","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","code","code_verifier"],"properties":{"grant_type":{"enum":["authorization_code"]},"code":{"type":"string"},"code_verifier":{"type":"string"},"redirect_uri":{"type":"string"},"client_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/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"}}}}},"security":[]}},"/api/v1/orders/{id}/onramp":{"post":{"operationId":"card_checkout","description":"Legacy card checkout URL; may be unavailable. For card payments use the Stripe card checkout on the order page (/order/{id}?pay=card).","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"}}}}},"security":[]}},"/api/v1/balance":{"get":{"operationId":"get_balance","security":[{"bearer":[]},{"oauth2":["account"]},{"session":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/balance/topup":{"post":{"operationId":"topup_balance","security":[{"bearer":[]},{"oauth2":["account"]},{"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"}}}}},"security":[]}},"/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"}}}}},"security":[]}},"/api/v1/health":{"get":{"operationId":"health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}}},"x-discovery":{}}