crypto-sentiment-x402

Crypto Sentiment API (x402)

面向 AI Agent 的按次付费加密货币情绪 API。无需 API 密钥，也无需订阅——Agent 发现此 API 后，会收到 HTTP 402，在 Base 上支付 USDC，然后获取数据。

情绪来源（全部免费，无需密钥）：

• 加密货币新闻 RSS（9 家媒体）—— CoinDesk、Cointelegraph、Decrypt、Bitcoin Magazine、The Block、CryptoSlate、NewsBTC、CryptoPotato、The Defiant（DL News 已于 2026-10-04 移除：其信息流仅提供 2026 年 4 月至 5 月的条目）
• Fear & Greed Index — alternative.me

**评分：**采用 VADER 情绪分析，并扩展了加密货币俚语词典（moon、rekt、rug、hodl、bullish/bearish 等），以免俚语被判为中性。每条标题都会结合标题和信息流描述进行匹配与评分，并移除 HTML 标签、实体、信息流页脚和媒体自身名称（app/sources/news.py 中的 clean_text；自 2026-10-21 起使用方法 72h-hl24-v2）。只统计过去 72 小时内发布的标题，每条标题的权重会随时间每过 24 小时减半（app/window.py）。当有效样本量低于 5 时，标签为 insufficient recent news。

---

1. 获取 Base 钱包地址

你需要一个地址来接收 USDC 付款。任何标准的 Ethereum 风格钱包都可在 Base 上使用（例如 Coinbase Wallet、配置为使用 Base 的 MetaMask）。你不需要向此应用提供私钥——只需提供用于接收资金的公开地址。

2. 在本地运行（测试网——免费，无需真实资金）

cd crypto-sentiment-x402
cp .env.example .env
# edit .env and set PAY_TO_ADDRESS to your wallet address
pip install -r requirements.txt
uvicorn app.main:app --reload

访问 http://localhost:8000，即可看到 API 描述。 调用 http://localhost:8000/sentiment/BTC 时，如果没有付款，会返回 HTTP 402 和付款说明；这与 Agent 的 x402 客户端所看到的内容完全相同，客户端会自动据此操作。

如需实际测试付费调用，请使用官方 x402 测试客户端（需要 Base Sepolia 测试网 USDC，可从 Base Sepolia 水龙头免费获取）：

pip install x402
python -m x402.examples.client --url http://localhost:8000/sentiment/BTC

3. 部署（最简单的方式：Render.com）

1. 将此文件夹推送到新的 GitHub 仓库。
2. 前往 render.com → New → Blueprint → 连接仓库。 Render 会自动读取 render.yaml。
3. 系统提示时，将 PAY_TO_ADDRESS 环境变量设置为你的 钱包地址。
4. 部署。Render 会构建 Dockerfile，并提供一个公开的 HTTPS URL，例如 https://crypto-sentiment-x402.onrender.com。

就是这样——默认启用测试网模式，因此在你将 X402_NETWORK 切换为 mainnet（见下方第 4 步）之前，不会产生真实费用。

4. 启用真实 USDC 付款

1. 注册免费的 Coinbase Developer Platform 账户并创建 API 密钥——主网 facilitator（用于生产级付款验证/结算）需要此密钥。
2. 在 Render 中设置：
   • X402_NETWORK=mainnet
   • CDP_API_KEY_ID=...
   • CDP_API_KEY_SECRET=...
   • PAY_TO_ADDRESS = 你的 主网 Base 地址（请仔细确认它不是仅限测试网使用的地址）
3. 重新部署。此后调用会在 Base 主网上结算真实 USDC。

请先设置较低的价格（X402_PRICE_USD，默认为 $0.01），再验证整个流程是否正常。

5. 上架服务，让 AI Agent 找到并付费使用

这里就是 x402 Bazaar——Coinbase 的发现层，本质上是一个供 Agent 搜索 x402 服务的搜索引擎。

• 如果你使用的是 CDP facilitator（也就是按照第 4 步在主网运行），服务在通过它处理第一笔真实付款后，就会自动在 Bazaar 中被发现——无需单独注册。
• 为了让 Agent 更容易找到并理解你的服务，请确保 app/main.py 的 RouteConfig 中的 description 字段清晰且具体（已设置）——这段文字会显示在 Bazaar 搜索结果中。
• 你可以通过 https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources 查看当前的 Bazaar 列表（公开访问，无需密钥），确认服务上线后是否已显示。
• 可选的额外推广方式：将 API 提交到 x402bazaar.org，这是一个由社区运营的 x402 服务目录，与 Coinbase 自己的 Bazaar 相互独立。

MCP 服务（Claude Desktop / Claude Code）

更希望 Agent 通过 MCP 调用服务，而不是直接使用原始 HTTP？mcp_server.py 会将同一个 API 封装为 MCP 工具（crypto_sentiment、get_hourly_history 和三个免费信息工具）——该服务会通过自己的 CDP 托管钱包支付每次调用的费用，因此调用方无需直接接触加密货币。请参阅 MCP.md 了解设置方法。

免费试用

