# 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`

## 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://github.com/oborseth/Porkbun-MCP (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api