API reference

Every route, field and answer is also in the machine-readable OpenAPI 3.1 file. Prices are on the pricing page.

• Basics
• Paid routes
• The free check before payment
• Delegation: your zone's own nameservers
• Paying without an account
• Cashu mints
• Failures after payment
• Authentication
• NIP-98 signed requests
• API keys
• Orders with an account
• Zones and records
• DNSSEC
• Dynamic DNS
• Secondary DNS
• Outside secondaries for hosted zones
• LNURL renewals
• Expiry, grace and reminders
• Account features
• Domain registration
• Limits and quotas
• Rate limits
• Errors
• Status and discovery

Basics

• Request and response bodies are JSON (Content-Type: application/json), at most 256 KiB.
• Times are UTC in ISO 8601 (2026-11-20T10:00:00Z). Quota days and months are UTC.
• Errors look like {"error": {"code": "...", "message": "...", "status": 409, "detail": {...}}} with Cache-Control: no-store; see errors. Every answer carries an X-Request-Id.
• Zone names are ASCII (internationalized names as xn--). Hostnames are the single label under dynkite.com (myhost or myhost.dynkite.com).

Paid routes

All are POST with a JSON body, on https://api.satsdns.com.

The body must hold exactly the fields shown (ns_ticket and previous_token are optional and only for the create routes). HEAD or GET on /v1/zones/create/30d, /v1/zones/renew/30d, /v1/ddns/create/30d and /v1/secondary/create/30d returns a shared 402 that only shows the price (for directories); to buy, POST your body and pay your own 402. HEAD and GET on the other paid routes are 405.

The free check before payment

Before any invoice is made, the request is checked. A request that would fail gets its error and no invoice. The same checks run again after payment.

The delegation check asks the parent zone's authoritative servers directly (no resolver cache), so you can order as soon as your registry publishes the new NS records. It gives up after 8 seconds (503 delegation_check_unavailable, retry).

Delegation: your zone's own nameservers

Each zone is served under its own pair of nameserver names, for example k7qd.ns1.satsdns.com and m3x9.ns2.satsdns.com. Pointing a domain at us therefore cannot let anyone else take it over: only the party that got the pair, and made the registry list it, can create the zone.

1. Send the create request without payment: {"zone": "example.org"}. The free check answers 409 delegation_missing with detail.expected_ns (your pair), detail.ns_ticket (a secret, shown once) and detail.ns_offer_expires_at (48 hours; an account's pair 7 days). Register the domain first: for a name its registry does not know, the answer has no expected_ns (detail.registered false). At most two open pairs per network and zone, and 20 new pairs a day per network (429 ns_offer_limit).
2. At your registrar, set exactly those two names as the domain's nameservers (other providers' nameservers may stay listed). Wait until the registry publishes them.
3. Send the request again with the ticket: {"zone": "example.org", "ns_ticket": "nst_..."}. Now you get the 402; pay as below. The create answer lists the zone's nameservers.

Keep the ticket: asking again without it gives a new pair (at most two per network and zone), and a pair the registry already lists is never given to anyone else. With an account, the pair belongs to the account and no ticket is needed (the order check, pay: "check", shows it). Domains registered through SatsDNS can be hosted only by their owner's account and keep ns1.satsdns.com and ns2.satsdns.com.

When a zone is removed (deleted or expired), first remove its NS records at your registrar. For 90 days, and for as long as the registry still lists the zone's nameservers, only its last owner can host the name again: the same account, or the old zone token sent as "previous_token" in the create body; it gets the same nameservers back.

Paying without an account

A valid request without payment gets 402 Payment Required with two ways to pay in the same answer.

L402 (Lightning)

1. The WWW-Authenticate header holds L402 macaroon="...", invoice="lnbc...".
2. Pay the invoice with any Lightning wallet and keep the preimage (64 hex characters).
3. Repeat the same request with Authorization: L402 <macaroon>:<preimage>.

The invoice and macaroon are valid for 1 hour and pay one request on that route and method. When the service's own Lightning node cannot make an invoice, an accepted Cashu mint issues it and X-L402-Invoice-Issuer names the mint; pay it the same way. If no invoice can be made at all, the 402 offers Cashu only, with Retry-After.

