odds-api-io 1.3.1 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/README.md +325 -244
  2. package/dist/cjs/client.d.ts +278 -0
  3. package/dist/cjs/client.js +536 -292
  4. package/dist/cjs/client.js.map +1 -1
  5. package/dist/cjs/errors.d.ts +63 -0
  6. package/dist/cjs/errors.js +54 -36
  7. package/dist/cjs/errors.js.map +1 -1
  8. package/dist/cjs/helpers.d.ts +5 -0
  9. package/dist/cjs/helpers.js +13 -0
  10. package/dist/cjs/helpers.js.map +1 -0
  11. package/dist/cjs/index.d.ts +15 -0
  12. package/dist/cjs/index.js +15 -3
  13. package/dist/cjs/index.js.map +1 -1
  14. package/dist/cjs/package.json +1 -0
  15. package/dist/cjs/types.d.ts +770 -0
  16. package/dist/cjs/types.js +4 -1
  17. package/dist/cjs/types.js.map +1 -1
  18. package/dist/cjs/version.d.ts +1 -0
  19. package/dist/cjs/version.js +5 -0
  20. package/dist/cjs/version.js.map +1 -0
  21. package/dist/cjs/websocket.d.ts +210 -0
  22. package/dist/cjs/websocket.js +405 -0
  23. package/dist/cjs/websocket.js.map +1 -0
  24. package/dist/esm/client.d.ts +278 -0
  25. package/dist/esm/client.js +537 -293
  26. package/dist/esm/client.js.map +1 -1
  27. package/dist/esm/errors.d.ts +63 -0
  28. package/dist/esm/errors.js +49 -34
  29. package/dist/esm/errors.js.map +1 -1
  30. package/dist/esm/helpers.d.ts +5 -0
  31. package/dist/esm/helpers.js +9 -0
  32. package/dist/esm/helpers.js.map +1 -0
  33. package/dist/esm/index.d.ts +15 -0
  34. package/dist/esm/index.js +5 -2
  35. package/dist/esm/index.js.map +1 -1
  36. package/dist/esm/package.json +1 -0
  37. package/dist/esm/types.d.ts +770 -0
  38. package/dist/esm/types.js +4 -1
  39. package/dist/esm/types.js.map +1 -1
  40. package/dist/esm/version.d.ts +1 -0
  41. package/dist/esm/version.js +2 -0
  42. package/dist/esm/version.js.map +1 -0
  43. package/dist/esm/websocket.d.ts +210 -0
  44. package/dist/esm/websocket.js +367 -0
  45. package/dist/esm/websocket.js.map +1 -0
  46. package/dist/types/client.d.ts +155 -195
  47. package/dist/types/client.d.ts.map +1 -1
  48. package/dist/types/errors.d.ts +48 -24
  49. package/dist/types/errors.d.ts.map +1 -1
  50. package/dist/types/helpers.d.ts +6 -0
  51. package/dist/types/helpers.d.ts.map +1 -0
  52. package/dist/types/index.d.ts +8 -3
  53. package/dist/types/index.d.ts.map +1 -1
  54. package/dist/types/types.d.ts +659 -187
  55. package/dist/types/types.d.ts.map +1 -1
  56. package/dist/types/version.d.ts +2 -0
  57. package/dist/types/version.d.ts.map +1 -0
  58. package/dist/types/websocket.d.ts +211 -0
  59. package/dist/types/websocket.d.ts.map +1 -0
  60. package/package.json +46 -16
