# DNS & WHOIS Domain Lookup

**DNS & WHOIS Domain Lookup** is an independently documented x402 Atlas bridge at https://dns.use.x402atlas.com.
This document describes only this bridge; it does not aggregate routes, schemas,
or content from any other bridge.

## How payment works

Paid operations use the [x402 payment protocol](https://x402.org) and settle in
USDC. Atlas supports deployments on Base, Polygon, and Arbitrum, plus configured
Solana networks. This bridge currently advertises Arbitrum One (`eip155:42161`), Base (`eip155:8453`), Polygon (`eip155:137`), Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).

1. Send the HTTP request without a payment signature.
2. Read the `402 Payment Required` response. Its `accepts` entries are the
   authoritative network, asset, amount, and recipient options for that call.
3. Select an option, sign it with an x402-compatible wallet or SDK, and repeat
   the request with the `PAYMENT-SIGNATURE` header. The successful response is
   returned after verification and settlement.

TypeScript clients can automate the challenge, signing, and retry flow with
[`x402-fetch`](https://www.npmjs.com/package/x402-fetch) or
[`x402-axios`](https://www.npmjs.com/package/x402-axios). Fund a dedicated
wallet only with the working USDC balance it needs and keep that key separate
from treasury accounts.

## Pricing

Atlas route prices start at $0.005 per successful call. This bridge's fallback
price is $0.005; operations below state their exact configured price in
`x-x402` and `x-payment-info`. The live `402` challenge remains authoritative.

## Worked payment example

Request one documented operation without a signature to inspect its live terms:

```bash
curl -i 'https://dns.use.x402atlas.com/a?host=example.com'
# HTTP/1.1 402 Payment Required
# Read accepts[].network, asset, amount, and payTo from this response.
```

Sign one accepted option and repeat the identical request with the
`PAYMENT-SIGNATURE` header. Do not invent or cache payment terms; read them from
the current challenge.

## Use this API

- Interactive reference: https://dns.use.x402atlas.com/docs
- OpenAPI 3.1 specification: https://dns.use.x402atlas.com/openapi.json
- Agent-readable route corpus: https://dns.use.x402atlas.com/llms.txt
- Endpoint index: https://dns.use.x402atlas.com/index.json

Use the operation schemas and examples below to construct requests. Copy the
server URL, path, method, parameters, and request body from the operation you
want to call. Path and query examples are concrete and can be used directly.

## Atlas response metadata

Successful JSON responses include an additive top-level `_atlas` block, kept
separate from the bridge's data fields. `_atlas.docs` links this bridge's
`/llms.txt` corpus. `_atlas.related` suggests adjacent APIs, each with a callable
`url`, its own `docs` link, and a short `summary`. Suppress this block by sending
`X-Atlas-Meta: none` or by adding `?_atlas=0` to the request.

## Errors and compatibility

Validation failures use HTTP `400`. Paid operations may return `402` before
dispatch. Upstream and internal failures use the documented `5xx` responses.
Clients should rely on documented fields and tolerate additive response fields,
including `_atlas` unless they explicitly opt out.

## Protocol reference

- x402 protocol and SDKs: https://x402.org

## DNS & WHOIS Domain Lookup

Docs: https://dns.use.x402atlas.com/docs · OpenAPI: https://dns.use.x402atlas.com/openapi.json

### GET /a

DNS A record lookup — resolve any hostname or domain to its IPv4 addresses, returned as a clean JSON list. For host resolution, connectivity and uptime checks, IP-reputation enrichment and infrastructure mapping.

Resolves a hostname to its IPv4 (A-record) addresses via a pinned public recursive resolver, returned as a flat `records` string array plus a `queried_at` UTC stamp. Pass the required `host` query param (a bare hostname — IP literals, `localhost`, and reserved suffixes like `.local`/`.internal` are rejected as `400 invalid_host`). Private/loopback/link-local addresses are stripped from the result, and a host that resolves to nothing after filtering (or NXDOMAIN) returns `404`, never a 200 with an empty list. For mail servers use `/mx`, for TXT policy records use `/txt`.

**Price:** $0.005 per call.

Parameters:
- `host` (required, string) — Bare hostname to resolve (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/a?host=example.com'
```

Response example:

```json
{
  "host": "example.com",
  "queried_at": "2026-06-05T12:00:00Z",
  "records": [
    "93.184.216.34"
  ]
}
```

### GET /dnssec

DNSSEC health check: reports whether a domain is DNSSEC-signed (DNSKEY), has a DS record at the parent, and whether the resolver authenticated the answer, with advisory warnings.

Checks a domain's DNSSEC posture over DNS-over-HTTPS and returns `{domain, dnssec_enabled, has_ds, authenticated, warnings[], queried_at}`: `dnssec_enabled` is true when a DNSKEY is present, `has_ds` when the parent publishes a DS record, and `authenticated` when the resolver set the DoH `AD` flag. Pass the required `domain` query param (a bare domain; IP literals, `localhost`, and reserved suffixes are rejected as `400 invalid_domain`). `warnings` is advisory and NEVER changes the status code — an unsigned or unauthenticated domain still returns `200` with warnings; only an unreachable/unparseable DoH upstream or a timeout is an error (`502`/`504`).

**Price:** $0.005 per call.

Parameters:
- `domain` (required, string) — Bare domain to check for DNSSEC signing (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/dnssec?domain=example.com'
```

Response example:

```json
{
  "authenticated": true,
  "dnssec_enabled": true,
  "domain": "cloudflare.com",
  "has_ds": true,
  "queried_at": "2026-06-05T12:00:00Z",
  "warnings": []
}
```

### GET /mx

DNS MX record lookup — a domain's mail servers with their hostnames and priorities as structured JSON, for email routing, deliverability diagnostics and mail-provider detection.

Returns a domain's mail servers as a `records` array of `{host, pref}` objects (`pref` is the MX preference — lower wins) plus a `queried_at` UTC stamp, for email routing, deliverability diagnostics and mail-provider detection. Pass the required `host` query param (a bare hostname; IP literals, `localhost`, and reserved suffixes are rejected as `400 invalid_host`). Each `host` is returned in raw DNS form, typically with a trailing dot (e.g. `mail.example.com.`). A domain with no MX records (or NXDOMAIN) returns `404`, not a 200 with an empty list.

**Price:** $0.005 per call.

Parameters:
- `host` (required, string) — Bare hostname to resolve (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/mx?host=example.com'
```

Response example:

```json
{
  "host": "example.com",
  "queried_at": "2026-06-05T12:00:00Z",
  "records": [
    {
      "host": "mail.example.com.",
      "pref": 10
    }
  ]
}
```

### GET /rdap

RDAP domain registration lookup: structured registrar, creation/updated/expiry dates, status, nameservers and a computed domain age. A parsed, snake_case JSON alternative to raw WHOIS text.

Returns a normalized, snake_case domain-registration record parsed from RDAP: `{domain, registrar, created, updated, expiration, status[], nameservers[], domain_age_days, queried_at}` — a structured alternative to the raw `/whois` text, not the raw RDAP blob. Pass the required `domain` query param (a bare domain; IP literals, `localhost`, and reserved suffixes are rejected as `400 invalid_domain`). `domain_age_days` is computed from `created` to now as a fraud/trust signal and falls back to `0` when the registration date is missing or unparseable; other fields may be empty strings when the registry omits them, and `status`/`nameservers` are always arrays (possibly empty). A domain with no registration record returns `404`.

**Price:** $0.005 per call.

Parameters:
- `domain` (required, string) — Bare domain to look up via RDAP (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/rdap?domain=example.com'
```

Response example:

```json
{
  "created": "1995-08-14T04:00:00Z",
  "domain": "example.com",
  "domain_age_days": 11000,
  "expiration": "2024-08-13T04:00:00Z",
  "nameservers": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "queried_at": "2026-06-05T12:00:00Z",
  "registrar": "RESERVED-Internet Assigned Numbers Authority",
  "status": [
    "client delete prohibited"
  ],
  "updated": "2023-08-14T07:01:44Z"
}
```

### GET /txt

DNS TXT record lookup — a domain's TXT records as a clean JSON list: SPF, DKIM and DMARC policy strings plus site-verification and domain-ownership tokens, for email-authentication and domain-verification checks.

Returns a domain's TXT records as a flat `records` string array (each entry the raw TXT string) plus a `queried_at` UTC stamp — SPF (`v=spf1 ...`), DKIM and DMARC policy strings, and site-verification / ownership tokens. Pass the required `host` query param (a bare hostname; IP literals, `localhost`, and reserved suffixes are rejected as `400 invalid_host`). Records are returned verbatim and unparsed — the caller interprets SPF/DKIM/DMARC syntax. A domain with no TXT records (or NXDOMAIN) returns `404`, not a 200 with an empty list.

**Price:** $0.005 per call.

Parameters:
- `host` (required, string) — Bare hostname to resolve (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/txt?host=example.com'
```

Response example:

```json
{
  "host": "example.com",
  "queried_at": "2026-06-05T12:00:00Z",
  "records": [
    "v=spf1 -all"
  ]
}
```

### GET /whois

WHOIS domain lookup — raw registry text with registrar, nameservers, lifecycle dates and status, plus the responding server. Use the RDAP endpoint when you need parsed structured data.

Returns the raw WHOIS record for a domain as text: `{domain, server, raw, queried_at}`, where `server` is the authoritative host whose text was returned (IANA when there is no referral, otherwise the one referred registry) and `raw` is the unparsed WHOIS body — clients parse per-TLD as needed. Pass the required `domain` query param (a bare domain; IP literals, `localhost`, and reserved suffixes are rejected as `400 invalid_domain`). Only a single referral hop is followed (multi-hop chains are not chased), responses over 64 KiB surface as `502 upstream_error`, and a slow server returns `504`. For a parsed, structured snake_case alternative use `/rdap`.

**Price:** $0.005 per call.

Parameters:
- `domain` (required, string) — Bare domain to query (not an IP literal, not localhost, not under a reserved suffix like .local/.internal); minLength: `1`, maxLength: `253`; example: `"example.com"`

Example:

```sh
curl 'https://dns.use.x402atlas.com/whois?domain=example.com'
```

Response example:

```json
{
  "domain": "example.com",
  "queried_at": "2026-06-05T12:00:00Z",
  "raw": "Domain Name: EXAMPLE.COM\n...",
  "server": "whois.verisign-grs.com"
}
```