curl -i -X POST https://api.satsdns.com/v1/ddns/create/30d \
  -H "Content-Type: application/json" -d '{"hostname": "myhost"}'
# pay the invoice from www-authenticate, then:
curl -X POST https://api.satsdns.com/v1/ddns/create/30d \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" -d '{"hostname": "myhost"}'

Cashu (NUT-24)

The 402 also carries X-Cashu: creqA..., a payment request with the amount, the unit (sat) and the accepted mints. Repeat the request with a cashuB... token in the X-Cashu header.

A token that is short, or from a mint that is not accepted right now, gets 400 with an X-Cashu-Error header and is not spent. No change is returned on overpayment. The current list is always in /.well-known/l402-services.

Failures after payment

If a paid request is refused after payment (for example the zone was taken by someone else in between, or the delegation changed), the answer is 422 with the reason, or 503 if our side failed. Either way:

• L402: the answer says X-L402-Retry: allowed, and the same proof works once more on the same route and method within the hour (fix the body and try again).
• Cashu: the answer carries a refund token for the price in X-Cashu-Refund. Redeem it promptly: until you do, anyone who sees it can take it.

At most one retry or refund per payment and 10 per IP address per hour, within a service-wide hourly budget. If no automatic refund could be made, ask through the contact page.

If the answer to a paid zone create is lost (a timeout), send the identical request again with the same L402 proof within 15 minutes: you get the zone back with a new token (an earlier one, if it arrived, stops working). A create whose checks run too long is refused with 422 create_timeout rather than finished late.

Authentication

Management routes are free per call. Each accepts any of these credentials:

• Tokens and keys are 256-bit random values, shown once and stored only as a hash. We cannot show them again. Rotate a token with POST /v1/zones/{zone}/token or POST /v1/ddns/{hostname}/token; the old one stops working at once.
• A wrong token and an unknown zone get the same 401.
• Sensitive actions need a fresh NIP-98 signature (a session or API key gets 401 step_up_required): creating or revoking API keys, setting a recovery key, transfers, recoveries, rotating or disabling a token, deleting a zone, hostname or the account, asking for a refund, changing secondary primaries, TSIG keys or outside secondaries. A zone's own token may also do the actions for that zone. A token acts for the account that owns its object: while that account is banned the token is read-only.
• A token-bought zone can be claimed into an account: POST /v1/account/claim {"zone": "example.org", "token": "jdz_..."} (NIP-98). The token keeps working unless the owner disables it (PATCH /v1/zones/{zone}/settings {"token_disabled": true}, NIP-98).

NIP-98 signed requests

An account is a Nostr public key. It is created when it first orders, claims or sets something; reading GET /v1/account creates nothing. To sign a request, make a kind 27235 event with empty content and these tags, sign it, base64-encode the JSON and send Authorization: Nostr <base64>:

• ["u", "https://api.satsdns.com/v1/account/zones"]: the exact URL you call, scheme, host, path and query byte for byte (no port, no fragment). An event signed for one host does not work on another.
• ["method", "POST"]: the HTTP method in upper case.
• ["payload", "<sha256 hex of the raw body>"]: required on every method except GET and HEAD. Hash the exact bytes you send; an empty body hashes to e3b0c442...b855.

created_at must be within 60 seconds of our clock, and each event id is accepted once. A failed check is 401 with a code such as auth_expired, auth_replayed, auth_url_mismatch, auth_method_mismatch, auth_payload_mismatch or bad_signature, plus a Date header and detail.server_time so you can correct your clock. In JavaScript, nostr-tools' nip98.getToken(url, method, sign, true, payload) makes the header; send exactly the body string it hashed.

API keys

POST /v1/account/keys        (NIP-98)
{"label": "ci", "scope": {"objects": ["zone:example.org", "host:myhost"], "access": "write"},
 "expires_at": 1798761600}

• objects: ["*"] or a list of zone:NAME and host:LABEL. access: read or write (records, dynamic-DNS updates).
• Keys can order renewals and extra queries for objects in their scope, but never new zones or hostnames.
• At most 20 live keys per account; optional expiry up to 2 years ahead. The key is shown once. Revoke with DELETE /v1/account/keys/{id}.
• A key follows the current owner: a zone transferred to another account drops out of the old owner's keys.

