{"openapi":"3.1.0","info":{"title":"NutriRef","summary":"Pay-per-call USDA nutrition API for AI agents (x402 / USDC on Base).","description":"Structured access to the USDA FoodData Central database, gated by the **x402** micropayment protocol. Agents pay per request in USDC on Base — no signup, no API keys, no human-in-the-loop auth. Unpaid requests get a `402 Payment Required` with payment instructions; x402-aware clients sign a gasless USDC authorization (EIP-3009) and retry automatically.\n\nFour endpoints: food search ($0.001), food detail ($0.002), side-by-side compare ($0.003), and recipe scale+sum ($0.005). All values per 100g; missing nutrients are `null`.","version":"0.2.0"},"paths":{"/v1/nutrition/search":{"get":{"tags":["nutrition"],"summary":"Search USDA foods by name","description":"Searches USDA FoodData Central for foods matching `q`. Returns ranked matches with their `fdc_id` plus a lightweight macro summary (calories, protein, carbs, fat). Use the returned `fdc_id` with /detail for the full nutrient breakdown. **Price: $0.001 per request.** Cached 24h.","operationId":"search_v1_nutrition_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Free-text food name to search (e.g. \"banana\", \"greek yogurt\").","title":"Q"},"description":"Free-text food name to search (e.g. \"banana\", \"greek yogurt\")."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Max number of results to return (1–50).","default":10,"title":"Limit"},"description":"Max number of results to return (1–50)."}],"responses":{"200":{"description":"Up to `limit` ranked food matches with fdc_id and macros.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/nutrition/detail/{fdc_id}":{"get":{"tags":["nutrition"],"summary":"Full nutrition for one food by FDC ID","description":"Returns the full normalized nutrition record for a USDA FoodData Central food, by `fdc_id`. All 13 tracked nutrients are returned per 100g; missing values are `null` rather than 0. Get the `fdc_id` from /search first. **Price: $0.002 per request.** Cached 7d.","operationId":"detail_v1_nutrition_detail__fdc_id__get","parameters":[{"name":"fdc_id","in":"path","required":true,"schema":{"type":"integer","title":"Fdc Id"}}],"responses":{"200":{"description":"Normalized food with 13 nutrient fields per 100g.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NormalizedFood"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/nutrition/compare":{"post":{"tags":["nutrition"],"summary":"Compare 2–5 foods side by side","description":"Fetches normalized nutrition for each `fdc_id` and computes per-nutrient winners. Higher-is-better fields (protein, fiber, vitamin C, calcium, iron, potassium) report the highest; lower-is-better fields (sodium, sugar, saturated_fat, cholesterol) report the lowest; calories/fat/carbs report both extremes. Composes from cached /detail calls. **Price: $0.003 per request.**","operationId":"compare_v1_nutrition_compare_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}},"required":true},"responses":{"200":{"description":"Foods array + per-nutrient winners (with criterion).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/nutrition/recipe":{"post":{"tags":["nutrition"],"summary":"Sum nutrition across a recipe of weighted ingredients","description":"Takes a list of ingredients as `{fdc_id, grams}` pairs, scales each food's per-100g nutrition by `grams/100`, and sums across all ingredients. Returns aggregate nutrition for the whole recipe. Composes from cached /detail calls. **Price: $0.005 per request.**","operationId":"recipe_v1_nutrition_recipe_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipeRequest"}}},"required":true},"responses":{"200":{"description":"Total grams, ingredient count, and summed nutrition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}},"head":{"tags":["meta"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Health Health Get"}}}}}}}},"components":{"schemas":{"CompareRequest":{"properties":{"fdc_ids":{"items":{"type":"integer"},"type":"array","maxItems":5,"minItems":2,"title":"Fdc Ids"}},"type":"object","required":["fdc_ids"],"title":"CompareRequest","example":{"fdc_ids":[2012128,173944]}},"CompareResponse":{"properties":{"foods":{"items":{"$ref":"#/components/schemas/NormalizedFood"},"type":"array","title":"Foods"},"winners":{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/Winner"},{"additionalProperties":{"$ref":"#/components/schemas/Winner"},"type":"object"}]},"type":"object","title":"Winners"}},"type":"object","required":["foods","winners"],"title":"CompareResponse","example":{"foods":[{"calories":312.0,"description":"BANANA","fdc_id":2012128,"protein":12.5,"sodium":594.0},{"calories":89.0,"description":"Banana, raw","fdc_id":173944,"protein":1.1,"sodium":1.0}],"winners":{"calories":{"highest":{"criterion":"highest","fdc_id":2012128,"value":312.0},"lowest":{"criterion":"lowest","fdc_id":173944,"value":89.0}},"protein":{"criterion":"highest","fdc_id":2012128,"value":12.5},"sodium":{"criterion":"lowest","fdc_id":173944,"value":1.0}}}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NormalizedFood":{"properties":{"fdc_id":{"type":"integer","title":"Fdc Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"brand_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Owner"},"data_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Type"},"serving_size":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Serving Size"},"serving_size_unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serving Size Unit"},"calories":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calories"},"protein":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Protein"},"fat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fat"},"carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carbs"},"fiber":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fiber"},"sugar":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sugar"},"sodium":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sodium"},"cholesterol":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cholesterol"},"saturated_fat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Saturated Fat"},"vitamin_c":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vitamin C"},"calcium":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calcium"},"iron":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Iron"},"potassium":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Potassium"}},"type":"object","required":["fdc_id"],"title":"NormalizedFood","description":"Flat per-100g nutrition for one food. Missing nutrients are null, not 0.","example":{"calcium":5.0,"calories":89.0,"carbs":22.8,"data_type":"Foundation","description":"Banana, raw","fat":0.3,"fdc_id":173944,"fiber":2.6,"iron":0.3,"potassium":358.0,"protein":1.1,"saturated_fat":0.1,"serving_size":100,"serving_size_unit":"g","sodium":1.0,"sugar":12.2,"vitamin_c":8.7}},"RecipeIngredient":{"properties":{"fdc_id":{"type":"integer","title":"Fdc Id"},"grams":{"type":"number","exclusiveMinimum":0.0,"title":"Grams"}},"type":"object","required":["fdc_id","grams"],"title":"RecipeIngredient","example":{"fdc_id":173944,"grams":150.0}},"RecipeRequest":{"properties":{"ingredients":{"items":{"$ref":"#/components/schemas/RecipeIngredient"},"type":"array","minItems":1,"title":"Ingredients"}},"type":"object","required":["ingredients"],"title":"RecipeRequest","example":{"ingredients":[{"fdc_id":173944,"grams":150.0},{"fdc_id":2012128,"grams":50.0}]}},"RecipeResponse":{"properties":{"total_grams":{"type":"number","title":"Total Grams"},"ingredient_count":{"type":"integer","title":"Ingredient Count"},"nutrition":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Nutrition"}},"type":"object","required":["total_grams","ingredient_count","nutrition"],"title":"RecipeResponse","example":{"ingredient_count":2,"nutrition":{"calcium":70.0,"calories":289.5,"carbs":54.5,"cholesterol":0.0,"fat":3.6,"fiber":3.9,"iron":1.01,"potassium":537.0,"protein":7.9,"saturated_fat":0.15,"sodium":298.5,"sugar":21.4,"vitamin_c":20.6},"total_grams":200}},"SearchHit":{"properties":{"fdc_id":{"type":"integer","title":"Fdc Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"brand_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand Owner"},"calories":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Calories"},"protein":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Protein"},"carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carbs"},"fat":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fat"}},"type":"object","required":["fdc_id"],"title":"SearchHit","description":"Lightweight subset used in search responses.","example":{"brand_owner":"Wonder Natural Foods Corp","calories":312.0,"carbs":40.62,"description":"BANANA","fat":6.25,"fdc_id":2012128,"protein":12.5}},"SearchResponse":{"properties":{"query":{"type":"string","title":"Query"},"count":{"type":"integer","title":"Count"},"results":{"items":{"$ref":"#/components/schemas/SearchHit"},"type":"array","title":"Results"}},"type":"object","required":["query","count","results"],"title":"SearchResponse","example":{"count":2,"query":"banana","results":[{"brand_owner":"Wonder Natural Foods Corp","calories":312.0,"carbs":40.62,"description":"BANANA","fat":6.25,"fdc_id":2012128,"protein":12.5},{"calories":89.0,"carbs":22.8,"description":"Banana, raw","fat":0.3,"fdc_id":173944,"protein":1.1}]}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Winner":{"properties":{"fdc_id":{"type":"integer","title":"Fdc Id"},"value":{"type":"number","title":"Value"},"criterion":{"type":"string","title":"Criterion","description":"Direction the winner was selected by: \"highest\" or \"lowest\"."}},"type":"object","required":["fdc_id","value","criterion"],"title":"Winner"}}}}