开发者 / Agent
API 文档
报告页上看到的一切都能用 JSON 拿到:一次调用返回评分、代理 / VPN / Tor 判定、黑名单与滥用记录、 分场景适用性、逐项扣分依据,以及这份数据的边界。无需 API key。 机器可读的描述在 /openapi.json,给模型看的站点说明在 /llms.txt。
命令行
在终端里直接查
纯文本报告,72 列以内,可以直接贴进论坛
查本机的出口 IP
curl -L ipure.dev # -L:跟随到 https 的跳转
curl -4L ipure.dev # 指定走 IPv4 出口,-6L 为 IPv6查指定 IP · 关掉颜色 · 用法说明
curl -L ipure.dev/cli/8.8.8.8
curl -L "ipure.dev/cli/8.8.8.8?color=0" # 不带终端转义码,方便贴到论坛
curl -L ipure.dev/cli/help一键脚本:服务端报告 + 本机侧检测
bash <(curl -sL ipure.dev/cli.sh) # IPv4 与 IPv6 各查一次
bash <(curl -sL ipure.dev/cli.sh) -x socks5://127.0.0.1:1080 # 经指定代理,测某个节点的出口
bash <(curl -sL ipure.dev/cli.sh) -4 -n # 只查 IPv4、只要服务端报告
# 本机侧检测:此刻从这个出口能不能连上 ChatGPT(网页 / App / API 与 OpenAI 看到的地区)、
# 出站 25 端口通不通(能否直接向 Gmail / Outlook 投递)。这些只能在你的机器上测,不计入纯净度。
# 不写文件、不需要 root、不安装任何东西。先看源码再跑:curl -sL ipure.dev/cli.sh规则与 JSON 接口完全一致:查自己的出口 IP 不需要验证;查别的 IP,库里已有的直接返回, 未收录的每个来源每天可查 5 个。脚本类客户端发起的新检测另有全站每日上限, 到顶后会提示到网页上查看,已检测过的 IP 不受影响。
端点
四个接口
- GET /api/v1/ip/{ip}
- 新集成推荐用这个。整份报告放在
data里, 外层是稳定的 v1 外壳;支持 IPv4 / IPv6、refresh=1与lang=en。外壳还带summary(给 Agent 的决策摘要)与score_model_version。 - GET /api/v1/ip/{ip}/history?limit=20
- 当前报告 + 历史检测,最新的在前。只读,不重新检测、不消耗数据源额度。
limit默认 20,最多 200;has_more表示还有更早的记录。 加lang=en可要英文等级与判据名; 每条带change_type,区分证据变化与评分模型变化。 - GET /api/lookup?ip={ip}
- 旧接口,保持兼容;返回裸报告,限流与额度与 v1 共用。新代码建议直接用 v1。 加
refresh=1忽略缓存与历史库强制重查。 - GET /api/myip?format=text
- 回显调用方的公网 IP。不带
format时返回{ ip }。
v1 外壳是调用方可以长期依赖的部分:request_id、schema_version、checked_at、confidence、cache(fresh / cache / store)、score_model_version(旧报告为 null)、summary(决策摘要,与 MCP 工具同一份)、sources、unknowns;报告本体在 data 里,外侧不再重复 sources / unknowns / scoreModelVersion。 每个响应都带 x-request-id;报错时读 error.code,不要只匹配 message。 如果你的 Agent 浏览环境会拦截 /api/ 路径, 继续用 /ip/{ip}.json 即可,数据相同。
历史项包含 checked_at、current、score_model_version、change_type、purity、level、label、usage_type、native_type、asn、flags、blocklist_hits、factors。 没收录过的 IP 返回 404 code = not_found, 先请求 v1 报告或在浏览器打开报告页。
MCP
给 Agent 的 MCP 服务器
托管地址:https://ipure.dev/mcp(Streamable HTTP,无鉴权)。 三个工具:inspect_ip、assess_ip_for_use_case、compare_egress_ips。 返回精简摘要与 report_url,完整字段仍用 v1 API; 查询与网页 / API 共用门禁和免验证额度。
Claude Code
claude mcp add --transport http ipure https://ipure.dev/mcpCodex CLI 或其它 MCP 客户端:URL 填 https://ipure.dev/mcp, 传输类型选 HTTP / Streamable HTTP。也可以用下面的配置:
mcp.json
{
"mcpServers": {
"ipure": { "type": "http", "url": "https://ipure.dev/mcp" }
}
}配额
谁能调、调多少
- 同一份报告的三个地址:网页
/ip/{ip}、JSON/ip/{ip}.json、纯文本/ip/{ip}.txt。.json与/api/lookup?ip=完全等价,限流与额度共用; 有些 AI Agent 的浏览环境会拦带查询参数的接口地址,路径式的不受影响。报告页里还内嵌了同一份 JSON(script#ipure-report)。 英文版:/en/ip/{ip}.json、/en/ip/{ip}.txt,或在接口上加lang=en:结论、扣分依据、场景说明都是英文,分数与等级代码不变。 - 已收录的 IP:直接返回库中报告,不消耗数据源配额,任何客户端可调。 站内已有近万份报告,热门地址基本都在。
- 未收录的 IP:会真实查询各数据源。脚本与 Agent 每个来源 IP 每天可免验证查询 5 次(全站每日另有总量上限),剩余次数在响应头
x-open-budget-remaining。 额度用完返回 403,code = verification_required, 并附reportUrl:在浏览器打开它完成一次检测,这个 IP 就进库了,之后可直接调用。 免验证查询全站每分钟另有 15 次的放行上限,挤满时返回 429,code = open_rate_limited,按Retry-After等几秒重试即可。 需要批量或定时检测一批 IP,请通过页面右上角的「反馈」联系我们。 - 限流:普通查询 30 次 / 分钟;首次查询新 IP 10 次 / 分钟;refresh 5 次 / 分钟。超出返回 429。
- 缓存:库中报告带
stale标记, 超过陈旧阈值的建议 refresh;IP 的性质本来就很少变,多数情况下直接用即可。
字段
响应里有什么
| ip / version | 规范化后的地址与协议版本(4 / 6) |
|---|---|
| queriedAt | 报告生成时间。source 为 store 时是当初检测的时间,配合 stale 判断要不要 refresh |
| source | fresh 实时查询 · cache 进程缓存 · store 历史库 |
| usageType | residential · mobile · business · hosting · education · government · unknown |
| nativeType | native 原生 · broadcast 广播(注册地与使用地不一致)· unknown |
| flags | isProxy / isVpn / isTor / isHosting / isMobile / isRelay / isBogon / isSearchEngineBot。二值字段,保留兼容 |
| flagAgreement | 每个判定位有几家数据源一致确认。单源判定在评分里按半数计权 |
| proxyAssessment | 代理 / VPN 判定的证据强度:status(confirmed / suspected / not_detected / unknown)、kind(tor / vpn / proxy / none)、confidence、positive_sources。摘要展示优先用它,不要把单源 suspected 说成确定事实 |
| vpnOperator | 已知商业 VPN 的运营商:name、anonymity、popularity、protocols、logging、freeAccess。没有则为 null |
| risk.purity | 纯净度 0-100,越高越干净 |
| risk.level / label / verdict | 六档:pristine 极佳 · clean 纯净 · neutral 一般 · suspicious 可疑 · risky 高风险 · dangerous 极高风险 |
| risk.confidence | low / medium / high —— 参与评分的数据源覆盖度。分数与置信度分开看:同样 85 分,两家源和八家源的把握不同 |
| risk.factors[] | 每一分的来源:label、category、points(正数扣分、负数加回)、detail、floor(一票否决的风险下限)、explanation(展开说明:meaning 这说明什么 · cares 哪些场景在意 · weighting 为什么这么算 · remedy 能不能改善,与报告页一致) |
| scenarios[] | 分场景适用性:ai · social · streaming · gaming · ecommerce · email,各有 score、level、levelLabel 与 reason。level 为 restricted(地区受限)或 not_applicable(不适用)时 score 为 null |
| scenarioApplicable | false 表示该地址是公共基础设施(公共 DNS、搜索引擎爬虫),不是用户出口,场景评估不适用;原因在 scenarioNote |
| blocklists[] | 各公开黑名单:listed 命中;benign 命中但不构成风险(如 PBL 住宅段声明);unavailable 本次不可用、命中与否未知 |
| abuse[] | 滥用举报(score、reports)与攻击行为记录(attacks.byType:撞库、批量注册、漏洞扫描等)。原始 reports 不等于已确认滥用;score=0 会带 note 说明 |
| exposure / sharing | 网络暴露面(开放端口、已知漏洞)与共享程度(同地址 / 同网段观测到的设备数) |
| sources[] | 每个数据源本次的状态:ok、ms、error、skipped。失败不等于未命中。只做定位兜底、不参与任何判据的补充源,没查到时不列出。v1 放在外壳;旧接口在报告里 |
| feedback | 实测反馈:正在用这个 IP 的访客给各场景打的真实使用体验分(1-5,5 最好)。按场景给出 count 与 average,某场景满 3 人才出现。它独立于评分,是评分之外的参照 |
| unknowns[] | 仅凭 IP 无法判断的事项,见下文。v1 放在外壳;旧接口在报告里 |
| reportUrl | 这份报告的网页地址,引用结论时请附上 |
边界
这份数据看不到什么
所有结论基于查询时刻的公开与合作数据源,不构成账号安全或平台准入的保证
平台内部的风控标签
各平台有自己的 IP 信誉库与封禁记录,不对外公开。公开数据源没命中,不等于平台那边没有记录。
是否真正独享
共享程度只是同网段观测到的设备数,看不出同一出口此刻还有谁在用、在做什么。
这个 IP 关联过哪些账号
账号与 IP 的关联关系只存在于各平台内部,前人在这个 IP 上被封过的账号我们看不到。
设备、浏览器与操作行为
风控看的是 IP + 设备指纹 + 行为节奏的组合。IP 再干净,指纹与行为异常照样会被拦。
账号资料与 IP 是否自洽
注册国家、手机号、支付方式、语言时区与 IP 归属地不一致时,平台会额外核验,这与 IP 纯净度无关。
示例
v1 调用示例
curl · 当前报告
curl -s "https://ipure.dev/api/v1/ip/8.8.8.8" | jq '{id: .request_id, purity: .data.risk.purity, verdict: .data.risk.verdict, cache: .cache, sources: [.sources[] | select(.ok) | .name]}'curl · 检测历史
curl -s "https://ipure.dev/api/v1/ip/8.8.8.8/history?limit=5" | jq '{count, has_more, history: [.history[] | {checked_at, current, purity, level, change_type}]}'Python
import requests
r = requests.get("https://ipure.dev/api/v1/ip/8.8.8.8", timeout=30)
r.raise_for_status()
body = r.json()
report = body["data"]
print(body["request_id"], body["cache"], report["risk"]["purity"], report["risk"]["verdict"])
for s in report["scenarios"]:
print(s["label"], s["score"], s["levelLabel"], "—", s["reason"])
print("无法判断:", [u["label"] for u in body["unknowns"]])TypeScript
const res = await fetch("https://ipure.dev/api/v1/ip/8.8.8.8");
if (!res.ok) {
const { error } = await res.json();
throw new Error(`IPure ${error.code}: ${error.message}`);
}
const { data: report, sources, unknowns } = await res.json();
const ai = report.scenarios.find((s: { id: string }) => s.id === "ai");
console.log(report.risk.purity, ai?.levelLabel, sources.length, unknowns.length);给 Agent
何时调用,何时不调
适合调用
用户问「这个 IP 干不干净」「能不能拿去登 ChatGPT / 注册 X / 开亚马逊店 / 看 Netflix」「是不是 VPN 或机房 IP」 「为什么老被风控」;需要在执行网络任务前判断当前出口 IP 是否合适;要在多个候选 IP 之间比较。
不该调用
DNS 配置与网站部署;网络连通性故障排查;需要目标平台内部风控数据才能回答的问题。 引用结论时请连同 unknowns 一起给出,不要把「未发现风险」说成「安全」。