# SatsDNS

> Authoritative DNS hosting for domains you already own (DNSSEC-signed, JSON record API, 60 s minimum TTL), secondary DNS for zones on your own primary, dynamic-DNS hostnames under dynkite.com, and .com/.net/.org domain registration. Paid in sats per order: L402 (Lightning) or Cashu NUT-24 on the paid API routes with no account, or with a free Nostr account (NIP-98 signed requests) a Lightning invoice per order, or a bitcoin address for orders of at least 5,000 sats. No email or KYC for DNS hosting, no stored balance, no auto-renew. API: https://api.satsdns.com . Nameservers: ns1.satsdns.com, ns2.satsdns.com.

Prices in sats (POST with a JSON body on https://api.satsdns.com):

- /v1/zones/create/30d, /v1/zones/create/1y (hosted zone; body {"zone": "example.org", "ns_ticket": "nst_..."}, see below): 500 / 5,000
- /v1/zones/renew/30d, /v1/zones/renew/1y (hosted or secondary zone; no token needed): 500 / 5,000
- /v1/zones/queries/1m (1,000,000 more queries this UTC month): 200
- /v1/secondary/create/30d, /v1/secondary/create/1y (body {"zone": "example.net", "primaries": ["198.51.100.7"], "ns_ticket": "nst_..."}): 500 / 5,000
- /v1/ddns/create/30d, /v1/ddns/create/1y (hostname under dynkite.com; body {"hostname": "myhost"}): 200 / 2,000
- /v1/ddns/renew/30d, /v1/ddns/renew/1y (no token needed): 200 / 2,000
- Lightning address per zone or hostname (LNURL-pay on pay.satsdns.com): any amount from 100 sats, pro rata (zone 500 sats = 30 days, hostname 200 sats = 30 days)
- Nostr account, management routes, /v1/info, /healthz: free

Each zone gets its own pair of nameservers under ns1.satsdns.com and ns2.satsdns.com (for example k7qd.ns1.satsdns.com and m3x9.ns2.satsdns.com). First POST the create body without payment, {"zone": "example.org"}: the free check answers 409 delegation_missing with detail.expected_ns (your pair), detail.ns_ticket (secret, shown once) and detail.ns_offer_expires_at (48 hours; 7 days for an account's pair). The domain must be registered first: for a name its registry does not know, the answer has no expected_ns (detail.registered false). Set exactly that pair at the registrar (other nameservers may be listed too), wait for the registry, then POST again with {"zone": "example.org", "ns_ticket": "nst_..."} to get the 402. Asking again without the ticket gives another pair (at most two per network and zone, and 20 new pairs a day per network); a pair the registry already lists is never handed to anyone else. Account orders need no ticket (the pair belongs to the account; pay "check" shows it). Domains registered through SatsDNS can be hosted only by their owner's account. When you delete a zone, remove its nameservers at the registrar: for 90 days, and while the registry still lists them, only the last owner can host the name again (same account, or the old token as "previous_token" in the create body). Every paid request is checked for free first (name, reserved names, phishing list, clash with another zone, delegation, hostname rules); a request that would fail gets its 4xx error and no invoice.

Paying without an account: the valid unpaid request gets HTTP 402 with `WWW-Authenticate: L402 macaroon="...", invoice="..."` (pay, then repeat with `Authorization: L402 <macaroon>:<preimage>`; valid 1 hour, one request on that route) and `X-Cashu: creqA...` (repeat with `X-Cashu: cashuB...`). Cashu at list price: https://mint.minibits.cash/Bitcoin, https://21mint.me, https://mint.routstr.com, https://forge.flashapp.me, https://mint.cashu.chat; plus the mint's swap fee: https://mint.coinos.io, https://mint.macadamia.cash (send with include-fees). No change on overpayment. A refusal after payment is 422 (or 503) with `X-L402-Retry: allowed` (same proof works once more within the hour) or a refund token in `X-Cashu-Refund`.

The create answer holds a management token, shown once: jdz_... for zones, jdh_... for hostnames. Use `Authorization: Bearer <token>` on management routes, which are free per call:

- GET /v1/zones/{zone} (status, expires_at, days_left), GET/POST/PATCH /v1/zones/{zone}/records, PUT/DELETE /v1/zones/{zone}/records/{name}/{type}, GET /v1/zones/{zone}/dnssec (DS for the registrar), POST /v1/zones/{zone}/token (rotate), DELETE /v1/zones/{zone}
- Record set body: {"name": "www", "type": "A", "ttl": 300, "records": ["203.0.113.10"]}. Types A, AAAA, CNAME, TXT, MX, SRV, CAA, HTTPS, SVCB, TLSA, NS (below the apex), DS (with NS). TTL 60 to 86,400. 1,000 records per zone, 1,000 record writes per UTC day.
- POST /v1/ddns/{hostname}/update with {"a": "auto", "aaaa": "...", "txt": "...", "https": "...", "acme_txt": "..."} (null deletes; "auto" = caller's address; public addresses only, private/loopback/link-local/CGNAT/unique-local/reserved get 400 address_not_public); dyndns2: GET /nic/update?hostname=myhost&myip=... with Basic auth (any user, the token as password); https only, plain http gets badauth (401) and no redirect. TTL 60.
- Secondary zones: the create answer also holds a TSIG key (hmac-sha256, shown once), transfer_source_ips, notify_to and config examples for BIND, Knot, NSD and PowerDNS. Allow AXFR/IXFR to the key, send NOTIFY to notify_to from a registered primary. IPv4 primaries only for now.

Accounts: an account is a Nostr public key. Sign requests with NIP-98 (`Authorization: Nostr <base64 kind-27235 event>`; u tag = exact URL with query, method tag, payload tag = sha256 of the body for non-GET; 60 s window; each event once). Order with POST /v1/account/orders {"product": "zone_create|zone_renew|zone_queries|secondary_create|ddns_create|ddns_renew", "period": "30d|1y", "zone"|"hostname": "...", "pay": "lightning|onchain|both|check"}; poll GET /v1/invoices/{id} until "fulfilled". Lightning invoices last 15 minutes; on-chain needs the exact amount within 24 hours and counts as paid at 3 confirmations. Paid late or short: not run, refund on request. Claim a token-bought zone with POST /v1/account/claim. Scoped API keys (jdk_) with POST /v1/account/keys. Dashboard: https://app.satsdns.com .

Domain registration (.com, .net, .org; account orders only; sponsoring registrar Global Domain Group LLC, IANA ID 3956; agreement https://satsdns.com/registration-agreement): free quote with GET /v1/domains/check?domain=example.com&years=1. Order with POST /v1/account/orders {"product": "domain_register|domain_renew|domain_transfer", "period": "1y".."10y", "domain": "example.com", "registrant": {"name", "email", "phone": "+CC.NUMBER", "address1", "city", "postal_code", "country"}, "attestation": true, "nameservers": "ours" or a list, "host_zone": true|false, "pay": "lightning|onchain|both|check"}. The registrant must be the real person or organization you act for, with real contact data (no placeholders); attestation true means "I am authorised by the named registrant to register this domain for them, and the registrant accepts the registration agreement." List prices in sats: .com 18,000 register/renew/transfer; .net 20,000; .org 13,500 register, 17,500 renew/transfer; +3,000 for a year of hosting (host_zone); each order is quoted and never below list. WHOIS privacy always on. The registrant must confirm the registrar's email within 15 days or the domain is suspended (not refunded). No auto-renew; renewable until 25 days after expiry. Domain token jdd_... once in the invoice result; manage with /v1/domains/{domain} (status, nameservers, dnssec, lock, auth-code, registrant). People can order and manage domains in the dashboard too (https://app.satsdns.com, Register domain and Domains). Completed registrations are final.

Expiry: renewals add to the current end date (at most 1,125 days ahead). 7-day grace after expiry (still answering and editable), then the zone is removed. Nothing renews automatically; accounts get Nostr DM reminders. Each zone includes 1,000,000 queries per UTC month; over it the zone is flagged and the owner told, its records keep answering, and above 120% or after 3 days the operator reviews it (query volume never withdraws records automatically; only answers with data are counted).

## Docs

- [Agent skill](https://satsdns.com/skill.md): step-by-step ordering and management for agents
- [API reference](https://satsdns.com/docs): payment, authentication, records, DNSSEC, dynamic DNS, secondary DNS, limits, errors
- [Pricing](https://satsdns.com/pricing): products, periods and payment rails
- [OpenAPI 3.1](https://satsdns.com/openapi.yaml): machine-readable description of every public route
- [Service info](https://api.satsdns.com/v1/info): free JSON with nameservers, prices, periods and limits
- [Status](https://api.satsdns.com/healthz): free health check
- [Payment discovery](https://api.satsdns.com/.well-known/l402-services): free JSON with paid routes, prices and accepted mints

## Policies

- [Terms of service](https://satsdns.com/terms)
- [Domain registration agreement](https://satsdns.com/registration-agreement)
- [Acceptable use](https://satsdns.com/acceptable-use)
- [Privacy](https://satsdns.com/privacy)
- [Report abuse](https://satsdns.com/abuse): abuse@satsdns.com or POST /v1/abuse/reports
- [Contact](https://satsdns.com/contact)

## Optional

- [Home](https://satsdns.com/): overview and example
- [NIP-98](https://github.com/nostr-protocol/nips/blob/master/98.md): HTTP auth with Nostr events
- [NUT-24](https://github.com/cashubtc/nuts/blob/main/24.md): Cashu payments over HTTP 402