---
name: stabledomains
description: Search, price and register domain names and pay in USDC/USDT (Base, Ethereum, Arbitrum, Polygon, HyperEVM, BNB Chain, Solana) or gasless via x402. Also expiring/just-dropped domain radar, drop feeds and alerts. Use when an agent needs to find, buy, renew or manage a domain, or watch domains that are dropping.
---

# StableDomains

Real domains. Paid in stablecoins. Bought by agents. ICANN domains, premium names and live drop alerts, paid in USDC or USDT on any major chain. Agents sign up, pay per call via x402, and register in one request. No account forms. Pay in USDC/USDT or by card. Site: https://stabledomains.net. Chains: Base, Ethereum, Arbitrum, Polygon, HyperEVM, BNB Chain, Solana (1 USDC/USDT = 1 USD). Free WHOIS privacy.

- MCP server: https://stabledomains.net/api/mcp (streamable HTTP, JSON-RPC)
- OpenAPI 3.1: https://stabledomains.net/api/openapi.json
- llms.txt: https://stabledomains.net/llms.txt (full: https://stabledomains.net/llms-full.txt)
- Human docs: https://stabledomains.net/docs

**Topic skills** (load only what you need):
- [Search and register a domain](https://stabledomains.net/skill_register.md)
- [Manage DNS](https://stabledomains.net/skill_dns.md)
- [Renew, auto-renew and transfer in](https://stabledomains.net/skill_renew.md)
- [Expiring and dropped domains](https://stabledomains.net/skill_drops.md)
- [Payments: USDC/USDT, x402, balance](https://stabledomains.net/skill_payments.md)
- [Name taken? Available alternatives](https://stabledomains.net/skill_aftermarket.md)

## 1. MCP setup

**Claude Code**
```
claude mcp add --transport http stabledomains https://stabledomains.net/api/mcp
# with an API key (recommended for buying):
claude mcp add --transport http stabledomains https://stabledomains.net/api/mcp --header "Authorization: Bearer <key>"
```
**Claude (desktop / claude.ai):** Settings → Connectors → Add custom connector → URL `https://stabledomains.net/api/mcp`. Sign in with OAuth when asked (only needed for account tools).

**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
```json
{ "mcpServers": { "stabledomains": { "url": "https://stabledomains.net/api/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```
**VS Code / Copilot** (`.vscode/mcp.json`):
```json
{ "servers": { "stabledomains": { "type": "http", "url": "https://stabledomains.net/api/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```
**ChatGPT:** Settings → Apps & Connectors → Advanced → enable Developer mode → Create connector → MCP server URL `https://stabledomains.net/api/mcp`, authentication OAuth.

**Any MCP client with an API key:** add header `Authorization: Bearer <key>` (free key: `POST https://stabledomains.net/api/v1/agents/signup`, or pass `api_key` on buying tools).

Key tools: search_domains, quote_domain, create_order, pay_order, check_order, buy_with_balance, list_domains, get_dns, set_dns, set_url_forward, apply_dns_template, suggest_domains, renew_domain, transfer_domain, drop_radar, find_dropping_domains, radar_alert, watch_domain, is_domain_dropping. Search, quotes, tools and x402 payments need no auth.

## 2. REST quickstart: search → price → register → pay

```
GET  https://stabledomains.net/api/v1/search?q=myagent            # availability + price across TLDs (premium, renewal_price)
GET  https://stabledomains.net/api/v1/quote?domain=myagent.com&years=1
POST https://stabledomains.net/api/v1/orders
     Idempotency-Key: <unique>
     {"domain":"myagent.com","years":1,"chain":"base","token":"USDC"}
```
`POST /orders` answers **402** with the payment requirements: exact amount (a unique sub-cent suffix), `pay_to` address and token contract. Then either:

1. Send exactly that amount of USDC/USDT on the chosen chain, then `POST https://stabledomains.net/api/v1/orders/{id}/pay` with header `X-PAYMENT-TX: <tx hash>` (or just poll; payments are auto-detected), or
2. Gasless x402 (USDC on Base): retry with an `X-PAYMENT` header signed per the 402 body.

Poll `GET https://stabledomains.net/api/v1/orders/{id}` until `status` is `completed`. Chains: base, ethereum, arbitrum, polygon, hyperevm (USDT0), bsc (18 decimals), solana. Tokens: USDC, USDT.
Prepaid alternative: top up via `POST /api/v1/balance/topup`, then `POST /api/v1/orders {"pay_with":"balance",...}`.

Premium names: `premium: true` in search/quote; priced from the registry premium; `renewal_price` shows the premium renewal. Large premium orders may be refused before payment (clear error, nothing charged).

Manage owned domains (auth): `GET /api/v1/domains`, `PUT /api/v1/domains/{domain}/dns`, `POST /api/v1/domains/{domain}/renew`, `POST /api/v1/domains/{domain}/autorenew`, transfers via `POST /api/v1/transfers`.

### Name taken? Available alternatives
Taken name? `GET https://stabledomains.net/api/v1/availability?domain=agent.com` returns `availability` plus `suggestions[]`: close AVAILABLE alternatives (other extensions, get/try/hq/app variants), live-checked and cheapest first. `/api/v1/search` adds the same `suggestions` when the name is taken; MCP `suggest_domains {"domain":"agent.com"}` (free).

### Free URL forwarding and DNS templates
- Free URL forwarding: `PUT https://stabledomains.net/api/v1/domains/{domain}/forward {"target":"https://x.com/you","subdomain":"@"}` (MCP `set_url_forward`; `subdomain` @ also covers www, or e.g. `blog`; `code` 301|302; `preserve_path`). `GET` lists forwards, `DELETE ?subdomain=` removes one.
- One-call DNS templates (free): `POST https://stabledomains.net/api/v1/domains/{domain}/dns/template {"template":"vercel"}` (MCP `apply_dns_template`). Templates: vercel, netlify (params.site), github-pages (params.user), google-workspace, microsoft-365, zoho-mail (params.region). List: `GET https://stabledomains.net/api/v1/domains/x/dns/template`.

### Name taken?
`GET https://stabledomains.net/api/v1/suggest?domain=cloud.com` (MCP `suggest_domains` with `domain`) returns close AVAILABLE alternatives (other endings and get/try/hq variants), live-checked, cheapest first, each with price and checkout_url.

### Showcase your project
- Showcase (opt-in, free): list your project on https://stabledomains.net/showcase. At order time pass showcase:true, showcase_title, showcase_description to POST /api/v1/orders or MCP create_order; later PUT /api/v1/domains/{domain}/showcase {title, description} to add or edit, DELETE to remove. Public list: GET /api/v1/showcase.

### Referrals: earn as an agent
The affiliate programme is open to agents (https://stabledomains.net/affiliates): a commission on every paid order you refer, paid weekly in USDC on Base ($5 minimum). Enroll on the full MCP (`agent_signup`, `set_payout_address`); the read-only discover MCP exposes `get_referral_link` and `get_referral_stats` only. Discover cannot buy domains; share `?ref=` and earn when a person or full-MCP agent completes a paid order.
1. Instant key if needed: MCP `agent_signup` (or `POST /api/v1/agents/signup`).
2. Get your code: MCP `get_referral_link` (or `GET /api/v1/referrals/link`, auth).
3. Set a payout address: MCP `set_payout_address {payout_address: "0x…"}` (or `PUT /api/v1/referrals/payout-address`).
4. Pass `"ref": "<code>"` on `create_order`, `create_cart` and `transfer_domain` (REST: /api/v1/orders, /cart, /transfers), or share `https://stabledomains.net/?ref=<code>`. Track with `get_referral_stats`.

## Raise your x402 client spend cap

Default client caps ($0.10 in x402-fetch / x402-axios v1, $1 in @x402/fetch v2) block domain purchases (often $5–$50+). Raise the per-payment cap to about **50 USDC** before calling `/api/v1/register` or paying an order:

- **x402-fetch / x402-axios (v1):** pass `maxValue` (USDC base units, 6 decimals). Example: `wrapFetchWithPayment(fetch, wallet, 50_000_000)` (= $50).
- **@x402/fetch (v2):** `client.setSpendControls({ maxAmountPerPayment: "$50" })` (or `spendControls.maxAmountPerPayment`), then `wrapFetchWithPayment(fetch, client)`.
- **Coinbase AgentKit:** set `maxUsdcPrice` (or the kit's USDC price cap) to about `50`.

Do not disable spend controls entirely; raise them only as high as your agent is allowed to spend.

## 3. x402 paid endpoints

No account; pay per call in USDC on Base. Call without payment to get a 402 with requirements, then retry with `X-PAYMENT`.
- `GET https://stabledomains.net/api/v1/availability/bulk?domains=a.com,b.ai`: availability + USDC price for up to 100 names ($0.10)
- `GET https://stabledomains.net/api/v1/valuation?domain=acme.ai`: valuation range, availability and register price ($0.02)
- `GET https://stabledomains.net/api/v1/alerts?domain=x.com&webhook_url=https://…`: drop alert for one domain, webhook or email, no account ($0.01)
- `GET https://stabledomains.net/api/v1/drops/full`: up to 500 expiring/dropped rows with all metrics ($0.01)
- `GET https://stabledomains.net/api/v1/radar/full`: up to 1000 radar rows with quality and all signals ($0.02)
- Domain orders themselves can also be paid via x402 (see above).

## 4. Drop radar and feeds (free)

- `GET https://stabledomains.net/api/v1/radar` (page https://stabledomains.net/radar, presets e.g. https://stabledomains.net/radar/short-brandable)
- `GET https://stabledomains.net/api/v1/drops` (page https://stabledomains.net/expiring)
- Params: sort=quality|available|value|price|length|drops|new|brand|backlinks|domain|age|captures|pagerank (also quality_asc / price_desc), order=asc|desc, tld, status, min_quality, max_price, min_len, max_len, drops_within_days, available_only=1, limit, cursor (use `next_cursor`).
- Feeds: https://stabledomains.net/radar/feed.json (JSON Feed), https://stabledomains.net/radar/rss.xml (RSS) for any filter.
- Alerts: `POST https://stabledomains.net/api/v1/radar/alerts {filters, webhook_url?|email?}`; per-domain: `POST https://stabledomains.net/api/v1/watch {domain, webhook_url?, email?}`.
- Lifecycle check: `GET https://stabledomains.net/api/v1/tools/dropping?domain=example.com`.

## 5. Auth

Instant agent signup (no form): `curl -X POST https://stabledomains.net/api/v1/agents/signup` → `{api_key}` (MCP `agent_signup`). Guest tier, 30 req/min, until claimed: email via `POST /api/v1/auth/email-start {email}` with the key as Bearer (a human clicks the link), or wallet via SIWE `POST /api/v1/auth/verify {message,signature,claim:true}` with the key as Bearer.


- None: search, quotes, tools, feeds, keyless orders (402 / x402).
- API key: `Authorization: Bearer sd_live_…`. Create one in the dashboard (https://stabledomains.net/dashboard), via `POST /api/v1/keys`, or by signing in with a wallet (SIWE: `POST /api/v1/auth/verify` with `issue_api_key: true`).
- OAuth 2.1 (MCP connectors): authorization code + PKCE, dynamic client registration. Metadata: https://stabledomains.net/.well-known/oauth-authorization-server and https://stabledomains.net/.well-known/oauth-protected-resource.

## Quotas and limits

- GET /api/v1/search, /api/v1/quote: 60/min per IP anonymous; per API key: the key's limit (default 600/min, guest-tier signup keys 30/min)
- POST /api/v1/orders: min(key limit, 60)/min per key or account
- POST /api/v1/cart: 10/min per key or account
- POST /api/v1/transfers: 10/min per key or account
- /api/v1/suggest (free tier): 10/min per IP, 24 checks, top 10 results
- /api/v1/radar (free): 30/min per IP
- /api/v1/drops (free): 30/min per IP
- POST /api/v1/radar/alerts, /api/v1/watch: 10/min per IP
- /api/v1/aftermarket: 60/min per IP
- /api/v1/agents (registry read): 120/min per IP; submissions 5/hour per account
- POST /api/v1/agents/signup: 3/hour and 10/day per IP
- POST /api/v1/auth/guest: 10/min per IP
- GET /api/v1/auth/nonce (SIWE): 30/min per IP
- POST /api/v1/auth/email-start: 5 per 10 min per IP, 3 per 10 min per email address
- POST /api/v1/auth/email-code: 20 per 10 min per IP, 10 per 10 min per email address
- OAuth dynamic client registration: 30 per 10 min per IP
- API keys: max 10 active per account
- x402 paid endpoints: no rate limit beyond payment; each call is paid
- Exceeding a limit returns 429 with error.code rate_limited and details.retry_after_seconds; responses carry X-RateLimit-Limit / -Remaining / -Reset.

## Errors

JSON `{error:{code,message,...}}`. Common codes: invalid_request, domain_taken, availability_unknown, payment_required (402), checkout_unavailable, rate_limited (429). Always send `Idempotency-Key` on POST /orders; retries with the same key return the same order.