datum 接入与购买帮助中心

一句话模型： datum 是一个只给 AI Agent 调用的数据 API 平台。每次调用一个端点 = 一次独立付费（x402 协议，Base 链 USDC）。不卖订阅、不卖 Key、不计量按时长。买家先发请求 → 服务端回 402 + 付费说明 → 买家钱包签名付款 → 服务端返回真实数据。

你是哪种用户？选一条路走：

• 用 Claude / Cursor / Windsurf / Cline 等智能体客户端 → 方式 A：MCP 一键接入（推荐，10 秒）
• 自己写代码的开发者（Python / JS / 任何语言） → 方式 B：HTTP 直连数据端点（一条命令拿数据）
• 要让程序无人值守自动付款 → 方式 C：x402 自动付费（额度用完自动续）
• 用 Coze 扣子 / Dify / n8n 等工作流平台 → 方式 D：HTTP 请求节点接入（填个地址就通）

免费每月白送额度，不用注册、不用 API Key：匿名每月 100 积分（请求头带 X-Anonymous-Id），绑个钱包地址升到每月 5000 积分（请求头带 X-Wallet: 0x你的地址，只要地址、不要签名、不要私钥）。1 积分 = $0.001。297 款现货数据产品：黄金信号、加密链上、美欧中宏观、股票、外汇、加工指标（L1-L5 五档加工层级）。

我们的 MCP 端点 https://agentdatum.com/mcp 是标准 streamable-http，任何支持远程 MCP 的智能体都能接。接完立刻能用 86 个工具——其中三个是万能钥匙：

• list_products — 免费列出全部 297 款产品（编号、美元价格、说明）
• get_product_info — 免费查任意一款的详情和付款方式（传入产品编号即可）
• fetch_data — 取数据（传入产品编号，可带钱包地址走免费额度）

其余 83 个是分好类的现成信号工具（黄金/白银、市场压力、美股龙头、全球指数、宏观、能源、就业、美债收益率、恐惧贪婪、聪明钱……），直接问就行。

🟣 Claude Desktop（Windows / Mac）

1. 打开配置文件：%APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）
2. 粘贴以下内容，保存后完全退出并重启 Claude：

{
  "mcpServers": {
    "agentdatum": {
      "url": "https://agentdatum.com/mcp"
    }
  }
}

3. 重启后点 🔨 工具图标，看到 agentdatum 就成功了。直接问："你们有哪些宏观数据产品？分别多少钱？"

💻 Claude Code（命令行）

claude mcp add --transport http agentdatum https://agentdatum.com/mcp
claude mcp list   # 看到 agentdatum = 成功

然后直接问："用工具取一下黄金信号 sig-gold，告诉我现在的动量和波动率"——它会自动取数并分析。

🟠 Cursor / Windsurf / Cline 等（项目级配置）

在项目根目录建 .mcp.json（Cursor）或 mcp_config.json（Windsurf / Cline），内容一样：

{
  "mcpServers": {
    "agentdatum": {
      "url": "https://agentdatum.com/mcp"
    }
  }
}

保存后在 MCP 面板点刷新，看到 agentdatum 即可。

每一个数据产品就是一个普通网址，GET 一下就返回 JSON。不用注册、不用 API Key——带上身份头直接调：

# 一条命令拿数据（匿名身份，走每月 100 免费积分）
curl "https://agentdatum.com/api/v1/d/sig-gold" \
  -H "X-Anonymous-Id: my-agent-001"

# 换成钱包身份，免费额度升到每月 5000 积分（只要地址，不要签名）
curl "https://agentdatum.com/api/v1/d/sig-gold" \
  -H "X-Wallet: 0x你的钱包地址"

Python 示例（pip install requests）：

import requests

headers = {"X-Wallet": "0x你的钱包地址"}   # 或 X-Anonymous-Id
r = requests.get("https://agentdatum.com/api/v1/d/sig-gold",
                 headers=headers, timeout=30)

print(r.status_code)              # 200 = 拿到数据；402 = 免费额度用完，该付款了
print(r.headers.get("x-datum-tier"))          # L3  -> 这一款是"加工指标"层
print(r.headers.get("x-datum-collected-at"))  # 数据采集时间
data = r.json()                   # 结构化 JSON，直接喂给你的程序或大模型
print(data["raw"]["signals"][0]["last_value"])

响应里白送的三个情报头（方便你判断数据新不新、值不值这个价）：

• x-datum-tier — 加工层级：L1 原始直采 / L2 标准接口 / L3 加工指标 / L4 复合信号 / L5 跨源派生情报
• x-datum-collected-at、x-datum-as-of — 数据采集时间、数据所属时点
• x-credits-cost、x-credits-left — 这次扣了几分、还剩几分

⚠️ 匿名身份限流 1 次 / 5 秒（绑钱包即解除限流，额度同时升到 5000/月）。

