使用可查验的 x402 证据进行开发。

curl -G "https://ifandonlyif.io/api/v3/evidence/check" \
  --data-urlencode \
  "url=https://api.example.com/paid-resource"

成功回应封装

{
  "success": true,
  "data": {
    "endpoint": {
      "id": "ENDPOINT_UUID",
      "url": "https://api.example.com/paid-resource",
      "name": "Example x402 API"
    },
    "operational_status": "passing",
    "ownership": {
      "status": "verified",
      "method": "iff-well-known"
    },
    "protocol": {
      "status": "pass",
      "version": 2,
      "payment_options": [],
      "check_codes": ["x402_v2_valid"]
    },
    "availability": [
      {
        "window": "24h",
        "samples": 288,
        "reachable_rate": 100,
        "protocol_pass_rate": 99.7,
        "p50_latency_ms": 84,
        "p95_latency_ms": 190
      }
    ],
    "freshness": {
      "status": "fresh",
      "observed_at": "2026-07-12T04:30:00Z",
      "interval_seconds": 300
    },
    "evidence": {
      "report_hash": "HEX_SHA256",
      "monitor_id": "iff-production-monitor",
      "monitor_version": "3.0.0",
      "monitor_signature_algorithm": "ML-DSA-65",
      "monitor_signature": "BASE64_ML_DSA_65_SIGNATURE",
      "monitor_public_key": "BASE64_ML_DSA_65_PUBLIC_KEY"
    }
  }
}

1. 要求 challenge

   challenge 会绑定 domain、URI、chain、wallet、nonce 与到期时间。

2. 签署完全相同的讯息

   以同一钱包地址，将返回的 message 原封不动交给 personal_sign。请在提示中核对 domain、wallet 与 expiry。这是登入 signature，不是 payment 或 token approval。IFF 永远不需要你的 private key 或 recovery phrase。

3. 交换并轮替

   取得 access_token、refresh_token、token_type 与 expires_in。下方范例以 $ACCESS_TOKEN 代表 access token。每个 refresh token 仅能使用一次：refresh 后请替换两个 token。

curl "https://ifandonlyif.io/api/v3/auth/challenge" \
  -H "content-type: application/json" \
  -d '{"wallet_address":"0xYOUR_WALLET"}'

curl "https://ifandonlyif.io/api/v3/auth/verify" \
  -H "content-type: application/json" \
  -d '{
    "challenge_id":"CHALLENGE_UUID",
    "wallet_address":"0xYOUR_WALLET",
    "message":"EXACT_MESSAGE_FROM_SERVER",
    "signature":"0xSIGNATURE"
  }'

curl 无法签署，signature 来自你的钱包。上例是 request template。请提交原始的 challenge_id 与 message 及钱包的 signature，并以 JSON serializer 建立 body，例如 JSON.stringify({ challenge_id: challenge.challenge_id, wallet_address: wallet, message: challenge.message, signature })。不要将 literal newline 贴入 JSON，也不要自行重建 message。token 请勿出现在 URL、截图、source code 与 shell history。

curl "https://ifandonlyif.io/api/v3/auth/refresh" \
  -H "content-type: application/json" \
  -d '{"refresh_token":"REFRESH_TOKEN"}'

challenge 五分钟后到期且只能使用一次。拥有者回应使用 Cache-Control: no-store。

回应含唯一的 claim_attempt_id 与 ownership object（challenge、expires_at、verification_url、document）。challenge 有效 24 小时。任何已验证钱包都可建立独立 attempt；pending attempt 不能读取 private observation、手动 probe、管理 webhook、连结 ERC-8004 或取消发布。

curl "https://ifandonlyif.io/api/v3/endpoints" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "url":"https://api.example.com/paid-resource",
    "name":"Example x402 API",
    "description":"Payment-gated resource"
  }'

201 Created：新 endpoint 与 claim attempt。200 OK：既有 endpoint 新增 attempt。请将 endpoint_id 存为 ENDPOINT_UUID，并保留 claim_attempt_id 供 polling。两者都不排入 verification，也不授予 owner access。等待时请勿重复注册。

