datum 接入与购买帮助中心

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

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

• 用 Claude / Cursor / Windsurf / Cline 等智能体客户端 → 方式 A：MCP 一键接入（推荐，10 秒）
• 在用 OpenAI 接口的程序 / 平台 → 方式 B：OpenAI 兼容接入（只改 base_url）
• 自己写代码的开发者 → 方式 C：原始 HTTP + x402（最底层，什么语言都能用）
• 用 Coze 扣子 / Dify / FastGPT 等国内平台 → 方式 D：国内平台接入（填三样就通）

免费前 3 次调用免费（请求头带 X-Wallet: 0x你的钱包地址 即可）。数据免费通过 AI 总闸要数据 = 数据免费——你只付 AI 的钱，我们内部自动注入实时数据，帮你省 50-90% token。

我们的 MCP 端点 https://agentdatum.com/mcp 是标准 streamable-http，任何支持远程 MCP 的智能体都能接。接完立刻能用 36+ 个工具：13 个实时信号（黄金/加密/宏观）、19 个加工指标、AI 总闸、实时搜索、网页提取——全部即接即用。

🟣 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 = 成功

然后直接问："用实时数据帮我分析一下美股和恐慌指数"——AI 总闸会自动取数并分析。

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

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

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

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

我们的 https://agentdatum.com/v1 是标准 OpenAI 格式接口。任何"填 base_url 就能换模型"的工具、框架、代码都能接——不用注册、不用 API Key（Key 填什么都行，真正的鉴权是 x402 付款）：

base_url: https://agentdatum.com/v1
api_key:  任意字符串（x402 付款才是真正的钥匙）
model:    任意（自动换挡：聊天 $0.001 / 出图 $0.04 / 深度 $0.049）

# Python 示例（pip install openai）
from openai import OpenAI
client = OpenAI(base_url="https://agentdatum.com/v1", api_key="x402")
r = client.chat.completions.create(
    model="deep",   # 名字随意，总闸按内容自动换挡
    messages=[{"role": "user", "content": "黄金现在什么信号？结合实时数据分析"}],
)
print(r.choices[0].message.content)

首次调用返回 402 → 用任意 x402 钱包（如 Coinbase CDK / 支持 x402 的钱包）签名付款 → 自动返回结果。数据自动注入、免费。

# 第 1 步：发请求（前 3 次带免费钱包头直接拿数据）
curl -X POST https://agentdatum.com/api/v1/ai \
  -H "Content-Type: application/json" \
  -H "X-Wallet: 0x你的钱包地址" \
  -d '{"messages":[{"role":"user","content":"黄金信号+比特币价格"}]}'
# → 前 3 次直接返回数据；第 4 次起返回 HTTP 402 + PAYMENT-REQUIRED 头

# 第 2 步：用 x402 SDK 解析 402 → 钱包签名付款（USDC on Base，秒到）
#    pip install x402  （官方 Python SDK）

# 第 3 步：带 PAYMENT-SIGNATURE 头重试 → 拿到真实数据（HTTP 200）

数据端点同理：GET /api/v1/d/sig-gold 等，一个端点一个价格。完整端点清单：/.well-known/ai-catalog.json · /.well-known/x402.json。给 AI Agent 的机器可读说明：/llms.txt。

国内主流 AI 应用平台都支持 OpenAI 兼容接口——只需填三样东西（记住口诀：地址 /v1、Key 随便、模型名随便）：

API Base URL: https://agentdatum.com/v1
API Key:      x402（任意字符串即可，真正的鉴权是 x402 付款）
Model:        任意（总闸自动换挡：聊天 $0.001 / 出图 $0.04 / 深度 $0.049）

🟠 Coze 扣子（coze.cn）：工作空间 → 设置 → 模型 → 添加自定义模型 API → 协议选 OpenAI → 填上面三样 → 保存 → 在 Bot 编排页的模型下拉框选它。

🔵 Dify：右上角头像 → 设置 → 模型供应商 → 找到 OpenAI-API-compatible（注意不是 OpenAI）→ 添加模型 → 填上面三样。

🟢 FastGPT / n8n / 文心千帆 / 阿里百炼 / 讯飞星火：同样找"自定义模型 / OpenAI 兼容 / 自定义工具"入口，填同一套三样即可。

⚠️ 关键点：Model 名随便填（总闸不看模型名，按你提问的内容自动换挡到聊天/出图/深度）；API Key 随便填（x402 付款才是钥匙）。首次调用返回 402 → 钱包签名付款 → 自动返回结果。数据自动注入、免费（省 50-90% token）。

国内 C 端智能体 App 的插件/技能走各平台官方商店（用户不能自填远程地址），我们正在逐个申请入驻官方商店（元宝 OpenClaw 技能市场 / 千问 Agent 商店 / 豆包插件 / 文心智能体平台 / Kimi 等），上架后即可一键使用。

在那之前，最稳的国内路径：开发者/企业用方式 D（Coze / Dify / FastGPT）把我们配成"数据 + AI"节点，再发布成自己的 Bot 给大众用。

🎁 免费试用无门槛：所有端点前 3 次调用免费（请求头带 X-Wallet: 0x你的钱包地址），国内用户不需要 USDC 也能先体验全部 173 个数据端点 + AI 总闸。正式付费走 x402（USDC on Base），web3 开发者都很熟。

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"]     # 如 "49000"（6 位精度，= $0.049）

核查：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。

AI 推理类端点（如 /api/v1/deepseek/chat）只收 POST。GET 探测拿到的是"GET 的 402 签名"，但路由本身拒绝 GET，付款后重发 GET 仍被 405 挡下。

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

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

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

body 字段名不对。例如 deepseek/chat 要 {"messages":[{"role":"user","content":"hi"}]}，webfetch 其实是 GET 带 ?url= 参数，不是 POST。

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

# 聊天/推理类
POST /api/v1/deepseek/chat   {"messages":[{"role":"user","content":"你好"}]}
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/...。真实外部买家走公网不受影响。

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())