nutriref

NutriRef

按次付费获取 USDA 营养数据，供 AI Agent 使用。 通过 x402 微支付协议获取结构化的 FoodData Central 数据——Agent 每次请求支付 $0.001–$0.005 的 USDC，无需注册、无需 API 密钥，也无需人工身份验证流程。

线上服务：https://nutriref.xyz。规范见 /openapi.json · Swagger 见 /docs · Bazaar 发现入口见 /.well-known/x402。

端点

方法	路径	价格	缓存
GET	/v1/nutrition/search?q=&limit=	$0.001	24 小时
GET	/v1/nutrition/detail/{fdc_id}	$0.002	7 天
POST	/v1/nutrition/compare	$0.003	派生
POST	/v1/nutrition/recipe	$0.005	派生

所有数值均按每 100 g 计算。缺失的营养素为 null，而非 0。compare 会返回每种营养素的优胜项（最高蛋白质、最低钠含量等）。recipe 按克数换算并求和。

在 Claude（或任何 MCP Agent）中使用

NutriRef 提供了一个 MCP 服务，将这四个端点作为原生工具开放。通过 PyPI 安装：

pip install nutriref-mcp

然后将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json、Claude Code 的 MCP 设置等）：

{
  "mcpServers": {
    "nutriref": {
      "command": "nutriref-mcp",
      "env": {
        "PAYER_PRIVATE_KEY": "0x...your-funded-wallet-key...",
        "NUTRIREF_BASE_URL": "https://nutriref.xyz"
      }
    }
  }
}

不想安装？可以使用 uvx nutriref-mcp 作为 command，按需运行。若要从克隆的仓库运行，则执行 pip install -e ".[mcp]"，并将 command 设为 python，args: ["-m", "mcp_server"]。

钱包需要在 Base 主网上有 USDC——手续费由 Facilitator 代付，因此你只需要持有稳定币。现在 Agent 可使用 nutrition_search、nutrition_detail、nutrition_compare、nutrition_recipe，并会自动按次付款。

通过任意 HTTP 客户端使用

未付款的请求会收到 402 Payment Required，其中包含 x402 付款说明。任何支持 x402 的客户端都可以签署免 Gas 的 USDC 授权（EIP-3009），并自动重试：

import asyncio
from eth_account import Account
from x402.client import x402Client
from x402.http.clients.httpx import wrapHttpxWithPayment
from x402.mechanisms.evm.exact import register_exact_evm_client

account = Account.from_key("0x...funded-wallet-key...")
client = x402Client(); register_exact_evm_client(client, account)

async def main():
    async with wrapHttpxWithPayment(client, base_url="https://nutriref.xyz") as http:
        r = await http.get("/v1/nutrition/detail/2012128")
        print(r.json())

asyncio.run(main())

响应示例

GET /v1/nutrition/detail/173944：

{
  "fdc_id": 173944,
  "description": "Banana, raw",
  "data_type": "Foundation",
  "serving_size": 100, "serving_size_unit": "g",
  "calories": 89.0,  "protein": 1.1,    "fat": 0.3,
  "carbs": 22.8,     "fiber": 2.6,      "sugar": 12.2,
  "sodium": 1.0,     "cholesterol": null, "saturated_fat": 0.1,
  "vitamin_c": 8.7,  "calcium": 5.0,    "iron": 0.3,  "potassium": 358.0
}

---

自托管

NutriRef 为开源项目；nutriref.xyz 上的线上实例只是众多可能部署方式中的一种。要运行自己的实例：

cp .env.example .env
# fill in USDA_API_KEY (free at https://fdc.nal.usda.gov/api-key-signup.html)
# and X402_RECEIVER_ADDRESS (an EVM address that should receive payments)
docker compose up --build
curl http://localhost:8000/health

配置

变量	必需	默认值	用途
USDA_API_KEY	是	—	从 fdc.nal.usda.gov 获取免费密钥
USDA_BASE_URL	否	https://api.nal.usda.gov/fdc/v1
REDIS_URL	否	redis://redis:6379/0	响应缓存
X402_NETWORK	否	base-sepolia	主网使用 base
X402_RECEIVER_ADDRESS	是	—	接收 USDC 的 EVM 地址
X402_FACILITATOR_URL	否	https://x402.org/facilitator	主网使用 https://api.cdp.coinbase.com
CDP_API_KEY_ID	仅主网	—	Coinbase Developer Platform 密钥 ID
CDP_API_KEY_SECRET	仅主网	—	Coinbase Developer Platform 密钥
LOG_LEVEL	否	INFO

主网需要 Coinbase CDP 账户，以及公开的 x402 Facilitator：https://api.cdp.coinbase.com。使用社区 Facilitator https://x402.org/facilitator，即可免费使用测试网。

架构

agent → x402 middleware → route handler → cache (Redis) → USDA FDC API

search 和 detail 直接缓存 USDA 响应。compare 和 recipe 使用缓存的 detail 数据组合结果——缓存预热后不会产生额外的 USDA 调用。缓存能显著降低成本：缓存命中的请求会在 <50ms 内返回，且不会访问 USDA。

测试

pip install -e ".[dev]"
pytest

示例：使用 NutriRef 的 Claude Agent

examples/meal-planner/ 是一个完整的 Agent，约 150 行代码。它将四个 NutriRef 端点作为工具提供给 Claude，并让 Claude 规划一整天的餐食，以达到指定的卡路里／蛋白质目标。如果你要将 NutriRef 接入自己的 Agent，值得一读——工具架构和付款循环都在其中。详见 examples/meal-planner/README.md。

仓库结构

app/                # FastAPI service
  main.py             # app factory + x402 init
  routes/             # search, detail, compare, recipe
  landing.py          # / (public landing page)
  discovery.py        # /.well-known/x402, /llms.txt, /.well-known/ai-plugin.json, /logo.svg
  usda.py             # async USDA client
  cache.py            # Redis wrapper
  normalize.py        # USDA → flat 13-nutrient schema
mcp_server/         # MCP server wrapper for agent use
examples/           # worked agent examples (meal planner)
scripts/            # CDP wallet bootstrap + payer-side test
tests/              # pytest + respx + fakeredis

致谢

• 感谢 USDA FoodData Central 提供数据。
• 感谢 x402 提供支付协议。
• 感谢 fastapi-x402 提供服务端中间件（我们会在启动时应用一个小型 EIP-712 补丁，以支持 Base 主网 USDC）。