SOA record check API
Asks the public resolvers for the SOA of the zone apex and checks the serial against the YYYYMMDDnn form and refresh, retry, expire and the negative caching TTL against RFC 1912 and RFC 2308. The zone's own name servers are not contacted.
GET https://api.lookproof.dev/v1/dns/soa
Updated 2026-10-09
Examples use the Base (eip155:8453) network.
Input
Query parameters.
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
domain | string | Yes | 1–1024 characters | The domain to check, for example example.com. |
Example request
curl -i 'https://api.lookproof.dev/v1/dns/soa?domain=example.com'import asyncio
import os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import register_exact_evm_client
async def main() -> None:
signer = EthAccountSigner(Account.from_key(os.environ["EVM_PRIVATE_KEY"]))
client = register_exact_evm_client(x402Client(), signer, networks="eip155:8453")
async with x402HttpxClient(client) as http:
response = await http.get('https://api.lookproof.dev/v1/dns/soa', params={'domain': 'example.com'})
response.raise_for_status()
print(response.json())
asyncio.run(main())
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});
const response = await fetchWithPayment("https://api.lookproof.dev/v1/dns/soa?domain=example.com");
console.log(await response.json());
curl: unpaid request — returns 402 with the price (PAYMENT-REQUIRED). The Python and JavaScript clients pay it and send the request again. Only ordinary wallets (EOA) can pay; smart-contract wallets get a 402 without charge. See payments.
Example response
{
"checked_at": "2026-10-24T12:00:00Z",
"data": {
"domain": "example.com",
"soa": {
"expire": 1209600,
"minimum": 300,
"mname": "ns1.example.com",
"refresh": 7200,
"retry": 3600,
"rname": "hostmaster.example.com",
"serial": 2026102401,
"serial_format": "date"
},
"ttl": 300
},
"endpoint": "dns.soa",
"findings": [],
"meta": {
"cache_hit": false,
"duration_ms": 42,
"fresh_until": "2026-10-24T12:05:00Z",
"observed_at": "2026-10-24T12:00:00Z",
"resolver": "example",
"source": "dns"
},
"request_id": "req_aaaaaaaaaaaaaaaaaaaaaaaaaa",
"schema_version": "1.0",
"status": "ok"
}
Response fields
| Field | Meaning |
|---|---|
request_id | Unique id of this request. Quote it when you contact support. |
endpoint | The endpoint id, for example mail.spf. |
schema_version | Version of the response format, currently 1.0. |
checked_at | When the check ran (ISO 8601, UTC). |
status | ok, info, warning or error from the worst finding, or unknown when the check was incomplete. unknown is not an error in the domain. |
data | The check's own data. Its fields are listed below. |
findings | What was found: code, severity, message, explanation and evidence. |
meta | Duration, cache use, resolver and how long the result stays fresh. |
Fields in data
| Field | Type |
|---|---|
domain | string |
soa | SoaValues or null |
ttl | integer or null |
Status codes
| Status | Code | Meaning | Do you pay? |
|---|---|---|---|
| 200 | — | The result is delivered, also when it has negative findings. | Yes: charged once per payment; redelivery of the same payment is free |
| 402 | — | Payment is required, or the attached payment was refused. The body states the price. | No |
| 400 | bad_request | The request is malformed. | No |
| 409 | payment_in_progress, payment_bound_to_other_request | This payment is already being processed, or it is bound to a different request. No new payment is taken. | No |
| 422 | invalid_input | The input failed validation on a request that carries a payment; nothing is charged. Without a payment, invalid input gets a 402 whose error field names the problem. | No |
| 429 | rate_limited | Too many requests from this IP address or payer. | No |
| 502 | check_failed | The check could not be completed. | No |
| 503 | busy, unavailable, payments_unavailable | The service is busy or temporarily unavailable. | No |
| 504 | deadline_exceeded | The check ran out of time. | No |
Errors use the common error body. See errors.
Findings this endpoint can return
SOA record (7)
- Warning
SOA_EXPIRE_BELOW_REFRESHThe SOA expire is not longer than refresh plus retry. - Info
SOA_EXPIRE_SHORTThe SOA expire is shorter than two weeks. - Info
SOA_NEGATIVE_TTL_LONGThe SOA minimum (negative caching TTL) is longer than three hours. - Info
SOA_NOT_FOUNDThe name has no SOA record, so it is not the apex of a zone. - Info
SOA_REFRESH_OUT_OF_RANGEThe SOA refresh is outside 20 minutes to 12 hours. - Warning
SOA_RETRY_NOT_BELOW_REFRESHThe SOA retry is not shorter than the refresh. - Info
SOA_SERIAL_NOT_DATEThe SOA serial is not in the YYYYMMDDnn date form.
Check (1)
- Warning
CHECK_QUERY_BUDGET_EXCEEDEDThe check stopped after reaching its DNS query limit.
DNS (3)
- Error
DNS_DOMAIN_NOT_FOUNDThe DNS resolver reported that the domain does not exist. - Warning
DNS_RESOLVER_FAILUREThe DNS resolver returned a server failure. - Warning
DNS_RESOLVER_TIMEOUTThe DNS resolver did not answer in time.