Orders with an account

POST /v1/account/orders      (NIP-98, API key for renewals, or the dashboard)
Idempotency-Key: 6f3c0f0e-...          (optional; same key + same body within 24 h = same answer;
                                        409 idempotency_in_progress while the first is still running)
{"product": "zone_create", "period": "1y", "zone": "example.org", "pay": "onchain"}

The answer is 201 {"invoice": {...}} with lightning.bolt11 (valid 15 minutes) and/or onchain.address and onchain.bip21 (valid 24 hours). Poll GET /v1/invoices/{id}: when the state is fulfilled, result holds the zone or hostname status and, once, its token.

• On-chain: pay the exact amount to the new address. A payment seen in the mempool before the deadline still counts; the order counts as paid, and runs, once the payment has 3 confirmations. The invoice shows each payment's confirmations meanwhile (onchain.outputs[].confirmations, onchain.min_confirmations).
• Paid in time and in full: the order runs. Paid late (Lightning settled after expiry, or an on-chain payment first seen after the deadline) or short: the order does not run, and the money is refundable on request. Overpaid: the order runs and the extra is kept unless you ask for it back.
• Refunds: POST /v1/account/refunds {"invoice_id": "inv_...", "rail": "lightning", "destination": "name@example.com"} (NIP-98; on-chain: "rail": "onchain" and a bc1 address). Each is reviewed and paid by hand, from 1,000 sats, with the network fee deducted; refunds of on-chain payments wait for 3 confirmations. Amounts below 1,000 sats (for example a late or short payment on a 200- or 500-sat order) cannot be refunded. GET /v1/account/refunds shows their state.
• GET /v1/account/invoices lists your invoices; GET /v1/account/ledger lists the payments, orders and refunds of the account.

Zones and records

• Types: A, AAAA, CNAME, TXT, MX, SRV, CAA, HTTPS, SVCB, TLSA, NS (below the apex only, to delegate a subdomain) and DS (only where NS is). SOA, the apex NS and DNSSEC records are managed for you.
• Names: @ or empty for the apex, a relative name (www) or a full name inside the zone. * only as the leftmost label. Underscores are allowed (_acme-challenge, _443._tcp).
• Content is zone-file text. Names in content are absolute (mail.example.org means mail.example.org.). TXT may be unquoted; long values are split into 255-byte strings for you.
• TTL from 60 to 86,400 seconds, default 3,600. At most 100 records per record set.
• Rules: a CNAME stands alone and never at the apex; DS needs NS at the same name; below a delegated subdomain only glue (A, AAAA).
• Every change is applied at once on both nameservers.

curl -X PATCH https://api.satsdns.com/v1/zones/example.org/records \
  -H "Authorization: Bearer jdz_..." -H "Content-Type: application/json" -d '{"rrsets": [
    {"name": "@",   "type": "MX",  "ttl": 3600, "records": ["10 mail.example.org"], "changetype": "REPLACE"},
    {"name": "@",   "type": "TXT", "ttl": 3600, "records": ["v=spf1 mx -all"],      "changetype": "REPLACE"},
    {"name": "old", "type": "A",                                                     "changetype": "DELETE"}]}'

DNSSEC

• Every hosted zone is signed from the moment it is created: one combined key (CSK), ECDSA P-256 (algorithm 13), online signing, NSEC3 per RFC 9276 (SHA-1, no opt-out, 0 extra iterations, no salt). CDS and CDNSKEY records are published.
• Denial of existence reveals hashes of the names in the zone: NSEC3 stops simple zone walking, but short or common names can be guessed from the hashes offline. Do not treat a name as secret.
• GET /v1/zones/{zone}/dnssec returns ds (SHA-256 DS records for your registrar), cds, cdnskey, dnskey, algorithm, a short how-to and parent_ds: missing, matching or mismatch, read from the parent zone.
• To turn validation on, enter the DS record (or the DNSKEY, if your registrar asks for the key) at your registrar. Do not rely on the registry picking up CDS by itself.
• Before you move a zone away or delete it, remove the DS record at your registrar and wait for its TTL. A DS that points at keys no longer served makes validating resolvers reject your domain.
• Secondary zones are served as your primary signs them (pre-signed) or unsigned; you manage their keys and DS.

