# IP Checker

> IP, network and connection diagnostics for humans, software and autonomous agents. Tells a caller its public IP, country, ASN, ISP, network type and proxy/VPN/Tor signals, and looks up any IP address.

Base URL: https://ipcheck.trytorchlabs.com
API base URL: https://ipcheck.trytorchlabs.com/api/v1
Authentication: none required for the endpoints below.
Formats: plain text (single values) or JSON.
OpenAPI: https://ipcheck.trytorchlabs.com/openapi.json
Human docs: https://ipcheck.trytorchlabs.com/docs

## Endpoints

### Current connection

- Public IP only (plain text, fastest): GET https://ipcheck.trytorchlabs.com/ip
- Country code (plain text): GET https://ipcheck.trytorchlabs.com/country
- ASN, e.g. AS7018 (plain text): GET https://ipcheck.trytorchlabs.com/asn
- ISP name (plain text): GET https://ipcheck.trytorchlabs.com/isp
- Structured description: GET https://ipcheck.trytorchlabs.com/api/v1/me
- Compact agent format: GET https://ipcheck.trytorchlabs.com/api/v1/me?format=agent
- Selected fields only: GET https://ipcheck.trytorchlabs.com/api/v1/me?fields=ip,country,asn,isp
- Full diagnostic (network, geo, risk with certainty, protocol, request headers, client classification): GET https://ipcheck.trytorchlabs.com/api/v1/diagnostic

### Any IP address

- GET https://ipcheck.trytorchlabs.com/api/v1/ip/{ip}   (IPv4 or IPv6; add ?format=agent for the compact form)

### Proxy tools (planned; currently return 501 NOT_IMPLEMENTED after validating input)

- POST https://ipcheck.trytorchlabs.com/api/v1/proxy/test       body: {"proxy":{"protocol":"http","host":"...","port":8080,"username":"...","password":"..."}}
- POST https://ipcheck.trytorchlabs.com/api/v1/proxy/validate   body: {"proxy":{...},"expect":{"country":"US","asn":7018,"network_type":"residential"}}
- POST https://ipcheck.trytorchlabs.com/api/v1/proxy/session-test body: {"proxy":{...},"requests":10,"interval_ms":1000}

## Sample calls

curl https://ipcheck.trytorchlabs.com/ip
curl "https://ipcheck.trytorchlabs.com/api/v1/me?format=agent"
curl https://ipcheck.trytorchlabs.com/api/v1/ip/8.8.8.8

Example agent-format response:
{"ip":"203.0.113.42","geo":"US-California-Los Angeles","asn":"AS7018","isp":"AT&T Enterprises, LLC","network_type":"residential","proxy":false,"vpn":false,"tor":false}

## Response conventions

- Unknown values are null. Nothing is guessed.
- network_type is one of: residential, mobile, hosting, business, education, government, unknown, or null.
- proxy / vpn / tor / hosting booleans are estimates: true only when evidence is known or likely; null when undetermined (including weak positive signals); false when nothing was detected. For certainty use /api/v1/me (confidence object) or /api/v1/diagnostic (classification object), where each signal has certainty: known | likely | inferred | unavailable.
- tor=true with certainty "known" comes from the official Tor exit list. Proxy and VPN results are "likely" or "inferred", never "known".
- Allowed fields for ?fields=: ip, ip_version, country, country_name, region, city, postal_code, latitude, longitude, timezone, asn, asn_name, isp, organization, network_type, proxy, vpn, tor, hosting, reverse_dns, user_agent, http_version, client_type, timestamp
- Errors: {"success":false,"error":{"code":"INVALID_IP","message":"..."}}. Codes: INVALID_IP, INVALID_FIELD, INVALID_FORMAT, INVALID_REQUEST, INVALID_PROXY, UNSUPPORTED_PROTOCOL, PAYLOAD_TOO_LARGE, NOT_FOUND, NOT_IMPLEMENTED, PROXY_CONNECTION_FAILED, PROXY_TIMEOUT, RATE_LIMITED, INTERNAL_ERROR.

## Rate limits (per client IP, per minute)

- /ip, /country, /asn, /isp, /api/v1/me, /api/v1/diagnostic: 120
- /api/v1/ip/{ip}: 30
- /api/v1/proxy/*: 5
Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; Retry-After on 429.

## Limitations

- Location is IP-based and approximate (country reliable, city often approximate). It is never a street address.
- ISP on the default data source is the network operator of the ASN; resellers are not distinguished.
- Proxy and VPN detection is heuristic. Residential proxies usually appear residential.
- HTTP version and TLS details are only reported when the deployment's edge forwards them.
- Browser fingerprinting runs only in a web browser on the homepage; APIs do not fingerprint browsers.

## Guides

- https://ipcheck.trytorchlabs.com/learn/how-ai-agents-check-outbound-ip
- https://ipcheck.trytorchlabs.com/learn/can-websites-detect-proxies
- https://ipcheck.trytorchlabs.com/learn/what-is-an-asn