免费额度用完后，端点不会报错，而是返回 HTTP 402 + 一个 PAYMENT-REQUIRED 响应头——里面写清了"多少钱、付到哪个地址、走哪条链"。你的程序用 x402 协议签一笔小额付款，再重试一次就拿到数据。全程无需注册、无需订阅、按次付费。

# 第 1 步：照常请求（额度内直接 200 返回数据）
curl "https://agentdatum.com/api/v1/d/sig-gold" -H "X-Wallet: 0x你的钱包地址"

# 第 2 步：额度用完 -> 返回 HTTP 402
#   响应头 PAYMENT-REQUIRED (base64 JSON) = 付款单：
#     { 金额 amount / 收款地址 payTo / 网络 network / 资产 asset }
#   支持：USDC on Base  ·  USDT on X Layer

# 第 3 步：用官方 SDK 自动签付（Python）
#    pip install x402
#    from x402 import pay_and_retry
#    data = pay_and_retry(url, wallet_key="...")   # 自动解析402 -> 付款 -> 重试 -> 拿数据

# 第 4 步：带 PAYMENT-SIGNATURE 头重试原请求 -> HTTP 200 + 真实数据

用量越大越便宜（自动累计，不用申请）：累计 100 次 9 折 ｜ 500 次 8 折 ｜ 1000 次以上 7 折永久。

任何支持 x402 的客户端都能直接用（Coinbase CDK、各类 agent 钱包）。完整端点与价格清单：/.well-known/ai-catalog.json · /.well-known/x402.json。

这类平台不需要改模型设置——只要加一个「HTTP 请求」节点，把我们的数据端点填进去，再把返回的 JSON 交给大模型节点分析即可。填三样：

请求方式: GET
URL:      https://agentdatum.com/api/v1/d/sig-gold
请求头:   X-Wallet: 0x你的钱包地址     （或 X-Anonymous-Id: 任意编号）

🟠 Coze 扣子（coze.cn）：工作流编辑页 → 添加节点 → 选「HTTP 请求」→ 填上面三样 → 后面接一个「大模型」节点，把上一步的返回体作为输入，让它写分析结论。

🔵 Dify：工作流 → 添加节点 →「HTTP 请求」→ 同上；后面接 LLM 节点做解读。

🟣 n8n：加 HTTP Request 节点，Authentication 选 None，Headers 里加 X-Wallet；可接 Schedule Trigger 做定时取数。

🟢 FastGPT / 其他支持自定义工具的平台：找「自定义工具 / HTTP 请求」入口，填同一套三样即可。

⚠️ 返回 402 是正常流程（免费额度用完），不是错误——换绑钱包地址，或走方式 C 付款即可继续。

如果你不想手把手配，把下面任意一个地址直接丢给 AI，说一句"读一下这个，然后帮我取黄金信号"，它自己就知道我们有什么、怎么付钱：

• /llms.txt — 给 AI 读的说明书（产品清单 + 价格 + 免费额度规则 + L1-L5 层级）
• /.well-known/ai-catalog.json — 机器可读目录（298 条，每条含：访问地址、美元价格、加工层级、加工版还带溯源代码）
• /.well-known/agent-card.json — 智能体名片（我们是谁、能干什么、怎么接入）

🎁 先免费用再决定买不买：匿名每月 100 积分、绑钱包每月 5000 积分（1 积分 = $0.001），够你把 297 款产品试个遍。用完了按次付费，一次最低 $0.001（不到 1 分钱人民币）。

📖 想按图索骥挑产品？看我们的产品目录页：/catalog.html（含 L1-L5 加工层级对照表）。

1. 发现（Discovery）：通过 /.well-known/agent.json（A2A 名片）或 /.well-known/ai-catalog.json（ARD 目录）找到你要的数据端点与价格。
2. 发起请求：用 Accept: application/x402+json 请求目标端点（如 GET /api/v1/crypto/price）。
3. 收到 402：服务端返回 HTTP 402，并在 PAYMENT-REQUIRED 响应头里放一段 base64 编码的 JSON（含 accepts[].asset / amount / payTo / network）。响应 body 恒为 {}，付费信息不在 body 里。
4. 签名付款：客户端用 x402 SDK 解析该头，用 EVM 钱包对 eip155:8453 网络签名一笔 USDC 转账，把签名放进 PAYMENT-SIGNATURE 请求头重试。
5. 拿到数据：服务端验证付款后返回真实数据（HTTP 200 + JSON）。

流程依据：x402 官方 Seller/ Buyer 文档 — docs.x402.org · 协议官网 x402.org

问题 1：解析 x402 报价时找不到 maxAmountRequired / asset

客户端从响应 body 里找 maxAmountRequired、asset，永远找不到，误报"报价缺字段"。

x402 v2 把付费说明放在 响应头 PAYMENT-REQUIRED（base64 JSON），body 恒为 {}。旧版 v1 才用 body。

解码响应头，取 accepts[0].asset 与 accepts[0].amount：

