nutriref

NutriRef

AI エージェント向けの、リクエストごとに支払う USDA 栄養データです。 x402 マイクロペイメントプロトコルを通じて FoodData Central の構造化データを提供します。エージェントはリクエストごとに $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	派生

すべての値は 100g あたりです。欠損している栄養素は 0 ではなく null です。compare は栄養素ごとの該当食品（タンパク質が最も多いもの、ナトリウムが最も少ないものなど）を返します。recipe はグラム数に合わせて換算し、合計します。

Claude（または任意の MCP エージェント）から使用する

NutriRef には、4 つのエンドポイントをネイティブツールとして公開する 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 が必要です。ガス代はファシリテーターが負担するため、ステーブルコインの残高だけが必要です。これでエージェントは nutrition_search、nutrition_detail、nutrition_compare、nutrition_recipe を利用でき、呼び出しごとの自動支払いが可能になります。

任意の HTTP クライアントから使用する

未払いのリクエストには、x402 の支払い手順を含む 402 Payment Required が返されます。x402 対応クライアントなら、ガス代不要の 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 は、実現可能な多数のデプロイのうちの 1 つです。独自の環境を実行するには、次の手順に従います。

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 ファシリテーター https://api.cdp.coinbase.com が必要です。テストネットは、コミュニティのファシリテーター 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 エージェント

examples/meal-planner/ は、NutriRef の 4 つのエンドポイントをツールとして Claude に提供し、カロリーとタンパク質の目標を達成する 1 日分の食事を計画させる、約 150 行の完全なエージェントです。NutriRef を独自のエージェントに組み込む場合は、ぜひご覧ください。ツールスキーマと支払いループがすべて記載されています。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（Base mainnet USDC 向けに、起動時に適用する小さな EIP-712 パッチを含みます）。