对於单一 endpoint，请将回应中的 ownership.document 原封不动发布在 ownership.verification_url，例如：

同一 origin 的 endpoint 共用此档案。新增前请备份目前的 document。将既有 single claim 包成 {"claims":[...]} 的第一项并附加新的 ownership.document，或直接附加到既有 array。保留其他 endpoint 的 claim 与完全相同的 challenge。切勿以最新回应取代整个档案；IFF 不会合并。

旧版 single-claim format 仍受支援。multi-endpoint format 只有一个 top-level field claims：1–64 个 object，每个恰含 endpoint_id、owner_wallet 与 challenge，使用 API 提供的非空值（canonical lowercase UUID、Ethereum wallet address、完全相同的 challenge）。wallet 比对忽略大小写。body 须在 16 KiB 以内。unknown 或重复的 JSON field、重复 endpoint ID、混用 format 或任何 malformed entry 都会使整个档案被拒绝。更新时只替换该 endpoint 的项目。请持续保留有效 claim，供定期 domain-control recheck。

curl -X POST \
  "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/verify-ownership" \
  -H "authorization: Bearer $ACCESS_TOKEN"

此 verification request 返回 202 Accepted：job 已排入伫列，尚未验证。请遵循 Retry-After（目前为 5 秒），再用同一钱包的 access token polling：

curl "https://ifandonlyif.io/api/v3/endpoints?page=1&page_size=20" \
  -H "authorization: Bearer $ACCESS_TOKEN"

于 data.claim_attempts[].id 找到已保存的 attempt ID（必要时查看后续页面），读取 status、outcome_code 与 verification_failures。pending 不是成功；verified 表示 proof 通过；failed、expired、superseded 已结案。data.endpoints 列出 authoritative ownership。后续注册不会轮替另一钱包的 challenge。只有成功的 same-origin proof 可取代 owner；transfer 会停用旧 webhook 并重设发布资格。

检查失败后 attempt 仍为 pending 时，请修正已部署的档案，并在 24 小时内重新排入 verification。attempt 已到期或结案时，请重新注册该 URL、发布新 document 并排入新 attempt。verification 返回 409：没有可用的 pending attempt。503：queue 不可用，不代表通过；请以 backoff 重试。401：更新 token 或重新登入。

拥有权验证通过后

owner access 与首次发布是不同步骤。verified-tier card 在 ownership verification 完成且至少三笔通过的 initial 或 scheduled observation 后才公开；manual probe 不计入。等待期间公开 404 不代表 ownership 验证失败。请用仅限 owner 的 history 诊断：

curl "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/observations?page=1&page_size=20" \
  -H "authorization: Bearer $ACCESS_TOKEN"

读取 data.observations 与各 probe_type。要求 private diagnostic 时，执行下方命令，再 polling 此 history 等候新的 manual observation。202 仅确认已排入伫列。manual 结果不会变更 public card、发布资格、manifest 或通知。

curl -X POST \
  "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/probes" \
  -H "authorization: Bearer $ACCESS_TOKEN"

接著请设置变更通知。要停止监测并隐藏卡片，请使用下方仅限 owner 的动作。它也会停用 webhook 与 pending delivery，但保留 immutable observation、claim-attempt audit 与 transparency-log entry。快取的卡片最多可再显示 30 秒。要恢复，请重新注册该 URL 并再次证明控制权。

curl -X DELETE \
  "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID" \
  -H "authorization: Bearer $ACCESS_TOKEN"

成功停止返回 204 No Content。wallet 没有目前的 verified 或 stale claim 时，owner management route 返回 404（仅有 pending attempt 不足）。claim 为 stale 时，history 与停止仍可用，但建立 webhook 或 manual probe 会返回 409，直到 ownership 再次验证。

公开与验证

已验证的钱包与 endpoint 拥有者

下方每个 route 都需要 Authorization: Bearer <access_token>。registration、polling 与 verification 限建立 attempt 的 wallet；management route 需 verified 或 stale ownership。

ownership

目前的 domain-control 状态、方式与验证时间。

protocol

最新的 x402 解析结果、版本、各项具名检查与宣告的 payment option。

availability

