# Dynamic DNS (DDNS)

Keep an A record pointed at a machine whose IP changes (home server, dynamic ISP). The pattern: read your current IP, compare it to the record, and update only when it changed.

## 1. Get your current public IP

```bash
curl -X POST https://api.porkbun.com/api/json/v3/ping \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
# -> { "status":"SUCCESS", "yourIp":"203.0.113.10" }
```

`yourIp` is the IP Porkbun saw the request come from — exactly what the A record should point at if you're calling from the box you want to reach.

## 2. Read the current record

```bash
curl 'https://api.porkbun.com/api/json/v3/dns/retrieveByNameType/example.com/A/home' \
  -H 'X-API-Key: pk1_...' -H 'X-Secret-API-Key: sk1_...'
```

(Use a blank subdomain for the apex: `…/A/` instead of `…/A/home`.) Compare the record's `content` to `yourIp`. **If they match, do nothing** — don't write on every tick.

## 3. Update only on change

`editByNameType` upserts by name+type, so you don't need the record ID:

```bash
curl -X POST https://api.porkbun.com/api/json/v3/dns/editByNameType/example.com/A/home \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","content":"203.0.113.10","ttl":"600"}'
```

If the record doesn't exist yet, create it once with `/dns/create/example.com` (`type:"A"`, `name:"home"`, `content`, `ttl`).

## 4. Run it on a schedule

Call this from cron every few minutes. Keep TTL low (e.g. 600s) so changes propagate quickly. A minimal loop:

1. `ping` → `yourIp`
2. `retrieveByNameType` → current `content`
3. if different → `editByNameType`

## If the update seems to do nothing

Check `warnings` in the write response before you debug anything else:

```json
{ "status": "SUCCESS",
  "warnings": ["home.example.com ... is delegated to nameservers we do not operate (ns1.example-dns.net), so this change was saved to your Porkbun DNS zone but does NOT affect what resolves ..."] }
```

We keep a DNS zone for every domain in the account whether or not the domain
points at our nameservers, so a write always succeeds locally. If the domain is
delegated somewhere else, the record you just wrote is real but nobody is asking
us for it. Either run the DDNS update against whoever runs those nameservers, or
point the domain at ours with `POST /domain/updateNs/example.com`.

`GET /dns/preflight/example.com` reports the same thing up front, as the
`nameservers-ours` check.

## Scope the key

Give the DDNS box a key restricted to **just this domain** and, if its egress IP is stable, to that IP. A leaked DDNS key then can't touch anything else on the account. See [Getting started](https://porkbun.com/llms/guides/getting-started) for key scoping.

## Related

- DNS endpoints: https://porkbun.com/llms/dns
- Caller IP only (no auth needed): `GET /api/json/v3/ip`


---

## More

- Guides (how-tos): https://porkbun.com/llms/guides
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Short overview: https://porkbun.com/llms.txt
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api