Dynamic DNS

A hostname myhost.dynkite.com carries A, AAAA, TXT and HTTPS records, and a TXT record at _acme-challenge.myhost.dynkite.com for ACME DNS-01. All have a 60-second TTL.

Hostnames and their addresses are public: anyone who knows or guesses a hostname can look up its addresses, and dynkite.com's DNSSEC (NSEC3, no salt, no extra iterations) gives out a hash of every hostname, from which short or common ones can be guessed. Use a long random hostname if it should be hard to find.

Buy

curl -i -X POST https://api.satsdns.com/v1/ddns/create/30d \
  -H "Content-Type: application/json" -d '{"hostname": "myhost"}'
# 402: pay 200 sats (L402 or Cashu) and repeat. The 201 answer holds "token": "jdh_..." (shown once).

Update with JSON

# Point A at the address this request comes from, and set an IPv6 address:
curl -X POST https://api.satsdns.com/v1/ddns/myhost/update \
  -H "Authorization: Bearer jdh_..." -H "Content-Type: application/json" \
  -d '{"a": "auto", "aaaa": "2001:db8::10"}'
#   {"changed": true, "records": {...}, "hostname": "myhost.dynkite.com.", "ttl": 60}

• Fields: a, aaaa, txt, https, acme_txt. A value or a list of up to 10 values replaces the set, null deletes it, and a field you leave out stays as it is.
• "auto" (for a or aaaa) means the address the request comes from. Call over IPv4 for a and over IPv6 for aaaa.
• Only public (globally routed) addresses are accepted, also through "auto". Private (10/8, 172.16/12, 192.168/16), loopback, link-local, shared CGNAT (100.64/10), IPv6 unique-local (fc00::/7), multicast, documentation and other reserved addresses, and IPv6 forms that carry such an IPv4 address, are refused with 400 address_not_public (detail.reason says which kind); nothing is changed. A public name that points into a local network can be used against the visitors' own devices (DNS rebinding).
• Unchanged values are not written and do not count against the 1,000 changes a day.
• GET /v1/ddns/{hostname} shows the status, the end date and the current records.

ACME DNS-01

curl -X POST https://api.satsdns.com/v1/ddns/myhost/update \
  -H "Authorization: Bearer jdh_..." -H "Content-Type: application/json" \
  -d '{"acme_txt": "gfj9Xq...Rg85nM"}'
# ...let the CA validate, then remove it:
curl -X POST https://api.satsdns.com/v1/ddns/myhost/update \
  -H "Authorization: Bearer jdh_..." -H "Content-Type: application/json" -d '{"acme_txt": null}'

Routers, ddclient and inadyn (dyndns2)

GET https://api.satsdns.com/nic/update?hostname=myhost&myip=203.0.113.7 with HTTP Basic authentication: any user name, the hostname token as the password. Leave out myip to use the caller's address; give IPv4 and IPv6 separated by a comma. Answers are plain text: good <ip>, nochg <ip>, badauth, dnserr (not an IP address, or not a public one), abuse (suspended, over the daily limit, or the owning account is banned) or 911.

curl -u "user:jdh_..." "https://api.satsdns.com/nic/update?hostname=myhost"
#   good 203.0.113.7

# /etc/ddclient.conf
protocol=dyndns2
ssl=yes
server=api.satsdns.com
login=myhost
password='jdh_...'
myhost.dynkite.com

HTTPS only: the token travels in the request. Plain http gets badauth (401) and no redirect; a client set to http has already sent its token in clear, so switch it to https and rotate the token (POST /v1/ddns/{hostname}/token). Updates are limited to 12 a minute per address.

Secondary DNS

You run the primary. Our ns1 transfers the zone from it with a TSIG key; ns2 transfers from ns1. Delegate the domain to the zone's own pair of nameservers first, as for a hosted zone (delegation; your own servers may be listed too).

Create

POST /v1/secondary/create/30d      (paid route, or an order with "product": "secondary_create")
{"zone": "example.net", "primaries": ["198.51.100.7"]}