24 小时与 7 天的样本、百分比与 p50/p95 latency。

freshness

最新 observation 是否仍在发布所需的 freshness window 内。

evidence

Canonical report hash、monitor identity、ML-DSA-65 signature（旧 report 为 Ed25519）与 public key。

anchor

可选的每日 manifest 链上状态与 transaction provenance。

rate 为 0 至 100 的百分比。缺少的 measurement 会略去或为 null；请勿推论为通过。

observed tier 的 probe 也会按 UTC 日计数。每个结束的日子会封存成一份每日确认文件，其 hash 以一个 leaf 进入 transparency log；启用 change-only storage 后，只有 observed state 变动时才保存完整的签名 observation。GET /api/v3/evidence/observed-confirmations/:day（或 /latest）返回原始 body、document_hash、leaf_hash 与承诺等级：sealed、logged 或 anchored。这是 monitor 观测到的统计，不证明每次 probe 都实际执行。

curl "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/webhooks" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"target_url":"https://hooks.example.com/iff"}'

建立订阅需 verified ownership，返回 201 Created，含 id、target_url 与 secret。请将 ID 存为 WEBHOOK_UUID，并把 secret 存放于接收端服务器；secret 只显示一次，无法取回。target 须为公开 HTTPS/443，不得含 credentials、query string、fragment 或 redirect。作用中 target 重复或作用中订阅超过 10 个，返回 409。

建立订阅不传送测试事件。事件随符合资格的 observation 变更而触发，不随每次 probe。依赖通知前，请先验证下列 header。

1. 拒绝超出允许 clock-skew 范围的 timestamp。
2. 使用仅显示一次的 secret，对 timestamp + "." + raw_body 计算 HMAC-SHA256。
3. 以 constant-time 比较 hex digest。
4. 依 Idempotency-Key 去重；重复传送仍应回应 2xx。

curl "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/webhooks" \
  -H "authorization: Bearer $ACCESS_TOKEN"

curl -X DELETE \
  "https://ifandonlyif.io/api/v3/endpoints/ENDPOINT_UUID/webhooks/WEBHOOK_UUID" \
  -H "authorization: Bearer $ACCESS_TOKEN"

清单位于 data。删除返回 204 No Content，停止待传送项目，不取消发布 endpoint。遗失 secret 时请删除并重建订阅。切勿在 client-side code 暴露 secret。

curl "https://ifandonlyif.io/api/v3/verify" \
  -H "content-type: application/json" \
  -d '{
    "url":"https://api.example.com/v1/quote",
    "payment_required":{"x402Version":2,"accepts":[{
      "scheme":"exact",
      "network":"eip155:8453",
      "asset":"0xab12cd34ab12cd34ab12cd34ab12cd34ab12cd34",
      "amount":"1000",
      "payTo":"0xef56ab78ef56ab78ef56ab78ef56ab78ef56ab78",
      "maxTimeoutSeconds":60
    }]}
  }'

TypeScript SDK

npm install @ifandonlyif/x402-preflight — 使用 verify()、wrapFetch() 或内含的 MCP command。阅读 SDK 指南.

Direct API

可从任何程序语言使用 POST /api/v3/verify。公开 Preflight 检查不需要 API key。

Badge

![x402 evidence](https://img.shields.io/endpoint?url=https://ifandonlyif.io/api/v3/badge/ENDPOINT_UUID.json)

实验性功能展示：Service Receipt v2

Service Receipt v2 是单一 verification result 的可选 signed artifact，不属于 core preflight contract。它将 response、verification-request digest 与五分钟 action window 绑定于 IFF 专用 ML-DSA-65 receipt key。略去 receipt 或传送 null 不改变 response；{} 或 "version":"2" 签发 v2，"1" 返回 422。既有 v1 receipt 仍可验证。

"receipt":{"version":"2","nonce":"checkout_7f3a"}

已签署的 artifact

成功选用此功能后会新增 service_receipt，不会变更其他 response field。

本机 verifier

将独立 envelope 或完整 API response 贴入Receipt 展示页（英文）。验证会在浏览器本机执行。

curl "https://ifandonlyif.io/api/v3/receipts/keys"