# FavouriteOdds best-markets widget — AI agent integration guide

STATUS: Provisioned partner embed. This guide describes the browser widget, not the commercial server-to-server API.
CONTRACT VERSION: data/v1 API 1.2.0; archive schema 6; widget refresh contract 15 seconds.

SAFE INTEGRATION
- Request a provisioned public embed token and iframe URL from FavouriteOdds.
- Embed `https://favouriteodds.com/widgets/best-markets?token=<public embed token>` in an iframe.
- A public embed token is revocable and limited to the widget's capped browser-safe dataset. It is not a commercial API key.
- Never put a commercial API key, Bearer credential, token hash, export URL, or server secret in HTML, JavaScript, a mobile client, source control, logs, prompts, or analytics.
- Do not replace the iframe with direct calls to `/data/v1`; commercial API calls must be server-to-server.

BRANDING
- Branding is provisioned server-side as `favouriteodds` or `white_label` and cannot be changed by query parameters or client CSS.
- `favouriteodds` renders the required “Powered by FavouriteOdds” attribution and link.
- `white_label` renders the contracted partner display name and no FavouriteOdds trademark.
- Never hide, cover, rewrite, or imitate attribution when the provisioned mode is `favouriteodds`.

IFRAME EXAMPLE
```html
<iframe
  src="https://favouriteodds.com/widgets/best-markets?token=fo_widget_provisioned_token&theme=light&locale=en"
  title="Best markets"
  loading="lazy"
  style="width:100%;min-height:640px;border:0"
></iframe>
```

RESIZING
- The widget posts `{ type: "favouriteodds:widget-resize", height: number }` to its parent when content height changes.
- Accept resize messages only when `event.origin === "https://favouriteodds.com"` and the height is a finite positive number.
- Apply a reasonable minimum and maximum height before changing the iframe.

DATA AND FAILURE RULES
- The widget refreshes every 15 seconds and retains its last valid snapshot during a transient refresh failure.
- Do not scrape rendered widget text or treat the iframe as a bulk-data API.
- Do not invent a market, price, fair probability, edge, event, or result when the widget is empty or unavailable.
- Treat displayed odds as time-sensitive information, not a guaranteed available price or outcome.
- The widget never places bets, manages bookmaker accounts, sends notifications, or moves funds.

SERVER-TO-SERVER ALTERNATIVE
- For custom rendering or larger datasets, use the provisioned commercial API described at https://favouriteodds.com/b2b/docs.
- Poll GET `/best-markets` no faster than its `refresh_after_seconds` value and atomically replace the previous complete snapshot.