• primaries: 1 to 4 IPv4 addresses (not host names), port 53, public unicast only. Private, reserved and documentation addresses and our own addresses are refused (400 bad_primary with detail.reason). IPv6 primaries are not offered yet (400 ipv6_primary_unsupported). At most 20 zones per primary address.
• The answer holds, once each: the zone token and tsig {"name", "algorithm": "hmac-sha256", "secret"}. We do not keep the secret. It also lists transfer_source_ips, notify_to and ready-made config_examples for BIND, Knot, NSD and PowerDNS.

Set up your primary

1. Install the TSIG key and allow zone transfers (AXFR and IXFR) to that key from the transfer_source_ips.
2. Send NOTIFY to the notify_to address, from the primary address you registered. NOTIFY from any other address is refused, and at most 10 a minute per zone are accepted.
3. The first transfer starts within about a minute. Until then the status shows health: pending.

# BIND (named.conf), with the values from the answer
key "jd-123-abcdef" { algorithm hmac-sha256; secret "<secret>"; };
zone "example.net" {
    type primary;
    file "example.net.zone";
    notify explicit;
    also-notify { <notify_to>; };
    allow-transfer { key "jd-123-abcdef"; };
};

Run it

• GET /v1/zones/{zone}/secondary: primaries, health (pending, ok, failing, refused_primary, too_large, stale, suspended), serial, last transfer, last error, record count.
• PUT /v1/zones/{zone}/secondary {"primaries": [...]} changes the primaries (and brings back a zone suspended as stale once your primary works again).
• POST /v1/zones/{zone}/secondary/tsig makes a new key and returns its secret once. Transfers fail until your primary has the new key.
• Records come from your primary only: the record routes answer 409 zone_is_secondary.
• Owners get a Nostr message after 24 hours of failed transfers, and when a signed zone's signatures are less than 3 days from expiry. After 7 days of failures, or once the data is older than the zone's SOA expire, the zone is suspended as stale so we do not serve data you abandoned.
• Zones above 20,000 records or 16 MiB per transfer are not served (too_large).
• Renew with /v1/zones/renew/..., an order (zone_renew) or the zone's Lightning address. The query quota and grace period are the same as for hosted zones.

Outside secondaries for hosted zones

A hosted zone may also be served by up to 2 other providers' secondaries, listed as extra nameservers at your registrar:

PUT /v1/zones/{zone}/xfr-peers
{"peers": [{"address": "192.0.2.25", "tsig": true}, {"address": "198.51.100.40", "tsig": false}]}

With "tsig": true a key is made for that peer and shown once; with false the peer may transfer the zone from its address without a key (for providers that cannot use TSIG). The peers get NOTIFY on every change. The same address rules as for primaries apply. GET on the same route lists them.

LNURL renewals

POST /v1/zones/{zone}/lnurl      (token, owner or write key; also /v1/ddns/{hostname}/lnurl)
#   {"pay_id": "abcdefghijkm", "lnurl": "LNURL1...", "lightning_address": "abcdefghijkm@pay.satsdns.com",
#    "rate": {"sat_per_30_days": 500, "min_sat": 100, "max_sat": 100000}, ...}

• Any Lightning wallet can pay the address or the LNURL. Each payment from 100 to 100,000 sats extends the zone pro rata: 500 sats = 30 days for zones, 200 sats = 30 days for hostnames, counted from the current end date.
• The address stops offering amounts beyond the 1,125-day limit, and refuses payments while the zone is suspended or past grace.
• It works for zones bought without an account, so anyone you give the address to can keep the zone running. GET shows the current address; POST again replaces it (the old one stops working).
• Renewal reminders to accounts include this address.

Expiry, grace and reminders

