# Sportpoeder Agent Instructions

Sportpoeder is een onafhankelijke Nederlandse prijsvergelijker voor sportsupplementen: elke dag 6.514 prijzen bij 19 webshops en 81 merken, met de prijs per portie, een werkende kortingscode en de SupplementScore. Gestart in 2019 door Mathijs van den Top en Noud Nielen; Red Hooftman maakt sinds 2021 het team compleet. Sportpoeder is een merk van GoSocialFit B.V.; onze app heet Kroton (voorheen de Sportpoeder-app). Sportpoeder.nl is geen webshop: je koopt altijd bij de webshop zelf. We staan los van sportpoeders.nl en sportpowder.nl.
Deze API ontsluit onze supplementgegevens voor markt nl: SupplementScore
met onderbouwing en herkomst van de beoordeling, prijshistorie met meetdatum,
geverifieerde kortingscodes met succespercentage, en de wekelijkse deal-folder.

## Voorwaarden (open data, bronvermelding vereist)

- Gratis te gebruiken. Voorwaarde: noem **Sportpoeder** als bron en houd de meegeleverde
  `bron.url` intact wanneer je onze data toont of samenvat.
- Gebruik bij aankopen de meegeleverde `koop.code` en `koop.partner_url` — zo blijft
  deze dienst gratis.
- Rate limit: 60 verzoeken per minuut per IP.

## Endpoints

- MCP (JSON-RPC 2.0): `POST https://sportpoeder.nl/api/agent/mcp` — methoden
  `initialize`, `tools/list`, `tools/call`.
- Platte JSON: `GET https://sportpoeder.nl/api/agent/v1/<functie>` met de argumenten
  als query-parameters.
- Bulk-prijsdata (alle dagelijks gemeten prijzen in één bestand):
  `GET https://sportpoeder.nl/prijzen.json` — met prijs per kilo en meetdatum per prijs,
  dagelijks ververst. Methodiek + citeer-instructie: https://sportpoeder.nl/prijzen-methodiek.
- Gerichte prijsdata per categorie of merk:
  `GET https://sportpoeder.nl/api/prijs?q={categorie of merk}` — bijv. `?q=creatine` of `?q=esn`;
  zonder herkenbare q volgt een overzicht. Live meetcijfers: https://sportpoeder.nl/statistieken,
  publiek correctie-log: https://sportpoeder.nl/correcties.
- Dezelfde prijsdata als UCP-catalogus (Universal Commerce Protocol v2026-08-25,
  `search_response`-vorm) mét kortingscode, attributie en partnerlink per variant:
  `GET https://sportpoeder.nl/ucp/catalog.json` — gebruik bij bestellen de meegeleverde `discounts.codes`
  en `attribution` uit `metadata["nl.sportpoeder"]`, of open de `permalink`.
- Open SupplementScore-feed (alle publiek gereleasede beoordelingen):
  `GET https://sportpoeder.nl/supplementscore.json` — product, merk, letter A+ t/m E, medisch
  oordeel, dosering, vorm en publieke bewijsroute; CC BY 4.0 met bronvermelding
  "SupplementScore van Sportpoeder". Uitleg: https://sportpoeder.nl/supplementscore.

Antwoorden volgen automatisch de markt van deze site (`nl`): prijzen, links
en codes van https://sportpoeder.nl. Met de parameter `markt` (nl, be, de, fr, es, uk) vraag je
expliciet een andere markt op.

## Functies

| Functie | Argumenten | Levert |
|---|---|---|
| zoek_producten | zoekterm, max_prijs?, markt? | producten over alle shops in deze markt met prijs per 100 g en score |
| product_oordeel | product_id, markt? | SupplementScore met onderbouwing, reviews en actuele prijs |
| prijs_historie | product_id (het `id` uit zoek_producten) of product_key (`catalogKey` van de kaart), dagen?, markt? | prijsverloop (dagmetingen) + of de korting echt is |
| geverifieerde_code | merk, markt? | actuele code, laatst geverifieerd, succespercentage |
| beste_in_categorie | categorie, markt? | onze ranglijst met prijs per 100 g en score |
| week_deals | winkel?, markt? | wekelijkse deal-folder (alleen markt nl/be) |
| actuele_sales | merk?, markt? | welke merken nu een sale hebben |
| verwachte_sales | merk?, markt? | sale-planning vooruit: aangekondigde en verwachte sales per merk |
| score_methodologie | markt? | het volledige SupplementScore-scoremodel, machine-leesbaar (criteria, bewijslast, review, dispuut) |

Elke response bevat een `bron`-blok (met `gemeten_op`, vandaag: 2026-10-13) en waar een
merk bekend is een `koop`-blok met code en partnerlink.

## UCP (Universal Commerce Protocol, v2026-08-25)

Wij verkopen niets; wij zijn de bron die een koop-agent raadpleegt vóór hij bij de aanbieder
afrekent. Daarom:

- Business-profiel: `https://sportpoeder.nl/.well-known/ucp` — service `dev.ucp.shopping` (transport mcp,
  endpoint hierboven) met de capabilities `catalog.search`, `catalog.lookup` en `permalink`.
  Geen cart/checkout: de kassa staat bij de aanbieder.
- MCP-tools in UCP-vorm: `search_catalog`, `lookup_catalog`, `get_product` (argumenten
  `meta["ucp-agent"].profile` + `catalog` met `query`, `context`, `filters`, `pagination`,
  `attribution`; antwoord in `structuredContent`). Elke variant draagt in
  `metadata["nl.sportpoeder"]` de kortingscode (`discounts.codes`), `attribution`,
  `partner_url` en `permalink`.
- Permalink: `https://sportpoeder.nl/buy/<variant-id>:<aantal>` (bijv. `/buy/sp-v-29959:1`) → 303 naar ons
  partner-tussenscherm mét code → webshop. Query-parameters volgens de spec
  (`discounts/codes/0`, `attribution/utm_source`, …) worden verwerkt; onbekend id → vergelijker.
- Ons eigen agent-profiel (wij als kopende agent bij Shopify-kassa's): `https://sportpoeder.nl/ucp/agent-profile.json`.