How to Get Started with myaddr.tools and Claim a Subdomain

Claiming a name on myaddr.tools takes seconds and requires no account: visit the site, pick an available name, and you receive a secret key. That key is the only credential for the name — whoever holds it controls the DNS records, and if you lose it you lose the name. Once you have the key, you manage records through the HTTP-based Update API.

Claiming your name

Go to myaddr.tools and claim the name you want. If it is available, the service returns a secret key. There is no signup, email confirmation, or password to manage.

Two things follow from that design:

• Store the key somewhere safe immediately. There is no recovery path described — losing the key means losing control of the name.
• Treat the key as a password. Anyone who has it can change or delete your records.

Your name resolves across several domains at once, all pointing to the same records:

All subdomains of the above also resolve, so you can use hosts like ipv4.your-name.myaddr.tools or ipv6.your-name.myaddr.tools.

Updating DNS records with the Update API

The endpoint is https://myaddr.tools/update. It is deliberately forgiving:

• GET, POST, and PUT are treated as equivalent update requests.
• Parameters are read from the URL query string and from POST/PUT bodies.
• Bodies may be application/x-www-form-urlencoded or application/json.
• Success returns body OK with status code 200; failures return a helpful error message with a 4xx status.

Add or update an IP address

Send a GET, POST, or PUT request to /update with key and ip parameters. Set ip to any valid IPv4 or IPv6 address, or use ip=self to record the requester's own IP address.

https://myaddr.tools/update?key=YOUR_KEY&ip=self

To force a specific address family, use the hosts ipv4.myaddr.tools or ipv6.myaddr.tools. Adding an IPv4 address replaces any existing IPv4 address, and the same applies to IPv6 — so each family holds one address at a time.

Add an ACME dns-01 challenge

For TLS certificates from CAs like Let's Encrypt, send a request with key and acme_challenge:

https://myaddr.tools/update?key=YOUR_KEY&acme_challenge=YOUR_CHALLENGE_VALUE

The value is served as a TXT record on all _acme-challenge subdomains. Challenge TXT records are removed automatically after a few minutes, so you do not need to clean them up.

Delete an IP address

A DELETE request to /update with key removes both the IPv4 and IPv6 addresses. This always responds with status code 204.

curl -X DELETE "https://myaddr.tools/update?key=YOUR_KEY"

Keeping your name active

Two independent timers apply:

• 90 days per IP address. Each IP (IPv4 and IPv6 tracked separately) must be updated at least once every 90 days to stay active.
• 120 days per name. If no updates are made to your name at all for 120 days, the registration is deleted and the name is released.

If your address rarely changes, schedule a periodic update anyway — a cron job or timer that calls /update with ip=self is enough to reset both clocks.

Deleting your registration

To immediately and permanently delete your registration and release the name, send a DELETE request to https://myaddr.tools/reg with your key:

curl -X DELETE "https://myaddr.tools/reg?key=YOUR_KEY"

This is irreversible — the name becomes available to anyone else.

Common snags

• Lost key: no recovery is described, so the name is effectively gone. Save the key before doing anything else.
• Only one address per family: a new IPv4 update overwrites the previous IPv4 record rather than adding a second one.
• ACME records are temporary: they disappear after a few minutes, which is fine for validation but not for long-lived TXT records.
• Silent expiry: missing the 90- or 120-day windows deletes records or the whole registration, so automate updates if you are not checking in regularly.