DomainRef / Docs
DomainRef docs
One HTTP call grades a domain's public email and web security setup and returns JSON: each check with its grade, finding and exact fix, plus a 0-100 score and a letter. No account and no signup.
Routes
| Route | Price | What it returns |
|---|---|---|
GET /v1/domain/check?domain={domain} | $0.01 | The full graded report: every check with its grade, finding and fix, the score and the letter. |
GET /v1/domain/age?domain={domain} | $0.005 | Registrar, age, expiry and status flags, graded for newly registered domains. Not for registries without RDAP, e.g. .za/.co.za, .me, .de, .io, .eu: refused free (422). |
| /grade (people, HTML) | Free | The letter, the score and pass, warn, fail or info for each check, without findings or fixes. 3 per visitor per day. Not an API: agents use the paid route. |
| /sample and /sample.json | Free | A real full report for 3l-groupconsulting.co.za, our own domain, refreshed daily. Only for that domain. |
HEAD on either paid route is a free 402 preview and is never charged.
How to pay
- x402: USDC on Base (eip155:8453). Call without payment and you get HTTP 402 with a PAYMENT-REQUIRED header. Any x402 client signs the payment and retries with PAYMENT-SIGNATURE. Settlement happens only when the call succeeds.
- MPP: the same 402 carries a WWW-Authenticate: Payment challenge for clients that speak MPP, at the same price and to the same address. MPP settles before the answer is sent, so DomainRef runs all its lookups first and refuses free when it cannot answer.
- API key: an Afriref API key with card credit, bought at afriref.dev/pricing, sent as X-API-Key. A failed call is refunded to the key.
Machine-readable prices and payment details: /.well-known/x402.
Example
Unpaid, the call answers with the price:
$ curl -si "https://domainref.dev/v1/domain/check?domain=example.com"
HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…Paid, it returns the report. Real output for example.com, trimmed to three of its checks:
{
"domain": "example.com",
"score": 100,
"letter": "A",
"summary": "example.com scores 100/100 (A): 6 pass, 0 warn, 0 fail, 7 info. Nothing to fix.",
"checks": [
{ "check": "dmarc", "label": "DMARC", "grade": "pass",
"finding": "DMARC enforces p=reject on 100% of mail.", "fix": null },
{ "check": "mta_sts", "label": "MTA-STS", "grade": "info",
"finding": "Not applicable: the domain publishes a null MX, so it takes no mail.", "fix": null },
{ "check": "registration", "label": "Registration (registrar and age)", "grade": "pass",
"finding": "Registered 1995-08-14 via RESERVED-Internet Assigned Numbers Authority (IANA 376), 11390 days old, expires 2027-08-13.", "fix": null }
]
}The full shape of both responses is in openapi.json, and /sample.json is a complete live report.
MCP
https://domainref.dev/mcp is a streamable HTTP MCP server with two tools, domain_check and domain_age. MCP calls pay with api_key (an Afriref key with card credit from afriref.dev/pricing). Per-call x402 and MPP payment is HTTP only, so a call without a key returns an api_key_required error that names the HTTP endpoint.
{ "mcpServers": { "domainref": { "url": "https://domainref.dev/mcp" } } }Limits and guardrails
- Never charged: bad input (400), a domain that does not exist (404), a domain that only resolves to private addresses (400), the age lookup for registries without RDAP (422), broken DNSSEC or name servers that refuse to answer (422, with the diagnosis and fix), an invalid API key (401), rate limits (429, with Retry-After) and DNS or registry outages (503). This holds on every rail.
- Rate limits: per network before payment, and per wallet or API key after it. A limited call is a free 429.
- Non-intrusive: only public DNS over HTTPS, the registry's RDAP, Microsoft's public sign-in discovery, and HTTPS on port 443 of the domain (one TLS handshake, and the MTA-STS policy and BIMI mark certificate when published). No port scans and no other ports.
- Privacy: The DomainRef app does not store queried domains; our firewall log keeps request URLs (with the domain) for about 6 months. Details in the privacy notice.
- Results are informational, not a security audit. See the terms, including payment and refunds.
More
- openapi.json: the OpenAPI description.
- llms.txt: the same reference in plain text for agents.
- /.well-known/x402: x402 discovery.
- Pricing, guides, terms and privacy.