# ip-tools.eu API

ip-tools.eu answers one question for whoever connects to it: what does this connection look like from the outside? The API returns that about the caller, plus two lookups that are about anything: geolocation of an address, and the terms behind the fields.

## Hosts

Two kinds of host, because the main site's TLS is terminated by a web server that hides the connection:

| Host | What it sees | Endpoints |
|---|---|---|
| `https://ip-tools.eu` | The caller's address only | `/api/geo`, `/api/resolver` |
| `https://netcap4.ip-tools.eu` | The caller's own TCP connection, IPv4 only | `/api/capture`, `/report.md`, `/api/traceroute`, `/api/pathmtu` |
| `https://netcap6.ip-tools.eu` | The same over IPv6 only | as above, plus `/api/pathprobe6` |
| `https://netcap.ip-tools.eu` | Dual-stack, HTTP/3 advertised | `/api/capture` |

Every capture endpoint describes the connection that requested it. There is no way to ask about another address, by design.

## The connection report

```
curl -H 'Accept: text/markdown' https://netcap4.ip-tools.eu/
curl https://netcap4.ip-tools.eu/report.md
curl https://netcap4.ip-tools.eu/api/capture        # JSON
```

The report covers: IPv4 or IPv6 address, reverse DNS, classification (residential, hosting, relay), geolocation and ASN; the TLS ClientHello fingerprint (JA4, JA3) and what was negotiated; the likely client software from the TLS and HTTP/2 fingerprints against the User-Agent; Client Hints; the HTTP layer (header order, JA4H, HTTP/2 SETTINGS); the live TCP socket (RTT, MSS, cwnd, congestion control); the passive OS guess from the SYN (p0f, JA4T); the handshake timeline and captured packets; and the verdict, a weighed list of observations about VPNs, proxies, relays and carrier-grade NAT.

JSON fields of `/api/capture` (top level): `ip`, `ip_version`, `classification`, `reverse_dns`, `geo`, `tls`, `tls_negotiated`, `client`, `client_hints`, `http`, `request_proto`, `port`, `timing`, `handshake`, `distance`, `tcp`, `os`, `ipv6` (IPv6 only), `udp`, `quic`, `packets`, `verdict`. Optional query parameters: `tz` (the caller's IANA time zone, compared with the address's), `rtc` (a public address WebRTC found), `cgnat` (the caller's carrier-NAT evidence). The `openapi.json` description lists them.

## Geolocation

```
curl https://ip-tools.eu/api/geo                    # the caller
curl 'https://ip-tools.eu/api/geo?ip=203.0.113.4'   # any address
```

Returns `ip`, `ip_version`, `classification`, `reverse_dns` and `geo` with `location` (continent, country, region, city, postal code, latitude, longitude, accuracy radius in km, time zone) and `asn` (number, organisation, announced network). The database is an offline GeoLite2 copy; the address is not sent anywhere else. Lookups of addresses other than the caller's are limited to 60 per minute per caller, with a burst of 30; over the limit the answer is `429` with `Retry-After`.

## Probes about the caller

```
curl https://netcap4.ip-tools.eu/api/traceroute          # reverse traceroute, our host → caller
curl 'https://netcap4.ip-tools.eu/api/traceroute?mode=icmp'
curl https://netcap4.ip-tools.eu/api/pathmtu             # largest packet that reaches the caller
curl https://netcap6.ip-tools.eu/api/pathprobe6          # which IPv6 extension headers get through
```

Each targets the caller's own address, runs for a few seconds, and is rate-limited per address; a `429` means wait and retry. The traceroute rides the caller's open connection by default, which reaches past a NAT; `mode=icmp` sends plain echo probes instead.

## Resolver detection

The resolver check needs the caller to make a DNS lookup of a one-time name in a zone ip-tools.eu serves. A program can do it by hand:

1. Pick a random token, for example 20 hex characters.
2. Resolve `x.<token>.nnscap.ip-tools.eu` (and, optionally, `x.<token>.nnscap4.ip-tools.eu` and `x.<token>.nnscap6.ip-tools.eu`). The lookups may fail; only the fact that a resolver asked our name server matters.
3. After a second or two, `GET https://ip-tools.eu/api/resolver?token=<token>`.

The answer lists every resolver address that asked, with its network, transport, EDNS buffer size, DNSSEC DO bit, cookies, case randomisation, query minimisation, and whether it fetched the zone's DNSSEC key, which only a validating resolver does.

## Reading the fields

Every term is defined at https://ip-tools.eu/glossary.md, and each page of the site has a `.md` twin with an explainer of its view: https://ip-tools.eu/llms.txt lists them.

## Rules

Nothing is stored beyond a capture buffer that lives for seconds. Probes only ever target the connection that asked. Be considerate with lookups; the limits above are the only ones.