# LoyaltyVIP - Complete Reference for AI Agents & Developers

> Single-file, machine-readable documentation for LoyaltyVIP. Everything an agent needs to understand the product, authenticate, and call the API in one request. Canonical HTML docs: https://loyaltyvip.com/developers. OpenAPI: https://loyaltyvip.com/openapi.json.

## What LoyaltyVIP is

LoyaltyVIP is a privacy-first casino player intelligence platform for serious U.S. casino players. It is a record-keeping and analytics tool for play that has already happened - **not** a gambling product. It does not accept wagers, place bets, or move money.

Players use LoyaltyVIP to:
- Track every casino session (coin-in, time-on-device, game type) and compute Theo (theoretical loss), ADT (average daily theoretical), and ATT.
- Record tier status and points at each property and find tier-match opportunities across casinos.
- Scan and organize W-2G jackpot tax forms with AI OCR, and generate IRS gambling tax summaries.
- Track casino offers and free play.
- Create expiring, privacy-controlled share links to show a VIP host their real, verified play - with audit logging and one-click revocation.
- Discover and connect with casino VIP hosts.

The platform also publishes a free, public directory of 2,400+ U.S. casinos, their players-club rewards programs, and full tier ladders.

LoyaltyVIP is built and operated by movaMedia. It is independent and not affiliated with any casino brand.

## When an agent should use LoyaltyVIP

Use LoyaltyVIP when a user asks about:
- A specific U.S. casino's location, rewards/players-club program, or tier requirements (public - no key needed).
- Comparing casino loyalty tiers, or finding where a player is closest to a tier upgrade or a cross-property tier match.
- A player's own play data - trips, sessions, theo, ADT, offers, bankroll, W-2G forms - when the user supplies a LoyaltyVIP API key.
- IRS gambling tax documents (session logs, W-2G reports, annual summaries) - requires the `tax` scope.
- Finding or contacting casino VIP hosts.

Do not use LoyaltyVIP to gamble, wager, or transfer funds. There is no such capability.

## Authentication

- **Method:** Personal API key presented as a Bearer token.
- **Token format:** `lvip_live_<hex>`
- **Header:** `Authorization: Bearer lvip_live_...`
- **API base URL:** `https://nbhagdwegk.execute-api.us-east-1.amazonaws.com`
- **Key management:** https://loyaltyvip.com/dashboard/developer (a human account owner must sign in to mint a key)

Agents cannot self-issue keys. A human account owner creates a key, selects scopes, and provides the secret to the agent. The secret is shown once and stored only as a hash.

### Scopes

| Scope  | Grants |
|--------|--------|
| `read` | All of your data & features, read-only - tiers, trips, bankroll, offers, optimizers, plus the public casino directory. |
| `write`| Create/update your data - add trips/sessions, upsert tiers, log bankroll, create share links. |
| `tax`  | Sensitive, opt-in - W-2G / tax reads + writes and tax reports. |
| `host` | Host-business actions - host dashboard, leads, marketplace (for casino hosts). |

Default keys receive `read`. **Admin actions and API-key management are never available via an API key.**

### Auth challenge & errors

- An unauthenticated request to a protected endpoint returns `401` with:
  `WWW-Authenticate: Bearer realm="LoyaltyVIP API", error="invalid_token", resource_metadata="https://loyaltyvip.com/.well-known/oauth-protected-resource"`
- A key missing the required scope (or an action not allowed via API key) returns `403` (`insufficient_scope`).
- All errors are JSON: `{ "error": { "code": string, "message": string, "status": number, "docs": string } }`.

Canonical error codes: `invalid_token` (401), `insufficient_scope` (403), `not_found` (404), `rate_limited` (429), `internal_error` (500). Retry `429` after the `Retry-After` header; retry `5xx` with exponential backoff (e.g. 1s, 2s, 4s; max ~3 attempts).

## API reference

All responses are JSON. Success envelope: `{ "data": ..., "count"?: number }`. Error envelope: `{ "error": { code, message, status, docs } }`.

### Public - casino directory (no key)