三个工具无需钱包、无需 CDP 密钥，也无需付费。服务无需任何 CDP 变量即可启动，因此你可以先安装并试用这些工具：

• list_supported_coins — 24 个受支持的代码符号和名称。
• archive_coverage — 小时级归档数据包含的内容（GET /archive）：首次读取时间、行数，以及每个代码符号缺失的小时数。
• price_quote(symbol) — 发起一次免费请求并读取 402 付款要求：价格、网络、资产和 payTo 地址。

两个付费工具使用你自己的 CDP 钱包，以 Base 上的 USDC 付款：

• crypto_sentiment(symbol) — 当前读数，每次调用 $0.01。 不受支持的币种以及近期新闻过少的币种会被拒绝，且不会收费。
• get_hourly_history(symbol, start, end) — 过去的小时级读数（GET /history/{symbol}），每次调用 $0.05。实时记录，不会回填；start/end 使用 ISO 8601 格式，默认查询最近 7 天，每次调用最多 30 天。代码符号必须是 archive_coverage 所列出的已记录符号。未记录的代码符号、无效范围以及没有读数的范围会被拒绝，且不会收费。

钱包设置方法见 MCP.md。

订阅套餐（Stripe，无需加密货币）

更愿意按月付费，而不是按次使用 USDC？GET /v1/sentiment/{symbol} 通过 X-API-Key 请求头而非 x402 付款进行访问，支持 Free / Starter（$15/月）/ Pro（$59/月）套餐。请参阅 BILLING.md 了解设置方法，或在运行中的实例上调用 GET /billing/pricing 查看当前价格。

情绪变化提醒

监测某个代码符号的情绪变化，并在情绪发生变动时通过 Webhook / Discord / Telegram 收到通知，无需自行轮询 /sentiment。已包含在 Starter/Pro 订阅套餐中——请参阅 ALERTS.md。

历史数据集导出

提供情绪读数历史数据（而非仅限当前读数）的访问权限——后台任务每天为每个代码符号保存一份快照，Pro 或“Data Access”套餐的订阅者可通过 GET /dataset/export 将目前收集的全部数据导出为 CSV 或 JSON。请参阅 DATASET.md （没有回填历史数据——只有从启用快照循环时开始的数据）。

同样登陆 RapidAPI

已上架 RapidAPI Hub，方便开发者通过 RapidAPI 的市场发现并购买，而不是直接通过 Stripe 或 x402 购买。底层数据相同，由 GET /rapidapi/sentiment/{symbol} 提供——只有经过 RapidAPI 代理路由的流量才会被接受（通过共享密钥请求头进行验证），因此此端点并非用于直接调用。这里的套餐与 Stripe 套餐一致：Free（每月 100 次请求）、$15/月（3,000 次请求）、$59/月（15,000 次请求）。

Zapier 和 TradingView 集成

将情绪变化提醒发送到 Zapier（通过现有的 webhook 渠道，无需新增端点），或为 TradingView 价格提醒补充实时情绪信息，然后转发到你的 webhook/Discord/Telegram。请参阅 INTEGRATIONS.md。

API 参考

端点	价格	说明
GET /	免费	服务信息
GET /health	免费	健康检查
GET /sentiment/{symbol}	$0.01（可配置）	某个代币的综合情绪，例如 /sentiment/BTC

付费响应示例：

{
  "symbol": "BTC",
  "name": "Bitcoin",
  "overall_sentiment": {
    "sample_size": 42,
    "average_compound": 0.21,
    "label": "bullish",
    "positive_pct": 55.0,
    "negative_pct": 15.0,
    "neutral_pct": 30.0,
    "unweighted_compound_72h": 0.17,
    "effective_sample_size": 31.4,
    "newest_headline_age_hours": 1.6,
    "window": "72h-hl24-v2"
  },
  "drivers": [{ "title": "...", "source": "CoinDesk", "link": "https://...", "published": "...", "score": 0.62, "weight": 0.93, "effect": 0.03 }],
  "drivers_summary": "3 of the top 5 headlines are positive, 2 are negative.",
  "breakdown": {
    "news": { "...": "..." },
    "fear_greed_index": { "value": 62, "classification": "Greed" }
  },
  "sources": ["coindesk.com RSS", "..."]
}

备注和限制

• 已移除 Reddit 作为数据源：Reddit 的 Responsible Builder Policy 禁止未经书面批准将其数据用于商业用途，而此付费 API 会违反该政策。app/sources/reddit.py 仍保留在仓库中，暂未使用，以备未来政策变更。
• 币种覆盖范围：app/coins.py 包含约 15 个常用代币的初始列表。可按需添加更多——未映射的代币仍可使用，只是新闻匹配准确度会稍低（会退回到按代币代码本身进行匹配）。
• 仅支持 Base/EVM 上的 exact 支付方案。如果你也想接受基于 SOL 的 USDC，x402 SDK 还支持 Solana（ExactSvmServerScheme）——请参阅 app/main.py 依赖项中的注释掉的导入语句。
• 可通过在 app/main.py 的 routes 字典中添加条目，增加其他付费端点（例如历史情绪、多代币批量查询）。