• Every status answer shows expires_at, days_left and grace_ends_at.
• After expires_at the status is grace for 7 days: the zone keeps answering, can still be edited and renewed, and every status answer carries a warning.
• After the grace period the zone (or the hostname's records) is removed, and the name can be bought again by anyone.
• Nothing renews by itself. Accounts get Nostr direct messages (NIP-17; NIP-04 as well if you turn on notify_nip04 with PATCH /v1/account) 14, 7 and 1 days before the end, when grace starts, 2 days before removal and at removal. Zones without an account get no messages: read days_left.

Account features

Recovery by token: if someone else's account owns a zone and you hold its token, a claim starts a 72-hour recovery; the owner is told and can cancel it (and should then rotate or disable the token). No key, no token and no recovery key: the zone keeps running until it expires; we cannot hand it over.

Domain registration

.com, .net and .org names, registered with our sponsoring registrar, Global Domain Group LLC (IANA ID 3956), under the registration agreement. Domains are ordered only with an account, in the dashboard (Register domain) or with POST /v1/account/orders; they are not sold on the L402/Cashu routes. The dashboard's Domains screens also cover renewal, nameservers, DNSSEC, lock, transfer codes and registrant changes. WHOIS privacy is always on. Prices: pricing.

Check and quote (free)

GET /v1/domains/check?domain=example.com&years=1

Answers available, premium, prices_sat (register, or transfer when the name is taken, and renew) and hosting_addon_sat. The answer is cached for 60 seconds. 6 checks a minute per address.

Order

POST /v1/account/orders      (NIP-98 or an API key)
{"product": "domain_register", "period": "1y", "domain": "example.com",
 "registrant": {"name": "Ada Lovelace", "email": "ada@example.net", "phone": "+44.2071234567",
                "address1": "1 Example Street", "city": "London", "postal_code": "N1 1AA", "country": "GB"},
 "attestation": true, "nameservers": ["ns1.example.net", "ns2.example.net"], "host_zone": false,
 "pay": "lightning"}

• Before any invoice the order is checked for free: the name, our blocked and protected names, the registrant data, the attestation, the daily limits (one new registration or transfer a day per account and per registrant email address), availability at the registrar and the price.
• Pay the invoice as for every account order. When it is fulfilled, result holds the domain status and, once, the domain token (jdd_...). The registration may still be completing at the registrar: result.order_state and GET /v1/domains/{domain} show pending until it is done.
• If our registrar balance is short, the paid order waits for up to 24 hours (waiting_for_funding); after that it fails and is refundable. Other failures before registration are refundable too; see the registration agreement.
• A new registration starts on our nameservers. About 3 hours later (hold_until), after a phishing-list check, your nameservers (nameservers_pending) are set or the hosted zone goes live.
• The registrar emails the registrant a link to confirm the email address. If it is not used within 15 days, the registrar suspends the domain until it is; registrant_verification shows the state and deadline.

Manage

Management routes accept the domain token (Authorization: Bearer jdd_...), NIP-98 by the owning account, an API key with domain: scope, or a dashboard session. Actions marked "fresh signature" need a new NIP-98 signature (401 step_up_required) when you use an account. The domain token is as strong as the owner's key: whoever holds it can change nameservers and DNSSEC, unlock the domain, change the registrant and replace the token, so keep it as safe as your key. The one exception: when an account owns the domain, only the owner's NIP-98 signature gets the transfer code.

Renewal and expiry

• Nothing renews automatically. Renew with domain_renew (1 to 10 years, at most 10 years ahead in total). The owning account gets Nostr direct messages 30, 7 and 1 days before expires_at and at expiry.
• At expiry the registrar puts the domain on hold and it stops resolving. Status expired: still renewable through the API until renew_until (25 days after expiry).
• Status redemption: past renew_until. A restore is done by hand: ask through the contact page. See renewal, expiry and restore.

Domain errors

Abuse reports

POST /v1/abuse/reports (no account) with {"domain", "category", "details", "contact"} reports abuse of a domain, zone or hostname served or sold here now; any other name (also one removed, transferred away or deleted) gets 404 not_ours. See the abuse page.

Limits and quotas

An account becomes established by itself after 30 days and 10,000 sats paid in total. If you need more, ask through the contact page.

Rate limits

Per IPv4 address or IPv6 /64. Over the limit: 429 rate_limited with Retry-After.

Service-wide limits also apply. Limits per address and per network are checked first, and a refused request counts against none of the others. Do not spread requests over many addresses to get around these.

Errors

LNURL routes answer in the LNURL format ({"status": "ERROR", "reason": "..."} with HTTP 200), as wallets expect.

Status and discovery

• GET /healthz: {"ok": true, ...} when the API, its database and the DNS servers are up; 503 otherwise.
• GET /v1/info: nameservers, the dynamic-DNS domain, prices, periods, grace, limits, record types, DNSSEC settings, payment options and the secondary transfer addresses.
• GET /.well-known/l402-services: the paid routes, prices and accepted Cashu mints with their fees.