BookSync developer reference
One-page complete reference for integrating with or contributing to the BookSync extension. If you only want to install it, the install guide is shorter. If you want the threat model, security is the page.
Architecture in 30 seconds
- User mints a personal token at
/account/booksync. Plaintext shown once; SHA-256 stored on the server. - User installs the Chrome extension (developer mode today, Web Store soon).
- User logs into a sportsbook in the same Chrome profile. No credentials ever touch the extension.
- User opens the book's bet-history page and clicks Sync.
- The per-book content script reads visible HTML, normalizes each row to the canonical schema, and POSTs to
/api/account/booksync/importwith the token in the Authorization header. - Server upserts on
(user_id, book, external_id). Re-running sync is idempotent.
Authentication
Bearer token in the Authorization header. Format:
Authorization: Bearer np_bs_<32 hex>Tokens are per-device. Lose a laptop, revoke that token at /account/booksync. Other devices keep working.
Canonical bet payload
Every per-book scraper normalizes to this shape before POSTing. Schema lives in 0038-booksync-keys-and-attribution.sql.
| Field | Type | Req | Notes |
|---|---|---|---|
| external_id | string | yes | Book's own bet/entry/ticket id. Server-side dedup key. Re-running sync is safe. |
| book | string | yes | One of: draftkings, fanduel, betmgm, caesars, espn-bet, betrivers, fanatics, hardrock, prizepicks, underdog. |
| placed_at | iso8601 | yes | When the bet was placed. Book-provided when available, otherwise scrape ts. |
| sport | string | no | Lowercase token: nfl, nba, mlb, nhl, ncaaf, ncaab, mma, soccer, tennis, golf. |
| game | string | no | Free-form. "DAL @ NYG" / "Chiefs vs Eagles". For DFS lineups, the slate name. |
| market | string | no | Free-form. "spread", "moneyline", "player_points_o22.5". DFS uses the prop type. |
| pick_text | string | no | Human-readable. "Eagles -3.5", "Mahomes Over 285.5 yds". |
| odds_american | int | no | Signed. -110, +145. Omit for DFS entries that price by payout multiplier. |
| stake_cents | int | yes | Stake in cents. $10 = 1000. |
| potential_win_cents | int | no | Net potential profit in cents. Omit if unknown; server can compute from odds + stake. |
| result | enum | yes | pending | win | loss | push | void. |
| settled_at | iso8601 | no | When the bet settled. Required if result is not pending. |
Public endpoint catalog
Six endpoints, no auth, CORS-open. Drop-in for dashboards, uptime monitors, and partner integrations. OpenAPI 3.1 fragment at /api/booksync/openapi.json.
| Path | Cache | Description |
|---|---|---|
| /api/booksync/stats | 60 s | Adoption metrics. Total + active keys, distinct users, total bets imported, books live, 7d/30d windows, per-book breakdown. |
| /api/booksync/books | 5 min | Per-book scraper inventory. version, ring origin, host permissions, GitHub source URL, rot risk, last-verified-against-live-DOM ts. |
| /api/booksync/health | 30 s | System health probe. DB reachability, key/bets table presence, latency, endpoint inventory. Used by uptime monitors. |
| /api/booksync/version | 60 s | Latest extension version + upgrade hint. Polled by the popup at startup. |
| /api/booksync/recent | 5 min | Anonymized 30d feed of imports. PII-stripped: book + sport + market + stake bucket + result + days ago. ?limit=50 (max 200). |
| /api/booksync/openapi.json | 30 min | OpenAPI 3.1 fragment for the 5 public endpoints. Lets Postman / Insomnia / openapi codegen introspect without scraping the dev hub. |
Error codes
What the auth-gated import endpoint returns and what to do about it.
| Status | Meaning |
|---|---|
| 200 | Import accepted. Body contains imported / deduped / skipped counts. |
| 400 | Payload validation failed. Body lists which row was malformed. |
| 401 | Token missing or wrong format. |
| 403 | Token revoked or never minted on this account. |
| 404 | Resource not found (only on GET endpoints with path params). |
| 413 | Payload too large. Cap is 5000 rows per import call. |
| 429 | Rate limited. 30 imports per token per hour. |
| 5xx | Server-side. Retry with exponential backoff. /api/booksync/health will tell you if DB is down. |
Contributing
Per-book scraper PR guide lives at CONTRIBUTING.md. Selector strategy + rot-risk ranking at SCRAPER-AUDIT.md. Submission package for the Chrome Web Store at CHROME-WEB-STORE-SUBMISSION.md.
Surface map
- /booksync landing
- /booksync/install install guide
- /booksync/preview sample dashboard
- /booksync/books per-book table
- /booksync/status live system status
- /booksync/security threat model
- /booksync/faq 12 Qs
- /booksync/changelog versions
- /account/booksync mint a token
- /developers full API hub
Vault Ring 525. 21+ only. Not financial advice. 1-800-GAMBLER.