package/README.md CHANGED
@@ -7,291 +7,378 @@
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
8
8
  [![Node.js Version](https://img.shields.io/node/v/odds-api-io.svg)](https://nodejs.org)
9
9
 
10
- Official Node.js SDK for [**Odds-API.io**](https://odds-api.io) - Real-time sports betting odds from 450+ bookmakers.
10
+ Official Node.js and TypeScript SDK for the [**Odds-API.io**](https://odds-api.io) sports betting odds API: real-time and pre-match odds from 450+ bookmakers across 34 sports, over REST and WebSocket.
11
11
 
12
- Building with AI? See the [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding). Prefer Python? Check out the [Python SDK](https://github.com/odds-api-io/odds-api-python).
12
+ Building with AI? See the [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding). Prefer Python? Check out the [Python SDK](https://github.com/odds-api-io/odds-api-python). Prefer the terminal? Try the [CLI](https://github.com/odds-api-io/odds-api-cli).
13
13
 
14
- ## Features
14
+ ## Quickstart
15
15
 
16
- - 🏀 **34 Sports** - Basketball, football, tennis, and more
17
- - 📊 **Comprehensive Odds Data** - Real-time odds from 450+ bookmakers
18
- - 💰 **Arbitrage Detection** - Find risk-free betting opportunities
19
- - 📈 **Value Bets** - Identify positive expected value bets
20
- - 📉 **Dropping Odds** - Track sharp bookmaker line movements
21
- - 🔴 **Live Events** - Track in-play events and odds
22
- - 🔍 **Advanced Search** - Search events, participants, and leagues
23
- - ⚡ **TypeScript First** - Full type safety with TypeScript
24
- - 📦 **Dual Package** - Works with both ESM and CommonJS
25
- - 🛡️ **Error Handling** - Custom error classes for better debugging
26
-
27
- ## Installation
28
-
29
- ```bash
30
- npm install odds-api-io
31
- ```
16
+ 1. Install:
32
17
 
33
- ## Get Your API Key
18
+ ```bash
19
+ npm install odds-api-io
20
+ ```
34
21
 
35
- You need an API key from a paid plan. Visit [**odds-api.io/pricing**](https://odds-api.io/pricing) to get one.
22
+ 2. Set your API key ([get one here](https://odds-api.io/pricing?ref=npm)):
36
23
 
37
- ## Quick Start
24
+ ```bash
25
+ export ODDS_API_KEY="your-api-key"
26
+ ```
38
27
 
39
- ### TypeScript
28
+ 3. Make your first request:
40
29
 
41
- ```typescript
42
- import { OddsAPIClient } from 'odds-api-io';
30
+ ```typescript
31
+ import { OddsAPIClient } from 'odds-api-io';
43
32
 
44
- const client = new OddsAPIClient({
45
- apiKey: 'your-api-key-here'
46
- });
33
+ const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
47
34
 
48
- // Get all available sports
49
- const sports = await client.getSports();
50
- console.log(`Found ${sports.length} sports`);
35
+ const events = await client.getEvents({ sport: 'football', league: 'england-premier-league' });
36
+ const odds = await client.getEventOdds({ eventId: String(events[0].id), bookmakers: 'Bet365,Unibet' });
37
+ console.log(odds);
38
+ ```
51
39
 
52
- // Get upcoming NBA events
53
- const events = await client.getEvents({
54
- sport: 'basketball',
55
- league: 'usa-nba'
56
- });
40
+ ## Get an API key
57
41
 
58
- // Search for specific games
59
- const lakersGames = await client.searchEvents('Lakers');
42
+ The odds API needs a key from a paid plan. Pick a plan at [**odds-api.io/pricing**](https://odds-api.io/pricing?ref=npm). Rate limits, the number of bookmakers you can select and WebSocket access depend on the plan.
60
43
 
61
- // Get live events
62
- const liveEvents = await client.getLiveEvents('basketball');
63
- ```
44
+ ## Sports and bookmakers
64
45
 
65
- ### JavaScript (CommonJS)
46
+ | Sport | Example leagues |
47
+ |-------|-----------------|
48
+ | Football (soccer) | Premier League, La Liga, Champions League |
49
+ | Basketball | NBA, EuroLeague |
50
+ | American football | NFL, NCAAF |
51
+ | Baseball | MLB |
52
+ | Ice hockey | NHL |
53
+ | Tennis | ATP, WTA |
54
+ | Esports | CS2, League of Legends, Dota 2 |
55
+ | ...and 27 more | 34 sports in total |
66
56
 
67
- ```javascript
68
- const { OddsAPIClient } = require('odds-api-io');
57
+ Odds come from **450+ bookmakers**, including Bet365, DraftKings, FanDuel, Betfair, Unibet and SingBet. See the [full coverage list](https://odds-api.io/sportsbooks#coverage).
69
58
 
70
- const client = new OddsAPIClient({
71
- apiKey: 'your-api-key-here'
72
- });
59
+ ## Documentation
73
60
 
74
- async function getOdds() {
75
- const events = await client.getEvents({
76
- sport: 'basketball',
77
- league: 'usa-nba'
78
- });
79
-
80
- const odds = await client.getEventOdds({
81
- eventId: events[0].id,
82
- bookmakers: 'singbet,bet365'
83
- });
84
-
85
- console.log(odds);
86
- }
61
+ - [API documentation](https://docs.odds-api.io/)
62
+ - [API reference](https://docs.odds-api.io/api-reference)
63
+ - [AI and vibe coding guide](https://docs.odds-api.io/ai-vibe-coding)
87
64
 
88
- getOdds();
89
- ```
65
+ ## Features
90
66
 
91
- ### JavaScript (ESM)
67
+ - REST client for every public v3 endpoint: events, odds, odds summary, movements, value bets, arbitrage, dropping odds, historical odds and closing lines, settlement and grading, golf outrights, participants, bookmaker mappings
68
+ - `OddsWebSocket`: real-time odds, scores and status with reconnects that resume from the last `seq`
69
+ - Async iterators for paginated endpoints (`iterateEvents`, `iterateClosingLines`, `iterateMappings`, `iterateDroppingOdds`, `iterateHistoricalEvents`) and `pollUpdatedOdds` for the `/odds/updated` delta
70
+ - Types that match the responses, including the period score keys (`p1`..`pN`, `ft`, `ot`, `ap`)
71
+ - Error classes that keep the server's message, with `retryAfter` on rate limits and optional retries with backoff
72
+ - ESM and CommonJS, Node.js 18+
92
73
 
93
- ```javascript
74
+ ## Usage
75
+
76
+ ```typescript
94
77
  import { OddsAPIClient } from 'odds-api-io';
95
78
 
96
- const client = new OddsAPIClient({
97
- apiKey: 'your-api-key-here'
79
+ const client = new OddsAPIClient({ apiKey: process.env.ODDS_API_KEY! });
80
+
81
+ // Exact market names for a sport (no key needed)
82
+ const { markets } = await client.getMarkets('football');
83
+
84
+ // Upcoming and live Premier League matches
85
+ const events = await client.getEvents({
86
+ sport: 'football',
87
+ league: 'england-premier-league',
88
+ status: ['pending', 'live'],
89
+ });
90
+
91
+ // Odds for one match. Pass `markets` to keep responses small.
92
+ const odds = await client.getEventOdds({
93
+ eventId: events[0].id,
94
+ bookmakers: ['Bet365', 'SingBet'],
95
+ markets: ['ML', 'Spread', 'Totals'],
98
96
  });
97
+ for (const [bookmaker, bookMarkets] of Object.entries(odds.bookmakers)) {
98
+ const ml = bookMarkets.find((m) => m.name === 'ML');
99
+ console.log(bookmaker, ml?.odds[0]); // { home: '2.10', draw: '3.40', away: '3.20' }
100
+ }
99
101
 
100
- const sports = await client.getSports();
102
+ // Search, including in-play matches
103
+ const live = await client.searchEvents('Liverpool', { status: 'live' });
101
104
  ```
102
105
 
103
- ## Examples
106
+ CommonJS works the same way:
104
107
 
105
- ### Finding Arbitrage Opportunities
108
+ ```javascript
109
+ const { OddsAPIClient } = require('odds-api-io');
110
+ ```
106
111
 
107
- ```typescript
108
- import { OddsAPIClient } from 'odds-api-io';
112
+ Comma-separated parameters (`bookmakers`, `markets`, `eventIds`, `leagues`, `status`) accept either a string (`'Bet365,SingBet'`) or an array.
109
113
 
110
- const client = new OddsAPIClient({ apiKey: 'your-api-key' });
114
+ Market names must match in full: there is no `Match Winner` (use `ML`) and no bare `Over/Under`. Call `getMarkets(sport)` to see the names a sport serves.
111
115
 
112
- const arbs = await client.getArbitrageBets({
113
- bookmakers: 'singbet,bet365',
114
- limit: 10,
115
- includeEventDetails: true
116
- });
116
+ ## Odds comparison and summary
117
117
 
118
- arbs.forEach(arb => {
119
- console.log(`Profit: ${arb.profitPercentage}%`);
120
- console.log('Legs:', arb.legs);
121
- });
118
+ ```typescript
119
+ // Best, average, median, worst and fair price per line across bookmakers (Growth plans and above)
120
+ const summary = await client.getOddsSummary({ eventId: 123456, markets: ['ML', 'Totals'], includeExchanges: true });
121
+ const home = summary.markets[0].lines[0].outcomes.home;
122
+ console.log(home.best, home.bestBookmakers, home.fair);
123
+
124
+ // Price history for one market (prematch)
125
+ const history = await client.getOddsMovement({ eventId: 123456, bookmaker: 'Bet365', market: 'Totals', marketLine: 2.5 });
126
+ console.log(history.opening, history.latest);
122
127
  ```
123
128
 
124
- ### Tracking Odds Movements
129
+ ## Polling for changes
125
130
 
126
- ```typescript
127
- // Get odds for a specific event
128
- const odds = await client.getEventOdds({
129
- eventId: '62924717',
130
- bookmakers: 'singbet,bet365'
131
- });
131
+ `/odds/updated` returns only the market groups that changed. `pollUpdatedOdds` passes each `X-Next-Since` header back as the next `since`:
132
132
 
133
- // Track how odds change over time
134
- const movements = await client.getOddsMovement({
135
- eventId: '62924717',
136
- bookmaker: 'singbet',
137
- market: 'moneyline'
138
- });
133
+ ```typescript
134
+ const controller = new AbortController();
135
+ for await (const batch of client.pollUpdatedOdds({
136
+ bookmaker: 'Bet365',
137
+ sport: 'football',
138
+ markets: ['ML', 'Spread', 'Totals'], // required, max 40
139
+ intervalMs: 10_000,
140
+ signal: controller.signal,
141
+ })) {
142
+ for (const event of batch.data) {
143
+ // merge by event, bookmaker and market name; an absent market has not changed
144
+ }
145
+ }
139
146
  ```
140
147
 
141
- ### Getting Value Bets
148
+ For live odds the WebSocket is cheaper than any poll interval.
149
+
150
+ ## WebSocket
151
+
152
+ `OddsWebSocket` connects to `wss://api.odds-api.io/v3/ws`, tracks the highest `seq` and reconnects with `lastSeq`, so missed updates are replayed. In Node.js install the `ws` package (`npm install ws`); the server requires permessage-deflate compression, which `ws` and browsers negotiate by default. WebSocket access is a plan add-on.
142
153
 
143
154
  ```typescript
144
- // Find value betting opportunities
145
- const valueBets = await client.getValueBets({
146
- bookmaker: 'singbet',
147
- includeEventDetails: true
155
+ import { OddsAPIClient, OddsWebSocket } from 'odds-api-io';
156
+
157
+ const client = new OddsAPIClient({ apiKey });
158
+ const eventIds = [123456, 123457];
159
+ const store = new Map();
160
+
161
+ // 1. Snapshot with its sequence number
162
+ const { data, seq } = await client.getOddsSnapshot({ eventIds, bookmakers: ['Bet365'], markets: ['ML', 'Totals'] });
163
+ for (const event of data) for (const [book, markets] of Object.entries(event.bookmakers)) store.set(`${event.id}:${book}`, markets);
164
+
165
+ // 2. Stream from that point
166
+ const feed = new OddsWebSocket({
167
+ apiKey,
168
+ markets: ['ML', 'Totals'], // required for the odds channel, max 40
169
+ channels: ['odds', 'scores', 'status'], // optional, default odds only
170
+ eventIds, // or sport / leagues, status: 'live' | 'prematch'
171
+ lastSeq: seq ?? undefined,
148
172
  });
149
173
 
150
- valueBets.forEach(bet => {
151
- console.log(`Value: ${bet.valuePercentage}%`);
152
- console.log(`Odds: ${bet.odds} (Fair: ${bet.fairOdds})`);
174
+ feed.on('resync_required', async () => {
175
+ // replay could not be served: rebuild from REST, then continue
176
+ const snap = await client.getOddsSnapshot({ eventIds, bookmakers: ['Bet365'], markets: ['ML', 'Totals'] });
177
+ feed.lastSeq = snap.seq ?? undefined;
153
178
  });
179
+ feed.on('reconnecting', ({ attempt, delay, lastSeq }) => console.log(`reconnect #${attempt} in ${delay}ms from ${lastSeq}`));
180
+
181
+ for await (const msg of feed) {
182
+ if (msg.type === 'created' || msg.type === 'updated') store.set(`${msg.id}:${msg.bookie}`, msg.markets); // replace, do not merge
183
+ if (msg.type === 'deleted' || msg.type === 'no_markets') store.delete(`${msg.id}:${msg.bookie}`);
184
+ if (msg.type === 'score') console.log(msg.id, msg.scores, msg.clock);
185
+ }
154
186
  ```
155
187
 
156
- ### Tracking Dropping Odds
188
+ Events: `open`, `message`, one per message type (`welcome`, `created`, `updated`, `deleted`, `no_markets`, `score`, `status`, `resync_required`, `replay_complete`), `reconnecting`, `close` and `error`. `feed.close()` stops it; `feed.lastSeq` is the resume point to persist.
189
+
190
+ Close codes: 1012 (server restart) reconnects at once, 1013 (cooldown) waits at least 3 seconds, 1008 because a newer connection replaced this one stops instead of fighting it (two connections per key). A refused handshake (401, 403, 426) is not retried and rejects `connect()` / the iterator with `OddsWebSocketError`. Options: `reconnect` (default true), `maxReconnectAttempts`, `initialReconnectDelay`, `maxReconnectDelay`, `replayComplete` (default true) and `WebSocket` to pass your own implementation.
191
+
192
+ ## Historical odds and closing lines
157
193
 
158
194
  ```typescript
159
- // Find the biggest line movements from sharp bookmakers
160
- const drops = await client.getDroppingOdds({
195
+ // Finished events for one league (31 days per call)
196
+ const past = await client.getHistoricalEvents({
161
197
  sport: 'football',
162
- market: 'ML',
163
- minDrop: 10,
164
- sort: 'recent',
165
- includeEventDetails: true
198
+ league: 'england-premier-league',
199
+ from: '2026-09-01T00:00:00Z',
200
+ to: '2026-09-30T23:59:59Z',
166
201
  });
167
202
 
168
- drops.forEach(drop => {
169
- console.log(`${drop.event?.home} vs ${drop.event?.away}`);
170
- console.log(`${drop.market.name} ${drop.betSide}: ${drop.odds.opening} → ${drop.odds.current} (↓${drop.odds.drop.sinceOpening}%)`);
171
- });
172
- ```
203
+ // Any range: fetched in 31-day windows
204
+ for await (const event of client.iterateHistoricalEvents({ sport: 'football', league: 'england-premier-league', from: '2026-01-01T00:00:00Z', to: '2026-10-31T00:00:00Z' })) {
205
+ console.log(event.home, event.away, event.scores?.periods?.ft);
206
+ }
173
207
 
174
- ### Working with Participants
208
+ // Odds for one finished event
209
+ const closing = await client.getHistoricalOdds({ eventId: past[0].id, bookmakers: ['Bet365'], markets: ['ML'] });
175
210
 
176
- ```typescript
177
- // Search for teams/players
178
- const warriors = await client.getParticipants({
179
- sport: 'basketball',
180
- search: 'Warriors'
181
- });
211
+ // Closing lines for every settled event across up to 10 leagues (paid plans; 366 days per call, 100 per page)
212
+ for await (const event of client.iterateClosingLines({
213
+ sport: 'football',
214
+ leagues: ['england-premier-league', 'spain-laliga'],
215
+ from: '2026-08-01T00:00:00Z',
216
+ to: '2026-10-31T23:59:59Z',
217
+ markets: ['ML', 'Totals'],
218
+ bookmakers: ['Bet365', 'SingBet'],
219
+ })) {
220
+ console.log(event.id, event.bookmakers['Bet365']?.[0]?.odds[0]);
221
+ }
182
222
 
183
- // Get participant details by ID
184
- const participant = await client.getParticipantById(3428);
223
+ // Search finished events by team name
224
+ const arsenal = await client.searchHistoricalEvents({ query: 'Arsenal', sport: 'football' });
185
225
  ```
186
226
 
187
- ### Managing Bookmakers
188
-
189
- ```typescript
190
- // Get all available bookmakers
191
- const bookmakers = await client.getBookmakers();
192
-
193
- // Select specific bookmakers for your account
194
- await client.selectBookmakers('singbet,bet365');
227
+ ## Settlement and grading
195
228
 
196
- // Check which bookmakers you've selected
197
- const selected = await client.getSelectedBookmakers();
229
+ Paid plans. `getSettlements` returns status, a `final` flag and final scores; `gradeBets` grades selections against the result. Batches over 50 are split for you.
198
230
 
199
- // Clear selected bookmakers
200
- await client.clearSelectedBookmakers();
231
+ ```typescript
232
+ const { settlements, notFound } = await client.getSettlements([74919888, 73101436]);
233
+
234
+ const { grades } = await client.gradeBets([
235
+ { ref: 'bet-1', eventId: 74919888, market: 'ML', side: 'home' },
236
+ { ref: 'bet-2', eventId: 74919888, market: 'Spread', hdp: -0.75, side: 'home' },
237
+ { ref: 'bet-3', eventId: 74919888, market: 'Correct Score', label: '2-1' },
238
+ ]);
239
+ for (const g of grades) {
240
+ console.log(g.ref, g.result, g.reason, g.final); // 'won' | 'lost' | 'void' | 'half_won' | 'half_lost' | 'pending' | 'ungradeable'
241
+ }
201
242
  ```
202
243
 
203
- ## API Reference
244
+ Re-send selections that are not `final`, at most once a minute.
204
245
 
205
- ### Sports & Leagues
246
+ ## Outrights (golf)
206
247
 
207
- | Method | Description | Docs |
208
- |--------|-------------|------|
209
- | `getSports()` | Get all available sports | [Docs](https://docs.odds-api.io/api-reference/sports/get-sports) |
210
- | `getLeagues(sport)` | Get leagues for a sport | [Docs](https://docs.odds-api.io/api-reference/leagues/get-leagues) |
248
+ Outrights are a paid add-on: PGA Tour, DP World Tour, LIV Golf and the majors. A key without the add-on gets a `ForbiddenError` whose message links to the billing page.
211
249
 
212
- ### Events
250
+ ```typescript
251
+ import { ForbiddenError, isPriceRunner } from 'odds-api-io';
213
252
 
214
- | Method | Description | Docs |
215
- |--------|-------------|------|
216
- | `getEvents(params)` | Get events with filters | [Docs](https://docs.odds-api.io/api-reference/events/get-events) |
217
- | `getEventById(eventId)` | Get specific event details | [Docs](https://docs.odds-api.io/api-reference/events/get-event-by-id) |
218
- | `getLiveEvents(sport)` | Get currently live events | [Docs](https://docs.odds-api.io/api-reference/events/get-live-events) |
219
- | `searchEvents(query)` | Search for events by keyword | [Docs](https://docs.odds-api.io/api-reference/events/search-events) |
253
+ try {
254
+ const tournaments = await client.getOutrights({ sport: 'golf', league: 'pga-tour' });
255
+ const odds = await client.getOutrightOdds({ id: tournaments[0].id, bookmakers: ['DraftKings', 'Betfair Exchange'] });
256
+
257
+ for (const market of odds.bookmakers['Betfair Exchange'] ?? []) {
258
+ // Winner, Top 5, Top 5 (Incl. Ties), Top 10, Top 10 (Incl. Ties), Top 20, Top 20 (Incl. Ties), Make Cut
259
+ for (const runner of market.odds.slice(0, 3)) {
260
+ if (isPriceRunner(runner)) console.log(market.name, runner.label, runner.odds, runner.layOdds);
261
+ else console.log(market.name, runner.label, runner.yes, runner.no); // Make Cut
262
+ }
263
+ }
220
264
 
221
- ### Historical
265
+ const results = await client.getOutrightResults(tournaments[0].id);
266
+ console.log(results.winners['Top 10 (Incl. Ties)']);
267
+ } catch (err) {
268
+ if (err instanceof ForbiddenError && err.isAddOnRequired) console.log(err.message);
269
+ }
270
+ ```
222
271
 
223
- | Method | Description | Docs |
224
- |--------|-------------|------|
225
- | `getHistoricalEvents(params)` | Get finished historical events in a date range | [Docs](https://docs.odds-api.io/api-reference/historical/get-historical-events) |
226
- | `getHistoricalOdds(params)` | Get closing odds for a historical event | [Docs](https://docs.odds-api.io/api-reference/historical/get-historical-odds) |
272
+ "Top N" settles a boundary tie under the bookmaker's dead-heat rules; "Top N (Incl. Ties)" pays it in full. They are separate markets.
227
273
 
228
- ### Odds
274
+ ## Value bets, arbitrage and dropping odds
229
275
 
230
- | Method | Description | Docs |
231
- |--------|-------------|------|
232
- | `getEventOdds(params)` | Get odds for an event | [Docs](https://docs.odds-api.io/api-reference/odds/get-event-odds) |
233
- | `getOddsMovement(params)` | Track odds changes | [Docs](https://docs.odds-api.io/api-reference/odds/get-odds-movements) |
234
- | `getOddsForMultipleEvents(params)` | Get odds for multiple events | [Docs](https://docs.odds-api.io/api-reference/odds/get-odds-for-multiple-events) |
235
- | `getUpdatedOddsSince(params)` | Get odds updated since timestamp. `markets` is required by the API from 15 October 2026 | [Docs](https://docs.odds-api.io/api-reference/odds/get-updated-event-odds-since-a-given-timestamp) |
276
+ ```typescript
277
+ const valueBets = await client.getValueBets({ bookmaker: 'Bet365', sport: 'football', includeEventDetails: true });
278
+ valueBets.forEach((bet) => console.log(bet.market.name, bet.betSide, `${(bet.expectedValue * 100).toFixed(2)}% EV`));
236
279
 
237
- ### Participants
280
+ // Price gaps across your bookmakers. Prices move and bookmakers limit stakes, so check every leg before acting.
281
+ const arbs = await client.getArbitrageBets({ bookmakers: ['Bet365', 'SingBet'], sport: 'football', markets: ['Totals'], minProfit: 1 });
282
+ arbs.forEach((arb) => console.log(arb.profitMargin, arb.legs.map((l) => `${l.bookmaker} ${l.side} @ ${l.odds}`)));
238
283
 
239
- | Method | Description | Docs |
240
- |--------|-------------|------|
241
- | `getParticipants(params)` | Get participants/teams | [Docs](https://docs.odds-api.io/api-reference/participants/get-participants) |
242
- | `getParticipantById(id)` | Get participant by ID | [Docs](https://docs.odds-api.io/api-reference/participants/get-participant-by-id) |
284
+ // Dropping odds from sharp bookmakers (paid plans)
285
+ const drops = await client.getDroppingOdds({ sport: 'football', markets: ['ML'], minDrop: 10, sort: 'recent', includeEventDetails: true });
286
+ drops.forEach((d) => console.log(`${d.market.name} ${d.betSide}: ${d.odds.opening} -> ${d.odds.current} (-${d.odds.drop.sinceOpening}%)`));
287
+ ```
243
288
 
244
- ### Bookmakers
289
+ ## Participants, logos and mappings
245
290
 
246
- | Method | Description | Docs |
247
- |--------|-------------|------|
248
- | `getBookmakers()` | Get all available bookmakers | [Docs](https://docs.odds-api.io/api-reference/bookmakers/get-bookmakers) |
249
- | `getSelectedBookmakers()` | Get your selected bookmakers | [Docs](https://docs.odds-api.io/api-reference/bookmakers/get-selected-bookmakers) |
250
- | `selectBookmakers(bookmakers)` | Select bookmakers for your account | [Docs](https://docs.odds-api.io/api-reference/bookmakers/select-bookmakers) |
251
- | `clearSelectedBookmakers()` | Clear bookmaker selection | [Docs](https://docs.odds-api.io/api-reference/bookmakers/clear-selected-bookmakers) |
291
+ ```typescript
292
+ const teams = await client.getParticipants({ sport: 'football', search: 'Chelsea' });
252
293
 
253
- ### Betting Analysis
294
+ // PNG crest; the URL carries your key, so proxy it with getParticipantLogo() for public pages
295
+ const url = client.getParticipantLogoUrl(events[0].homeId!);
296
+ const png = await client.getParticipantLogo(events[0].homeId!); // ArrayBuffer
254
297
 
255
- | Method | Description | Docs |
256
- |--------|-------------|------|
257
- | `getArbitrageBets(params)` | Find arbitrage opportunities | [Docs](https://docs.odds-api.io/api-reference/arbitrage-bets/get-arbitrage-betting-opportunities) |
258
- | `getValueBets(params)` | Find value bets | [Docs](https://docs.odds-api.io/api-reference/value-bets/get-value-bets) |
259
- | `getDroppingOdds(params)` | Track sharp bookmaker line movements | [Docs](https://docs.odds-api.io/api-reference/dropping-odds/get-dropping-odds) |
298
+ // A bookmaker's own market and outcome ids for our events (paid plans)
299
+ const { data } = await client.getMappings({ bookmaker: 'Polymarket', eventId: 71515842 });
300
+ for await (const row of client.iterateMappings({ bookmaker: 'Kalshi', sport: 'american-football' })) {
301
+ console.log(row.eventId, row.market, row.side, row.marketId, row.outcomeId);
302
+ }
303
+ ```
260
304
 
261
- ## Error Handling
305
+ ## Bookmakers
262
306
 
263
- The SDK includes custom error classes for better error handling:
307
+ ```typescript
308
+ const bookmakers = await client.getBookmakers(); // name, active, createdAt, status ('ok' | 'degraded' | 'down'), reason
309
+ await client.selectBookmakers(['Bet365', 'SingBet']);
310
+ const { bookmakers: selected } = await client.getSelectedBookmakers();
311
+ await client.clearSelectedBookmakers(); // once every 12 hours
312
+ ```
313
+
314
+ ## Methods
315
+
316
+ | Area | Method | Endpoint |
317
+ |------|--------|----------|
318
+ | Catalogue | `getSports()` | `GET /sports` |
319
+ | | `getMarkets(sport?)` | `GET /markets` |
320
+ | | `getLeagues(sport, { all? })` | `GET /leagues` |
321
+ | | `getBookmakers()` | `GET /bookmakers` |
322
+ | | `getSelectedBookmakers()` | `GET /bookmakers/selected` |
323
+ | | `selectBookmakers(bookmakers)` | `PUT /bookmakers/selected/select` |
324
+ | | `clearSelectedBookmakers()` | `PUT /bookmakers/selected/clear` |
325
+ | Events | `getEvents(params)`, `iterateEvents(params, { pageSize?, maxPages? })` | `GET /events` |
326
+ | | `getEventById(id)` | `GET /events/{id}` |
327
+ | | `getLiveEvents(sport?)` | `GET /events/live` |
328
+ | | `searchEvents(query, { status? })` | `GET /events/search` |
329
+ | Odds | `getEventOdds(params)` | `GET /odds` |
330
+ | | `getOddsForMultipleEvents(params)`, `getOddsSnapshot(params)` | `GET /odds/multi` |
331
+ | | `getUpdatedOddsSince(params)`, `getUpdatedOddsSinceWithMeta(params)`, `pollUpdatedOdds(params)` | `GET /odds/updated` |
332
+ | | `getOddsMovement(params)` | `GET /odds/movements` |
333
+ | | `getOddsSummary(params)` | `GET /odds/summary` |
334
+ | | `getOddsSummaryMulti(params)` | `GET /odds/summary/multi` |
335
+ | Analysis | `getValueBets(params)` | `GET /value-bets` |
336
+ | | `getArbitrageBets(params)` | `GET /arbitrage-bets` |
337
+ | | `getDroppingOdds(params)`, `getDroppingOddsPage(params)`, `iterateDroppingOdds(params)` | `GET /dropping-odds` |
338
+ | Historical | `getHistoricalEvents(params)`, `iterateHistoricalEvents(params)` | `GET /historical/events` |
339
+ | | `searchHistoricalEvents(params)` | `GET /historical/events/search` |
340
+ | | `getHistoricalOdds(params)` | `GET /historical/odds` |
341
+ | | `getClosingLines(params)`, `iterateClosingLines(params)` | `GET /historical/closing-lines` |
342
+ | Settlement | `getSettlements(eventIds)` | `GET /settlements` |
343
+ | | `gradeBets(selections)` (alias `gradeSelections`) | `POST /settlements/grade` |
344
+ | Outrights | `getOutrights(params)` | `GET /outrights` |
345
+ | | `getOutrightOdds(params)` | `GET /outrights/odds` |
346
+ | | `getOutrightResults(id)` | `GET /outrights/results` |
347
+ | Participants | `getParticipants(params)` | `GET /participants` |
348
+ | | `getParticipantById(id)` | `GET /participants/{id}` |
349
+ | | `getParticipantLogo(id)`, `getParticipantLogoUrl(id)` | `GET /participants/{id}/logo` |
350
+ | Mappings | `getMappings(params)`, `iterateMappings(params)` | `GET /mappings` |
351
+ | WebSocket | `new OddsWebSocket(options)` | `wss://api.odds-api.io/v3/ws` |
352
+
353
+ Full parameter and response reference: [docs.odds-api.io/api-reference](https://docs.odds-api.io/api-reference).
354
+
355
+ ## Errors
356
+
357
+ Every error extends `OddsAPIError` and carries the server's own message, plus `status`, `body` and `rateLimit` when there was a response.
358
+
359
+ | Class | When |
360
+ |-------|------|
361
+ | `BadRequestError` | 400: a parameter is missing or invalid (the message says which) |
362
+ | `InvalidAPIKeyError` | 401 |
363
+ | `ForbiddenError` | 403: the plan does not include the endpoint or bookmaker, or an add-on is missing (`isAddOnRequired`) |
364
+ | `NotFoundError` | 404: the message often lists what does exist |
365
+ | `RateLimitError` | 429, with `retryAfter` in seconds (`RateLimitExceededError` is the same class) |
366
+ | `ServerError` | 5xx |
367
+ | `TimeoutError`, `NetworkError` | no response |
368
+ | `OddsWebSocketError` | WebSocket handshake refused or the helper gave up (`code` = HTTP status or close code) |
264
369
 
265
370
  ```typescript
266
- import {
267
- OddsAPIClient,
268
- OddsAPIError,
269
- InvalidAPIKeyError,
270
- RateLimitExceededError,
271
- NotFoundError,
272
- TimeoutError,
273
- NetworkError
274
- } from 'odds-api-io';
275
-
276
- const client = new OddsAPIClient({ apiKey: 'your-api-key' });
371
+ import { OddsAPIError, RateLimitError, ForbiddenError } from 'odds-api-io';
277
372
 
278
373
  try {
279
- const events = await client.getEvents({ sport: 'basketball' });
280
- } catch (error) {
281
- if (error instanceof InvalidAPIKeyError) {
282
- console.error('Your API key is invalid');
283
- } else if (error instanceof RateLimitExceededError) {
284
- console.error('Rate limit exceeded - wait before retrying');
285
- } else if (error instanceof NotFoundError) {
286
- console.error('Resource not found');
287
- } else if (error instanceof TimeoutError) {
288
- console.error('Request timeout');
289
- } else if (error instanceof NetworkError) {
290
- console.error('Network error');
291
- } else if (error instanceof OddsAPIError) {
292
- console.error('API error:', error.message);
293
- }
374
+ await client.getClosingLines({ /* ... */ });
375
+ } catch (err) {
376
+ if (err instanceof RateLimitError) console.log(`retry in ${err.retryAfter}s`);
377
+ else if (err instanceof ForbiddenError) console.log(err.message);
378
+ else if (err instanceof OddsAPIError) console.log(err.status, err.message);
294
379
  }
380
+
381
+ console.log(client.lastRateLimit); // { limit, remaining, reset } from the last response
295
382
  ```
296
383
 
297
384
  ## Configuration
@@ -299,52 +386,49 @@ try {
299
386
  ```typescript
300
387
  const client = new OddsAPIClient({
301
388
  apiKey: 'your-api-key',
302
- baseUrl: 'https://api2.odds-api.io/v3', // Optional, default shown
303
- timeout: 10000 // Optional, default 10 seconds
389
+ baseUrl: 'https://api.odds-api.io/v3', // default
390
+ timeout: 10000, // ms per attempt
391
+ maxRetries: 2, // retries on 5xx, network errors and short 429 waits; 0 turns them off
392
+ maxRetryDelay: 10000, // a 429 asking for a longer wait is thrown, not waited out
304
393
  });
305
394
  ```
306
395
 
307
- ## TypeScript Support
396
+ Bookmaker selection changes (PUT) are never retried.
308
397
 
309
- This SDK is written in TypeScript and includes complete type definitions:
398
+ ## Migrating from 1.3
310
399
 
311
- ```typescript
312
- import type {
313
- Sport,
314
- League,
315
- Event,
316
- HistoricalEvent,
317
- Participant,
318
- Bookmaker,
319
- EventOdds,
320
- HistoricalEventOdds,
321
- ArbitrageBet,
322
- ValueBet,
323
- DroppingOddsEntry,
324
- GetEventsParams,
325
- GetHistoricalEventsParams,
326
- GetHistoricalOddsParams
327
- } from 'odds-api-io';
328
- ```
400
+ 1.5.0 aligns the types with what the API returns. Code that used the old, inaccurate field names needs updating:
329
401
 
330
- ## Plans and Limits
402
+ - `Event`: `date`, `home`, `away`, `homeId`, `awayId`, `status` (`pending | live | settled | cancelled`), `sport`/`league` as `{ name, slug }`, `scores.periods`.
403
+ - Period keys are `p1`..`pN`, `ft`, `ot`, `ap`. The old `period1`, `overtime`, `penalties` and `fulltime` keys stop being served on 12 November 2026.
404
+ - `EventOdds.bookmakers` is a map of bookmaker name to markets; `OddsMovement` has `opening`, `latest` and `movements`.
405
+ - `ArbitrageBet` uses `profitMargin` and `legs[].side`; `ValueBet` uses `expectedValue` and `betSide`.
406
+ - `Bookmaker` is `{ name, active, createdAt, status, reason }`; `getSelectedBookmakers()` returns `{ bookmakers, count }`.
407
+ - `getDroppingOdds` now sends `markets` (the old `market` option was ignored by the API; it is still accepted and sent as `markets`).
408
+ - Errors keep the server message instead of a fixed text.
409
+ - The default base URL is `https://api.odds-api.io/v3`.
410
+
411
+ ## Examples
331
412
 
332
- An API key from a paid plan is required. Rate limits, bookmaker selection and WebSocket access depend on your plan; see [**odds-api.io/pricing**](https://odds-api.io/pricing) for details.
413
+ See [`examples/`](./examples):
333
414
 
334
- ## Resources
415
+ - `basic-usage.ts` / `basic-usage.js`: getting started
416
+ - `premier-league-odds.ts`: odds for a league
417
+ - `odds-tracking.ts`: price history and the updated-odds delta
418
+ - `arbitrage-betting.ts`: price gaps across bookmakers
419
+ - `websocket-feed.ts`: REST snapshot plus `OddsWebSocket`
420
+ - `golf-outrights-and-settlement.ts`: outrights and bet grading
335
421
 
336
- - 📘 [**API Documentation**](https://docs.odds-api.io/)
337
- - 🌐 [**Odds-API.io Website**](https://odds-api.io)
338
- - 💳 [**Get Your API Key**](https://odds-api.io/pricing)
339
- - 🐛 [**Report Issues**](https://github.com/odds-api-io/odds-api-node/issues)
422
+ ## Plans and Limits
340
423
 
341
- ## Examples Directory
424
+ An API key from a paid plan is required. Rate limits, bookmaker selection and WebSocket access depend on your plan; see [**odds-api.io/pricing**](https://odds-api.io/pricing?ref=npm).
342
425
 
343
- Check the [`examples/`](./examples) directory for more comprehensive examples:
426
+ ## Resources
344
427
 
345
- - `basic-usage.ts` / `basic-usage.js` - Getting started
346
- - `arbitrage-betting.ts` - Finding arbitrage opportunities
347
- - `odds-tracking.ts` - Monitoring odds movements
428
+ - [API documentation](https://docs.odds-api.io/)
429
+ - [Odds-API.io website](https://odds-api.io)
430
+ - [Get your API key](https://odds-api.io/pricing?ref=npm)
431
+ - [Report issues](https://github.com/odds-api-io/odds-api-node/issues)
348
432
 
349
433
  ## License
350
434
 
@@ -354,14 +438,11 @@ Check the [`examples/`](./examples) directory for more comprehensive examples:
354
438
 
355
439
  This is the official SDK for Odds-API.io. This tool is for informational purposes only and should not be used as the sole basis for betting decisions.
356
440
 
357
- ---
358
-
359
- Built with ❤️ for the sports betting and analytics community
360
441
 
361
442
  ## Citation
362
443
 
363
444
  If you use this package in research or a publication, please cite it. Citation metadata is in [CITATION.cff](CITATION.cff) (GitHub renders a "Cite this repository" button from it) and Zenodo metadata is in `.zenodo.json`.
364
445
 
365
446
  ```
366
- Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.2.2). https://github.com/odds-api-io/odds-api-node
447
+ Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.5.1). https://github.com/odds-api-io/odds-api-node
367
448
  ```