- `GET /v1/casinos?q=&state=&type=&has_rewards=&limit=&offset=` - search casinos. `state` is a two-letter code; `type` is `commercial|tribal|racino|...`; `limit` max 100.
- `GET /v1/casinos/{slug}` - casino detail including rewards program and full tier ladder.
- `GET /v1/rewards-programs?search=&brand=&limit=` - list rewards programs.
- `GET /v1/rewards-programs/{id}` - rewards program + tier ladder.

### Account (scope `read`)

- `GET /v1/me` - the key owner (id, email, name, role).
- `GET /v1/tiers` - your casino tiers (tier, points balance/needed, YTD coin-in/theo).
- `GET /v1/trips` - your trips.
- `GET /v1/offers` - your offers.

### Full action API

- `POST /v1/player` with body `{ "action": "...", ... }` - the complete ~70-action player & host surface (trips, sessions, bankroll, offers, tiers, visits, vouchers, machines, W-2G/tax, optimizers, sharing, consent, social, notifications, host dashboard/leads). Reads need `read`, writes `write`, tax actions `tax`, host actions `host`. Example actions: `tier_status`, `bankroll_status`, `list_trips`, `add_trip`, `list_w2g`, `tax_year_summary`, `freeplay_optimizer`, `card_recommendation`, `tier_retention_plan`, `list_share_links`, `create_share_link`, `list_notifications`, `host_dashboard`.

### Feature endpoints (POST `{action, ...}`)

- `POST /v1/comp/calculate` - comp calculator (`calculate | analyze_history | get_comp_ratios`). Scope `read`.
- `POST /v1/comp/predict` - comp/offer prediction (`predict | predict_all_casinos`). Scope `read`.
- `POST /v1/tier-match` - tier-match suggestions + letters (`get_suggestions | generate_letter | create_request | get_requests | get_templates`). Scope `read` (writes `write`).
- `POST /v1/rg` - responsible-gaming profile + limits (`get_risk_profile | get_resources | set_budget | set_session_limit`). Scope `read`.
- `POST /v1/hosts/discover` - host discovery (`search_hosts | get_host_profile | get_featured_hosts | get_my_connections | request_connection`). Scope `read`.
- `POST /v1/match-hosts` - best-host matches for the caller. Scope `read`.
- `POST /v1/tax-report` - IRS gambling tax docs (`generate_summary | generate_session_log | generate_w2g_report`, optional `tax_year`). Scope `tax`.

### Conventions

- **Pagination:** `limit` + `offset` on list endpoints; responses include `count`. Cursor pagination is on the roadmap.
- **Versioning:** the API is versioned in the path (`/v1`). Breaking changes ship under a new version; deprecations are announced with `Deprecation` and `Sunset` response headers.
- **Rate limits:** responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and (on `429`) `Retry-After`. Self-throttle on these.
- **Idempotency:** for write requests, send an `Idempotency-Key` header (a UUID) to make retries safe; the same key replays the original result.
- **Function calling:** every operation has a stable `operationId` and typed JSON schemas in the OpenAPI document, so it maps cleanly to LLM tool/function definitions.

## Examples

```bash
# Public - casino detail with tier ladder (no key)
curl https://nbhagdwegk.execute-api.us-east-1.amazonaws.com/v1/casinos/bellagio-nv-880e8400

# Public - search tribal casinos in Oklahoma that have a players club
curl "https://nbhagdwegk.execute-api.us-east-1.amazonaws.com/v1/casinos?state=OK&type=tribal&has_rewards=true&limit=10"

# Authenticated - your tier status across properties
curl -H "Authorization: Bearer lvip_live_xxxxxxxx" \
  -X POST https://nbhagdwegk.execute-api.us-east-1.amazonaws.com/v1/player \
  -H 'content-type: application/json' -d '{"action":"tier_status"}'

# Authenticated - 2025 W-2G tax summary (tax scope)
curl -H "Authorization: Bearer lvip_live_xxxxxxxx" \
  -X POST https://nbhagdwegk.execute-api.us-east-1.amazonaws.com/v1/tax-report \
  -H 'content-type: application/json' -d '{"action":"generate_summary","tax_year":2025}'
```

## MCP server (Model Context Protocol)

