StableDomains API, MCP server & CLI

Quickstart, no signup

• Free tier: search, availability, pricing and quotes are free with no account and no API key.
• Self-serve API key: POST /api/v1/agents/signup returns an API key instantly, no form (guest tier, 30 req/min). Or create keys in the dashboard or with POST /api/v1/keys.
• Dry run: POST /api/v1/orders with {"dry_run":true} (or header X-Dry-Run: 1) checks availability, price and TLD rules and returns would_succeed with no order and no charge. DNS PUT/PATCH accept dry_run too.
• Scoped API keys: POST /api/v1/keys with {"scope":"read"} (GET requests), "domains":["example.com"] (limit to named domains) or "allow_purchase":false (no orders, renewals, transfers or top-ups). Existing keys keep full scope.
• Monthly spend cap: PUT /api/v1/account/spend-cap with {"monthly_spend_cap_usd":50}. Orders that would pass the cap are refused with 403.
• Signed webhooks: PUT /api/v1/account/notifications with {"webhook_url":"https://…"} returns a signing secret. Events cover registration, transfer, renewal, expiry and DNS changes (dns.changed). Verify X-StableDomains-Signature: sha256=HMAC_SHA256(secret, raw_body); failed deliveries are retried for 24 hours, deduplicate on X-StableDomains-Delivery.
• Renew dry run: POST /api/v1/domains/{domain}/renew with {"dry_run":true} returns the quote, new expiry and blockers without charging.
• TLD requirements: GET /api/v1/tlds/{tld}/requirements returns a JSON Schema for the order body plus eligibility rules.
• DNS record types: A, AAAA, CNAME, MX, TXT and NS on hosted DNS. For SRV, CAA or ALIAS, set custom nameservers and manage them at your DNS provider.
• Tracing: every API response carries X-Request-Id and X-API-Version.
• Try before you pay: creating an order locks a quote for 60 minutes and costs nothing until a payment is sent, so you can test the full flow end to end.
• Payment: USDC/USDT from a wallet, gasless x402, or a human can pay by card on the Stripe checkout page.
• Stripe Link (MPP): order and renewal 402 responses also carry a WWW-Authenticate: Payment challenge with method="stripe". An agent pays it with a Shared Payment Token from the customer's Stripe Link wallet, after the customer approves it in Link (for example npx @stripe/link-cli mpp pay), then retries with Authorization: Payment … and its key in X-API-Key. The amount is the order price plus the card fee (minimum $0.50). Stripe MPP docs.

curl -X POST https://stabledomains.net/api/v1/agents/signup     # -> api_key
curl "https://stabledomains.net/api/v1/search?q=myidea"
curl "https://stabledomains.net/api/v1/availability?domain=myidea.com"

StableDomains CLI

Official command-line tool (Node 18+). Package: stabledomains. Tarball: stabledomains-0.2.0.tgz.

npx stabledomains search myidea
npx stabledomains price myidea.com
npx stabledomains register myidea.com --years 1 --chain base --token USDC
npx stabledomains status <order_id>
# add --json for machine-readable output; STABLEDOMAINS_API_KEY attaches orders to your account
npx stabledomains register myidea.com --ref yourcode   # or export STABLEDOMAINS_REF=yourcode

Earn on what your tools register

Pass your affiliate ref code with each order and earn 10% of our margin, paid weekly in USDC on Base. Send it as "ref": "yourcode" in the JSON body or as an X-SD-Ref: yourcode header on POST /api/v1/orders, /api/v1/cart and /api/v1/transfers. The MCP tools create_order, create_cart and transfer_domain take ref, and the CLI takes --ref or STABLEDOMAINS_REF. Get your code in the referral dashboard or with the MCP tool get_referral_link. Banners, links and a search widget are in the affiliate toolkit; how the program works.

curl -X POST https://stabledomains.net/api/v1/orders \
  -H "authorization: Bearer $STABLEDOMAINS_API_KEY" -H "content-type: application/json" \
  -H "X-SD-Ref: yourcode" -d '{"domain":"myidea.com","years":1}'

FAQ

Is there an official StableDomains MCP server?

Yes. It runs at https://stabledomains.net/api/mcp (streamable HTTP, OAuth 2.1 with dynamic client registration) and is listed in the MCP Registry as net.stabledomains/registrar, version 2.5.0 (server.json). For chat directories there is also https://stabledomains.net/api/mcp/discover, which has no buying tools and returns a checkout link instead. Setup: Claude, ChatGPT, safety controls.