NutriRef is a pay-per-call USDA nutrition data API designed specifically for AI agents, using the x402 micropayment protocol and settling in USDC on the Base mainnet. Its goal is to enable agents to directly obtain structured FoodData Central nutrition data without registration, without API keys, and without manual authorization processes.
Main capabilities
- Provides four endpoints: food search (search), food detail (detail), food comparison (compare), and recipe (recipe).
- All nutrition values are per 100 grams; missing nutrients return null rather than 0.
- compare returns the winner for each nutrient (e.g., highest protein, lowest sodium, etc.).
- recipe scales by grams and aggregates the nutrition data.
- search and detail cache USDA responses directly; compare and recipe combine based on cached detail data, requiring no additional USDA calls once the cache is warmed. Caching is an important cost lever: warmed requests can return within 50 milliseconds and do not access USDA.
How to use
- Use via MCP: NutriRef provides an MCP server that exposes the four endpoints as native tools. It can be installed from PyPI and then added in the MCP client configuration (such as Claude Desktop's claude_desktop_config.json, Claude Code's MCP settings, etc.). If you do not want to install it, you can run it on demand with uvx nutriref-mcp; if working from a cloned repository, you can run pip install -e ".[mcp]" and set command to python and args to ["-m", "mcp_server"]. The wallet needs USDC on the Base mainnet, and gas is paid by the facilitator, so only a stablecoin balance is needed. After configuration, the agent has four tools: nutrition_search, nutrition_detail, nutrition_compare, and nutrition_recipe, and automatically pays per call.
- Use via any HTTP client: unpaid requests return 402 Payment Required and x402 payment instructions. Any x402-compatible client will sign a gasless USDC authorization (EIP-3009) and automatically retry.
- Example response: GET /v1/nutrition/detail/173944.
- Self-hosting: NutriRef is open source, and the instance at nutriref.xyz is just one of many possible deployments. The mainnet requires a Coinbase CDP account and a public x402 facilitator (https://api.cdp.coinbase.com）；测试网可免费使用社区 facilitator（https://x402.org/facilitator）。
Use cases
- Add nutrition data query capabilities to Claude or other MCP agents.
- Build nutrition data applications that require pay-per-call and no API key management.
- Example: examples/meal-planner/ is a complete agent of about 150 lines that provides the four NutriRef endpoints to Claude as tools and asks it to plan a day of meals meeting calorie/protein targets. The example includes tool schemas and the payment loop, and is suitable as a reference when integrating NutriRef into your own agent; see examples/meal-planner/README.md for details.
Limitations and notes
- Each request costs approximately 0.001–0.005 USDC; the actual price is subject to the real charge.
- Requires a Base mainnet USDC balance; gas is paid by the facilitator.
- Data source is USDA FoodData Central.
- The live instance is at https://nutriref.xyz，规范见 /openapi.json, Swagger at /docs, and Bazaar discovery at /.well-known/x402.
- Acknowledgments: USDA FoodData Central provides the data, x402 provides the payment protocol, and fastapi-x402 provides the server middleware (a small EIP-712 patch was applied at startup to support Base mainnet USDC).
