WorldIP API — Developer Documentation

MCP server (for AI agents)

WorldIP speaks the Model Context Protocol, so an MCP-aware client can call it as a tool instead of scraping pages. No API key is required — the server exposes the same free keyless profile as the public endpoints.

Add it to Claude Code

claude mcp add --transport http worldip https://worldip.io/mcp

Or by hand in .mcp.json

The type field selects the transport — the config will not work without it.

{ "mcpServers": { "worldip": { "type": "http", "url": "https://worldip.io/mcp" } } }

Tools

Both tools are read-only, idempotent and open-world (they consult live data), and are annotated as such in tools/list.

The tools and the free keyless endpoint (https://worldip.io/{ip}) carry domains_hosted: how many registrable domains have a name resolving to the address, counted once a week from issued.live's DNS snapshot — a number, never the names. count is 0 when none were seen and null when the count is unavailable; the whole object is null for reserved addresses and, for now, for IPv6. The keyed lookup below is unchanged.

"domains_hosted": {"count":42650,"as_of":"2026-10-11","source":"issued.live","attribution":"Domain data provided by issued.live — for full details visit https://issued.live/pricing","details_url":"https://issued.live/pricing"}

Getting started

Every endpoint lives under a single HTTPS base URL and returns application/json. A successful response is 200 OK with the record at the top level; errors use standard HTTP status codes with a JSON error body (see Errors).

Quickstart — one full IP profile

curl -s https://worldip.io/api/v1/ext/lookup/8.8.8.8 \
  -H "Authorization: Bearer YOUR_KEY"

Beta keys for issued.live Plus and Pro customers

While the WorldIP API is in beta, our team issues API keys free of charge to customers with an active issued.live Plus or Pro subscription. issued.live and WorldIP are separate services run by the same company, Tuxxin LLC: your issued.live plan and billing do not change, and WorldIP charges nothing for a beta key.

Basic lookups on https://worldip.io/{ip} with your key have no daily cap. Responses carry X-RateLimit-* (per minute) and X-Concurrency-Limit (requests in flight); enriched lookups also carry X-Quota-* (monthly enriched lookups). Limits may change during the beta.

How to get your key

• Subscribe to issued.live Plus or Pro. We issue keys by hand and email yours to the address on your issued.live account within one business day.
• No key after one business day? Contact us from that address.
• We store only a hash of your key and cannot show it again, so keep it safe. If you lose it or it leaks, contact us and we will replace it.

Using your key

• Send it only in the Authorization: Bearer YOUR_KEY header, and only to https:// URLs.
• Never put it in a URL (?key=): URLs are written to server, proxy and browser logs. Never ship it in browser or app code that others can read; call the API from your server.
• Keep the attribution text (and grip_attribution where present) with any API data you display or pass on: some fields come from licensed datasets (see Data sources).

Beta conditions

• Free during the beta, one key per issued.live subscription, for you or your organisation only. Do not share, publish, sell or sublicense it.
• Limits may change during the beta, and so may fields and endpoints. We announce breaking changes on this page and email key holders.
• No SLA. Beta keys come with no uptime commitment.
• Revocation. We may suspend or revoke a key that is abused or used against our Terms, and we revoke it when the issued.live subscription it came with ends.
• End of the beta: 30 days after WorldIP’s paid plans launch. We will email you before then. Nothing is charged automatically.
• Support is best effort, through our contact form.

The full terms are in our Terms of Use (API keys and the beta).

Authentication

Present your key on every keyed request as a Bearer token, over HTTPS only. Do not use the ?key= query parameter: it is accepted only for older integrations, and a key in a URL is written to server logs and can leak through referrers and browser history.

Authorization: Bearer YOUR_KEY

Scopes

Each key carries one or more scopes. A request is rejected with 403 forbidden_scope if its key lacks the scope the endpoint requires.

Key locking (optional)

A key can be pinned so a leaked value is useless elsewhere:

• Origin lock — restricts browser calls to one site (enforced whenever the request carries an Origin/Referer). Mismatch → 403 origin_not_allowed.
• IP allow-list — restricts calls to specific caller IPs, the strongest server-to-server lock. Off-list → 403 ip_not_allowed.

IP profile lookup

curl -s https://worldip.io/api/v1/ext/lookup/8.8.8.8 \
  -H "Authorization: Bearer YOUR_KEY"

{
  "ip": "8.8.8.8",
  "reserved": false,
  "reserved_note": null,
  "ptr": "dns.google",
  "asn": { "number": 15169, "name": "Google LLC" },
  "org": { "name": "Google LLC", "slug": "google-llc", "category": "hosting" },
  "country": { "code": "US", "name": "United States" },
  "cidr": "8.8.8.0/24",
  "trust": { "score": 92, "band": "Trusted", "color": "#3fb950" },
  "web3": [],
  "bgp": {
    "prefix": "8.8.8.0/24",
    "origin_asn": 15169,
    "moas": false,
    "anomalies": []
  },
  "forward_dns": null,
  "flags": [
    { "key": "hosting", "label": "Hosting/DC", "level": "warn", "emoji": "🖥️",
      "title": "Datacenter / hosting network - server addresses, not home connections." }
  ],
  "classification": {
    "is_vpn": false,
    "is_proxy": false,
    "is_relay": false,
    "relay_source": null,
    "is_anonymous": false,
    "access_type": "hosting",
    "proxy_density_30d": null,
    "vpn_density_30d": null,
    "is_tor": false,
    "is_datacenter": true,
    "is_vpn_likely": false,
    "verdict": "hosting",
    "confidence": "high",
    "score": 0,
    "source": "worldip-classification"
  },
  "grip": null,
  "grip_attribution": null,
  "attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources",
  "links": {
    "ip": "https://worldip.io/8.8.8.8",
    "asn": "https://worldip.io/asn/AS15169",
    "org": "https://worldip.io/org/google-llc"
  },
  "generated_at": "2026-07-17T00:45:12+00:00"
}

IPv6 lookups

Both IP endpoints take IPv6 addresses: the free keyless https://worldip.io/{ipv6} and the keyed /api/v1/ext/lookup/{ipv6}. An IPv6 profile has the same keys as an IPv4 one, so one parser handles both, plus "version": 6, the containing prefixes and an rdns block. Authentication, scopes, per-key rate and concurrency limits, the monthly allowance, plan data tiers, CORS and the 5-minute origin cache work exactly as for IPv4.

curl -s https://worldip.io/2003:c8:734:9700::1

{
  "ip": "2003:c8:734:9700::1",
  "version": 6,
  "ptr": "p200300c8073497000000000000000001.dip0.t-ipconnect.de",
  "forward_dns": { "hostname": "p200300c8073497000000000000000001.dip0.t-ipconnect.de", "confirmed": true },
  "asn": { "number": 3320, "name": "Deutsche Telekom AG" },
  "org": { "name": "Deutsche Telekom AG" },
  "country": { "code": "DE", "name": "Germany" },
  "region": "Baden-Wurttemberg",
  "city": "Leutkirch",
  "cidr": "2003:c8:400::/38",
  "address_type": "Global Unicast",
  "prefixes": { "/32": "2003:c8::/32", "/48": "2003:c8:734::/48", "/56": "2003:c8:734:9700::/56", "/64": "2003:c8:734:9700::/64" },
  "rdns": {
    "status": "found",
    "kind": "isp_generated",
    "checked_at": "2026-09-30T10:34:08Z",
    "forward_check": "confirmed",
    "note": "ISP-generated name: the network names every address from a template, usually by encoding the address itself. It shows which network the address belongs to, not that a host is live there."
  },
  "_meta": { "keyless": true, "docs": "https://worldip.io/developers", "note": "...",
             "attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources",
             "generated_at": "...", "rate": { "limit": 1000, "remaining": 999, "reset": "...", "window_seconds": 86400 } }
}

curl -s https://worldip.io/api/v1/ext/lookup/2606:54c0:5898::1 -H "Authorization: Bearer YOUR_KEY"

"org": { "name": "Cloudflare, Inc.", "slug": "cloudflare-inc", "category": "cdn" },
"classification": {
  "is_vpn": null, "is_proxy": null, "is_relay": true, "relay_source": "icloud_private_relay",
  "is_anonymous": null, "access_type": "hosting", "is_tor": null, "is_datacenter": true,
  "verdict": null, "confidence": null, "score": null, "is_bogon": false, "blocklists": [], ...
},
"trust": null, "bgp": null, "forward_dns": null,
"unavailable": { "trust": "Trust score is IPv4-only: ...", ... }

Reserved, private and link-local addresses return reserved: true with no network data. An IPv4-mapped address (::ffff:8.8.8.8) is the IPv4 address it carries, and every endpoint answers it as that address: the keyless endpoint and the MCP tools return the IPv4 profile, and /api/v1/ext/lookup/::ffff:8.8.8.8 is the IPv4 lookup, counted and cached once, as 8.8.8.8. NAT64 (64:ff9b::/96) and 6to4 (2002::/16) addresses are IPv6 addresses; their profile adds embedded_ipv4 as a hint.

Pulse events

curl -s "https://worldip.io/api/v1/pulse/events?types=aspath,bogon&min_severity=5&limit=100" \
  -H "Authorization: Bearer YOUR_KEY"

{
  "events": [
    {
      "id": "bgp:14238894120583017472",
      "category": "bgp",
      "type": "aspath",
      "label": "AS-path anomaly (possible leak/hijack)",
      "severity": 7,
      "detected_at": "2026-07-17T00:44:57+00:00",
      "ts": 1768610697,
      "prefix": "103.163.158.0/24",
      "asn": 141804,
      "counter_asn": 140171,
      "country": "IN",
      "lat": 22.35,
      "lon": 78.67,
      "detail": { "collector": "rrc05", "as_path": "13237 3320 6453 4755 141804" }
    }
  ],
  "count": 1,
  "next_since": 1768610697,
  "server_time": 1768610760,
  "attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources"}

Pulse summary

curl -s https://worldip.io/api/v1/pulse/summary \
  -H "Authorization: Bearer YOUR_KEY"

{
  "bgp_anomalies": [
    { "type": "moas", "category": "bgp", "label": "Multiple-origin route (MOAS)", "last_1h": 7111, "last_24h": 11250 },
    { "type": "aspath", "category": "bgp", "label": "AS-path anomaly (possible leak/hijack)", "last_1h": 9, "last_24h": 120 }
  ],
  "rir_changes": [
    { "type": "allocation", "category": "rir", "label": "RIR allocation", "last_1h": 6, "last_24h": 214 }
  ],
  "server_time": 1768610760,
  "attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources"}

Public feeds (no key)

The same Pulse data also powers the auto-refresh on our Pulse pages, exposed as lightweight no-key poll endpoints. They share the site-wide per-IP request floor (see Rate limits); for higher volume or geo-tagged output, use the keyed Pulse events endpoint.

{
  "anomalies": [
    {
      "prefix": "200.7.251.0/24",
      "unexpected_asn": 273140,
      "expected_asn": 19114,
      "pings": 314,
      "last_seen": "2026-07-17 00:44:57",
      "collector": "rrc25",
      "as_path": "198150 174 12956 19114 273140"
    }
  ]
}

{
  "events": [
    {
      "id": 293167,
      "changed_at": "2026-07-11 12:03:24",
      "ip_start": 3627346432,
      "ip_end": 3627346943,
      "ip_start_str": "216.52.234.0",
      "change_type": "allocation",
      "old_value": null,
      "new_value": "US",
      "rir": "arin",
      "cidr_guess": "216.52.234.0/23",
      "org_name": "Unitas Global",
      "org_slug": "unitas-global",
      "asn": 10912,
      "country_code": "US"
    }
  ]
}

{
  "type": "aspath",
  "totals": { "anomalies_24h": 120 },
  "anomalies": [ /* ... */ ]
}

Rate limits

Limits are enforced with a sliding 60-second window: a key may make up to its per-minute limit in any 60 seconds (e.g. a 1,200/min key can send 300 requests in 10 seconds; the 1,201st request inside one 60-second window is rejected). Exceeding a limit returns 429 with a Retry-After header and a JSON body.

A high per-source-IP flood guard (3,000/min) also applies before authentication; it sits above every key's own limit, so your key's rate is the limit you will actually meet.

Concurrency

Each paid plan also limits concurrent (simultaneous, in-flight) requests per key: Basic 5, Pro 10, Business 20, Scale 30, Enterprise 100+ (custom). A request beyond the limit returns 429 concurrency_exceeded with Retry-After: 1 — retry as soon as an earlier request completes. Keyed responses carry X-Concurrency-Limit. Keyless and Free have no concurrency limit: they are capped at 60 requests/min. Limits may change during the beta.

Rate-limit headers

Every keyed response — successes and 429s — tells you where you stand, so you can pace yourself and confirm a limit change from a single response:

Plans with a monthly allowance also return X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. The keyless worldip.io/{ip} endpoint reports its daily allowance in the same X-RateLimit-* headers (Reset = next 00:00 UTC) and has a separate 60/min burst guard.

{ "error": "rate_limited", "retry_after_sec": 42, "limit_per_min": 1200, "remaining": 0, "reset": 1790812842 }

Using your API key on the free endpoint

Send your key as Authorization: Bearer <key> to https://worldip.io/{ip} (HTTPS only — a key sent over plain HTTP is refused with 403 https_required) and basic lookups become unlimited: no 1,000/day cap and nothing deducted from your plan.

• Your key's own limits apply instead of the keyless 60/min burst guard: its concurrency limit (X-Concurrency-Limit) and per-minute limit (X-RateLimit-*).
• Responses carry X-Free-Daily-Limit, X-Free-Daily-Remaining, X-Free-Daily-Reset and X-Billing (free-daily within the first 1,000/day per requester IP, unlimited beyond it — both are free). In the body, _meta.keyless is false and _meta.billing matches.
• The key needs the ext:read scope. An invalid, disabled or malformed key returns 401/403 — it is never silently served as keyless. Use the header rather than ?key=, which ends up in logs.
• Browsers: the endpoint answers the CORS preflight for Authorization and exposes all of the headers above.

Errors

Errors use standard HTTP status codes with a JSON body of { "error": "...", "message": "..." } (the 429 body is shown above).

Plans & data tiers

Web lookups on worldip.io are always free and need no signup. The API adds a monthly allowance of enriched lookups and unlocks progressively richer data — proxy/threat classification, trust scoring, live BGP and Web3 node roles — while keeping a free, no-signup tier. Paid plans are not on sale yet; during the beta, keys come with issued.live Plus and Pro (see Beta keys).

Annual billing is two months free (~17% off). See full pricing for details. Paid plans and self-serve keys are not open yet; during the beta, keys come with issued.live Plus and Pro — Beta keys. Limits may change during the beta.

Get launch updates

Paid plans and self-serve keys are not open yet. Drop your email and we'll message you the day they open — and again for major new endpoints. No spam, unsubscribe anytime. Already on issued.live Plus or Pro? Get your free beta key instead.