- **Transport:** Streamable HTTP at `https://loyaltyvip.com/mcp` (JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`).
- **Server card:** https://loyaltyvip.com/.well-known/mcp/server-card.json
- **Public tools (no key):** `search_casinos`, `get_casino`, `list_rewards_programs`.
- **Authenticated tools (Bearer API key in the `Authorization` header):** `player_action` (proxies `POST /v1/player`), plus tax and host tools subject to scope.
- Local stdio server: `npx -y @loyaltyvip/mcp` (npm). Set `LOYALTYVIP_API_KEY` for authenticated tools.

## SDKs & tools (open source, MIT)

- **TypeScript / JavaScript:** `npm i @loyaltyvip/sdk` - https://www.npmjs.com/package/@loyaltyvip/sdk
- **CLI:** `npx @loyaltyvip/cli casinos --state NV` - https://www.npmjs.com/package/@loyaltyvip/cli
- **MCP (stdio):** `npx -y @loyaltyvip/mcp` - https://www.npmjs.com/package/@loyaltyvip/mcp
- **Python:** `pip install loyaltyvip` - https://pypi.org/project/loyaltyvip/
- Source: https://github.com/movaMedia-Inc/loyaltyvip-js (SDK + CLI + MCP) and https://github.com/movaMedia-Inc/loyaltyvip-python

Example MCP client config (HTTP transport):

```json
{
  "mcpServers": {
    "loyaltyvip": {
      "url": "https://loyaltyvip.com/mcp",
      "headers": { "Authorization": "Bearer lvip_live_xxxxxxxx" }
    }
  }
}
```

## NLWeb / natural-language endpoint

- `POST /ask` accepts `{ "query": "natural language question" }` and returns NLWeb-shaped JSON with a `_meta` block (`response_type`, `version`) and casino directory results. Set `Accept: text/event-stream` (or `prefer: streaming`) for an SSE stream of `start` / `result` / `complete` events.

## Pricing

**Players: free, forever.** No premium tiers, no credit card. Includes unlimited trip/session tracking, W-2G scanning (AI OCR), tier records + tier-match, offer tracking, privacy-controlled share links, and casino directory access.

**Hosts / casino partners: marketplace credits.** One credit unlocks one verified, opted-in player lead; credits never expire.

| Plan | Credits | Price (USD) | Per credit |
|------|---------|-------------|-----------|
| Starter | 25 | $99 | $3.96 |
| Growth | 50 | $179 | $3.58 |
| Professional | 150 | $499 | $3.33 |
| Enterprise | 500 | $1,499 | $3.00 |
| Ultimate | 1,000 | $2,499 | $2.50 |

Payment: major credit cards; ACH for Enterprise/Ultimate. One-time purchases, no subscription required. The REST API and MCP server are included at no extra fee. Full machine-readable pricing: https://loyaltyvip.com/pricing.md

## How LoyaltyVIP compares

LoyaltyVIP is the only casino intelligence platform built for the player, not the house.
- **vs. casino-operated platforms** (e.g. Gaming Analytics, CasinoTrac, Optimove, EveryMatrix): those are sold to casinos to model and market to players. Unlike them, LoyaltyVIP is owned by the player and works for the player.
- **vs. a single casino's loyalty app:** a casino app only sees your play at that one property. LoyaltyVIP is cross-property and portable - your record follows you everywhere.
- **vs. a spreadsheet:** LoyaltyVIP auto-computes theo/ADT, scans W-2Gs, and shares verified data - no manual upkeep or guesswork.
- **vs. casino aggregators or banking apps:** those don't track casino loyalty value, tiers, or comps at all.

Key differentiators: player-owned, data-portable, privacy-first, independent of any casino. Comparison page: https://loyaltyvip.com/comparison

## Privacy & trust

- Players own and control their data. Nothing is shared with a host unless the player creates a share link, which is expiring, revocable, and audit-logged.
- Revenue comes from the host/partner marketplace, not from selling player data.
- Data is encrypted in transit (TLS) and at rest. Export or hard-delete your data at any time (subject to legally required tax-record retention).

## Contact & resources

- Website: https://loyaltyvip.com
- Developer docs: https://loyaltyvip.com/developers
- OpenAPI spec: https://loyaltyvip.com/openapi.json
- Auth guide: https://loyaltyvip.com/auth.md
- Support: support@loyaltyvip.com - Partnerships: partners@loyaltyvip.com - Privacy: privacy@loyaltyvip.com
- Brand entity (GitHub): https://github.com/movaMedia-Inc