# Feelia for AI agents and developers

Feelia tracks Kick streamers whose on-stream activity is casino slots, poker, sports betting, casino table games or crypto trading, and sells that research data to iGaming affiliate and partnerships teams. This page is the machine-access contract: a REST API at `https://feelia.uk/v1`, an MCP server at `https://feelia.uk/mcp`, one API-key header for both, and self-service ways to pay.

Feelia is not a gambling operator and does not promote gambling to consumers. Contacts are publicly listed business contacts with source attribution; streamers opt out at `https://feelia.uk/optout/<slug>` and the opt-out is honoured everywhere, including this API.

## Authentication

One header, everywhere:

```
Authorization: Bearer fk_live_…
```

How to get a key:

1. **Pro subscription** ($40/month or $400/year, crypto billing): log in at `https://feelia.uk/app` → **API keys** → create. Unlimited requests within the rate limit, contacts included.
2. **Buy a 24-hour or 30-day key with a crypto invoice** (USDT, BTC, ETH and more) — no account needed, see *Buy a key* below.
3. **Buy a key with one x402 payment** (USDC on Base) — when x402 is enabled on this deployment; `GET /v1/pricing` tells you.

Keys never carry dashboard-admin rights. An invalid, revoked, expired or not-yet-paid key answers `401 {"error":"invalid_api_key"}`.

## Free tier (no key)

- `GET /v1/pricing`, `GET /v1/access`, `GET /v1/stats`, `GET /v1/brands` — always free.
- `GET /v1/search` with `limit<=5` — 20 searches per day per IP.
- `GET /v1/streamers/{id}` — 5 profiles per day per IP.
- MCP tools `feelia_about`, `feelia_list_brands`, and the same preview quotas for `feelia_search_streamers` / `feelia_get_streamer`.

When the preview is exhausted or you ask for more, priced routes answer **`402 Payment Required`** with a JSON body that repeats the options below (and x402 headers when enabled).

## REST endpoints

| Method & path | Access | Purpose |
|---|---|---|
| `GET /v1/pricing` | free | prices, networks, how to pay (machine-readable) |
| `GET /v1/access` | free | who you are: tier, key status, remaining free quota |
| `GET /v1/stats` | free | catalog counters |
| `GET /v1/brands?days=30&limit=50` | free | sponsor brands ranked by distinct streamers |
| `GET /v1/search?…` | preview · key · x402 | search streamers; filters: `activity` (casino, poker, betting, crypto or exact slots/sports_betting/casino_table/crypto_trading), `language`, `country`, `brand`, `exclude_brands`, `sponsor_status` (free/dormant/active), `min_avg_viewers`, `max_avg_viewers`, `min_followers`, `is_live`, `coverage=category_mismatch` (covert only), `max_risk`, `sort`, `limit` (≤50), `offset` |
| `GET /v1/streamers/{id or slug}` | preview · key · x402 | profile: 30-day rollup, brands, sponsor timeline, brand history, recent streams, risk score — no contacts |
| `GET /v1/streamers/{id or slug}/contacts` | key | publicly listed business contacts with source and last-verified date |
| `POST /v1/keys/cryptocloud` `{"plan":"day"}` | free to call | mint a pending key + crypto invoice |
| `POST /v1/keys/x402/{day|month}` | x402 | mint an active key with one USDC payment (when enabled) |
| `GET /v1/keys/me` | key (pending or active) | key status, expiry, today's usage, checkout_url while pending |
| `POST /v1/keys/recover` | x402 signature | re-issue a never-used key whose purchase response was lost |

Full schema: `https://feelia.uk/openapi.json` (only `/v1` is published). Rate limits: 30 requests/min anonymous, 60/min per x402 payer, 120/min per key, 5 key purchases per hour per IP. Responses carry `X-RateLimit-Limit` / `X-RateLimit-Remaining`; `429` carries `Retry-After`.

### Examples

```bash
# free preview, no key
curl "https://feelia.uk/v1/search?activity=casino&language=es&sponsor_status=free&limit=5"

# with a key
curl -H "Authorization: Bearer fk_live_…" "https://feelia.uk/v1/search?activity=betting&min_avg_viewers=200&limit=25"
curl -H "Authorization: Bearer fk_live_…" "https://feelia.uk/v1/streamers/classybeef"
curl -H "Authorization: Bearer fk_live_…" "https://feelia.uk/v1/streamers/classybeef/contacts"
```

## Buy a key

### With a crypto invoice (USDT, BTC, ETH …) — works today

```bash
curl -X POST https://feelia.uk/v1/keys/cryptocloud -H 'Content-Type: application/json' -d '{"plan":"day"}'
```

Response `201`: `key` (store it — shown once), `status: "pending"`, `checkout_url`, `invoice`. Pay the invoice; the key activates within ~5 minutes of confirmation. Poll:

```bash
curl -H "Authorization: Bearer fk_live_…" https://feelia.uk/v1/keys/me
```

Plans: `day` = $2.00 for 24 hours, `month` = $40.00 for 30 days (validity counts from activation). Keys include the `contacts` scope.

### With x402 (USDC on Base) — when enabled

`POST https://feelia.uk/v1/keys/x402/day` answers `402` with a `PAYMENT-REQUIRED` header (x402 v2, `exact` scheme, upfront flow). Sign the USDC authorization with any x402-capable client or wallet, retry with `PAYMENT-SIGNATURE`, and the `201` body contains `key`. Lost the response? `POST /v1/keys/recover` with the same `PAYMENT-SIGNATURE` header, once, before the key's first use. Per-request x402 payments ($0.01 per search or profile) work the same way on `GET /v1/search` and `GET /v1/streamers/{id}`. `GET /v1/pricing` reports whether x402 is currently enabled and on which network.

## MCP server

- URL: `https://feelia.uk/mcp` (Streamable HTTP; protocol 2026-07-28 and legacy 2025-xx clients both work)
- Auth: the same `Authorization: Bearer <key>` header on the MCP connection; free tools work without it
- Tools: `feelia_about`, `feelia_search_streamers`, `feelia_get_streamer`, `feelia_get_contacts` (key), `feelia_list_brands`, `feelia_access_options`
- Protected tools without a key return a tool error that explains exactly how to get one — the model can act on it.

Claude Code:

```bash
claude mcp add --transport http feelia https://feelia.uk/mcp --header "Authorization: Bearer fk_live_…"
```

`.mcp.json` / Cursor / VS Code style config:

```json
{"mcpServers": {"feelia": {"type": "http", "url": "https://feelia.uk/mcp",
  "headers": {"Authorization": "Bearer fk_live_…"}}}}
```

claude.ai / Claude Desktop custom connector: add `https://feelia.uk/mcp` with **No sign-in**; organisations with request-header auth can add header `authorization` = `Bearer fk_live_…`. ChatGPT connectors cannot send API keys today, so ChatGPT gets the free tools only; OAuth sign-in is planned.

## Data notes

- `coverage_flag`: `gambling_confirmed` = classified as gambling inside a Kick gambling category; `category_mismatch` = covert: gambling content in a non-gambling category.
- `sponsor_status`: `active` = a sponsor brand seen in the last 7 days; `dormant` = 8–30 days ago; `free` = none in 30 days.
- `risk_score` 0–100: audience-quality risk from viewer-to-chat ratio, irregular viewer curves and related signals (higher = riskier).
- Classification comes from stream titles, categories and bios and from live thumbnails, judged by a System One model (TypeSafe Jev) with calibrated probabilities; uncertain cases are left unclassified rather than guessed.

Terms: `https://feelia.uk/terms`. Contact: `https://feelia.uk/contact`.