import base64, json
hdr = r.headers.get("PAYMENT-REQUIRED")   # 或 "payment-required"（HTTP 头名大小写不敏感）
info = json.loads(base64.b64decode(hdr).decode())
asset  = info["accepts"][0]["asset"]      # 0x8335...2913 (USDC)
amount = info["accepts"][0]["amount"]     # 如 "50000"（6 位精度，= $0.05，即 sig-gold 这一档）

核查：x402 PyPI 文档 "HTTP Headers / V2 Protocol" — pypi.org/project/x402

问题 2：密集请求被 429 限频

前 ~20 个请求正常，第 21 个起全部 429。

服务端限频：单真实 IP 60 次 / 60 秒滑动窗口（全局 800/60s）。单 IP 连续发几十个请求会撞满窗口。

客户端做全局节奏控制，保证任意 60 秒窗口内请求数 < 60（如 ~1.3s/请求），并对 429 做退避重试（读 Retry-After）。

问题 3：RPC 端点宕机导致余额查询失败

用 base.llamarpc.com 查 USDC 余额时返回 Cloudflare 521（源站无响应），所有余额检查失败。

单一公共 RPC 节点的可用性问题。免费节点常被限流或临时下线。

配置主备多端点，任一通即用：base.publicnode.com（主）、rpc.ankr.com/base、base.llamarpc.com（备）。USDC 合约 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 的 balanceOf selector = 0x70a08231。

USDC Base 合约经 Circle 官方确认 — developers.circle.com/stablecoins/usdc-contract-addresses

问题 4：测试用钱包"意外有钱"

本想用空钱包验证"没钱被拒"，却发现地址里已有 200+ USDC（链上被人误转）。

随手写的"测试地址"（如 0x000...0001）是公开地址，任何人都可能误转币进去，余额不可控。

验证"空钱包"用零地址 0x0000000000000000000000000000000000000000 或 0x000...dEaD 烧包地址——它们永久余额=0，不可能被误转，彻底消除误报。

问题 5：POST 端点用 GET 触发 405 Method Not Allowed

先 GET 探测拿到 402 并付款，付款后重发 GET 却返回 405。

先探测方法的响应：若首次请求返回 405，说明该端点只收 POST——改用 POST 重新发起请求，拿到 POST 自己的 402，再对 POST 的 402 正确签名付款。x402 签名是 method-specific 的，GET 的签名不能复用到 POST。

问题 6：POST body 格式不对导致 400

POST 请求返回 400，卡在参数校验，根本没到付费墙。

先发一个参数正确但无付款的请求触发 402（说明参数对了），再付款。各端点正确 body 见其工具页 /tools/<name>.html。常见模板：

POST /api/v1/data-guide      {"topic":"macro"}
# 抓取类（GET 带参，非 POST）
GET  /api/v1/webfetch?url=https://example.com

问题 7：VPS / 数据中心 IP 公网直连被 403

从 VPS（数据中心 IP，如 Vultr AS20473）直连 https://agentdatum.com/... 返回 403，但本地或浏览器正常。

Cloudflare 按数据中心 IP 声誉拦截（非 bug，是反爬策略）。Wikipedia/jina 等站同理。

服务端自测/自购时走 localhost 绕开 Cloudflare：http://localhost:8080/api/v1/...。真实外部买家走公网不受影响。

不用注册、不用 API Key。1 credit = $0.001（约人民币 7 厘），每月自动重置：

身份	每月免费额度	怎么领取
匿名访客	100 credits（约 $0.1）	请求时带一个任意自取的身份号：X-Anonymous-Id: 你的任意ID
绑定钱包地址	5000 credits（约 $5）	带只读钱包地址：X-Wallet: 0x你的地址。只是地址、不需要签名、不需要私钥
上月付过费	下月 再 +5000	自动发放，无需申请

额度用完后不会报错，而是返回 HTTP 402（意思是"该付钱了"），按下面第四节付款即可继续用。

按次付费，全站共 297 款收费产品，共 5 档价格，全部用 Base 链 USDC 结算。

单次价格	该档产品数	代表产品
$0.001	8 款	crypto-orderbook, space-nasa, weather-now, us-stock-tech, media-nasa-img 等
$0.01	257 款	eu-trade, water-usgs, public-health, food-safety, worldbank-econ 等
$0.05	27 款	sig-us-mega-cap, sig-global-indices, sig-macro-us, sig-gold, sig-stock-report 等
$0.10	1 款	sig-market-stress
$0.30	4 款	l5-macro-synthesis, l5-crypto-synthesis, l5-fx-synthesis, l5-global-macro-synthesis

完整价目表（含每一款的名字、价格、加工层级 L1-L5）：价目表页面 ｜ 机器可读版：产品目录（JSON）

from x402 import x402ClientSync
from x402.mechanisms.evm.exact import ExactEvmScheme
from eth_account import Account

signer = Account.from_key("0x你的私钥")
client = x402ClientSync()
client.register("eip155:*", ExactEvmScheme(signer=signer))

# 请求受保护端点，SDK 自动处理 402 → 签名 → 重试
r = client.get("https://agentdatum.com/api/v1/crypto/price")
print(r.status_code, r.json())