# NutriRef

> Pay-per-call USDA nutrition data for AI agents. Each request charges
> $0.001-$0.005 in USDC on Base mainnet via the x402 micropayment protocol.
> No signup, no API keys, no human auth flows.

## How to call it

Unpaid requests return HTTP 402 with payment instructions. Any x402-aware
HTTP client (e.g. the `x402` Python package) signs a gasless USDC
authorization (EIP-3009) and retries. Most LLM agents will want the MCP
server wrapper described below; humans wiring a script can also call the
HTTP API directly.

## Endpoints

- GET  /v1/nutrition/search?q={query}&limit={n}  -- $0.001 -- Search USDA foods by name; returns ranked matches with fdc_id, description, brand_owner, and macros.
- GET  /v1/nutrition/detail/{fdc_id}              -- $0.002 -- Full normalized nutrition (13 nutrients per 100g) for one food.
- POST /v1/nutrition/compare                        -- $0.003 -- Body: {"fdc_ids":[id,...]} (2-5 ids). Returns each food plus per-nutrient winners.
- POST /v1/nutrition/recipe                         -- $0.005 -- Body: {"ingredients":[{"fdc_id":id,"grams":g},...]}. Returns aggregate nutrition.

## Machine-readable

- OpenAPI: https://nutriref.xyz/openapi.json
- Swagger: https://nutriref.xyz/docs
- x402 Bazaar discovery: https://nutriref.xyz/.well-known/x402
- AI plugin manifest: https://nutriref.xyz/.well-known/ai-plugin.json

## MCP

The repo at https://github.com/Younghef/nutriref-api ships an MCP server
that exposes the four endpoints as native agent tools. Install and add
to a MCP client config:

    git clone https://github.com/Younghef/nutriref-api.git
    cd nutriref-api && pip install -e ".[mcp]"
    # then in your MCP client config:
    {
      "mcpServers": {
        "nutriref": {
          "command": "python",
          "args": ["-m", "mcp_server"],
          "env": {
            "PAYER_PRIVATE_KEY": "0x...funded-wallet-key...",
            "NUTRIREF_BASE_URL": "https://nutriref.xyz"
          }
        }
      }
    }

## Payment details

- Network: Base mainnet (chain id 8453)
- Asset: USDC at 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Receiver: 0x3f0a7f839619D578b8EEeD741C26F418b8E98e97
- Settlement: Coinbase CDP facilitator via the x402 protocol; payer wallets
  only need USDC, no native gas (EIP-3009 gasless authorizations).

## Nutrients tracked per /detail response

Per 100g: calories, protein, fat, carbs, fiber, sugar, sodium, cholesterol,
saturated_fat, vitamin_c, calcium, iron, potassium. Missing nutrients are
null, not zero.