odds-api-io 1.3.1 → 1.5.2

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 +330 -245
  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,382 @@
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
204
-
205
- ### Sports & Leagues
244
+ Re-send selections that are not `final`, at most once a minute.
206
245
 
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) |
246
+ ## Outrights (golf)
211
247
 
212
- ### Events
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.
213
249
 
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) |
250
+ ```typescript
251
+ import { ForbiddenError, isPriceRunner } from 'odds-api-io';
220
252
 
221
- ### Historical
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
+ }
222
264
 
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) |
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
+ ```
227
271
 
228
- ### 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.
229
273
 
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) |
274
+ ## Value bets, arbitrage and dropping odds
236
275
 
237
- ### Participants
276
+ ```typescript
277
+ const valueBets = await client.getValueBets({ bookmaker: 'Bet365', sport: 'football', includeEventDetails: true });
278
+ // expectedValue is bookmaker odds / fair odds x 100, so the edge in percent is expectedValue - 100 (103.42 = 3.42% edge)
279
+ valueBets
280
+ .filter((bet) => bet.expectedValue - 100 >= 3)
281
+ .forEach((bet) => console.log(bet.market.name, bet.betSide, `${(bet.expectedValue - 100).toFixed(2)}% edge`));
282
+
283
+ // Price gaps across your bookmakers. Prices move and bookmakers limit stakes, so check every leg before acting.
284
+ const arbs = await client.getArbitrageBets({ bookmakers: ['Bet365', 'SingBet'], sport: 'football', markets: ['Totals'], minProfit: 1 });
285
+ // profitMargin is already a percentage (2.48 = 2.48%)
286
+ arbs.forEach((arb) => console.log(`${arb.profitMargin.toFixed(2)}%`, arb.legs.map((l) => `${l.bookmaker} ${l.side} @ ${l.odds}`)));
287
+
288
+ // Dropping odds from sharp bookmakers (paid plans)
289
+ const drops = await client.getDroppingOdds({ sport: 'football', markets: ['ML'], minDrop: 10, sort: 'recent', includeEventDetails: true });
290
+ drops.forEach((d) => console.log(`${d.market.name} ${d.betSide}: ${d.odds.opening} -> ${d.odds.current} (-${d.odds.drop.sinceOpening}%)`));
291
+ ```
238
292
 
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) |
293
+ ## Participants, logos and mappings
243
294
 
244
- ### Bookmakers
295
+ ```typescript
296
+ const teams = await client.getParticipants({ sport: 'football', search: 'Chelsea' });
245
297
 
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) |
298
+ // PNG crest; the URL carries your key, so proxy it with getParticipantLogo() for public pages
299
+ const url = client.getParticipantLogoUrl(events[0].homeId!);
300
+ const png = await client.getParticipantLogo(events[0].homeId!); // ArrayBuffer
252
301
 
253
- ### Betting Analysis
302
+ // A bookmaker's own market and outcome ids for our events (paid plans)
303
+ const { data } = await client.getMappings({ bookmaker: 'Polymarket', eventId: 71515842 });
304
+ for await (const row of client.iterateMappings({ bookmaker: 'Kalshi', sport: 'american-football' })) {
305
+ console.log(row.eventId, row.market, row.side, row.marketId, row.outcomeId);
306
+ }
307
+ ```
254
308
 
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) |
309
+ ## Bookmakers
260
310
 
261
- ## Error Handling
311
+ ```typescript
312
+ const bookmakers = await client.getBookmakers(); // name, active, createdAt, status ('ok' | 'degraded' | 'down'), reason
313
+ await client.selectBookmakers(['Bet365', 'SingBet']);
314
+ const { bookmakers: selected } = await client.getSelectedBookmakers();
315
+ await client.clearSelectedBookmakers(); // once every 12 hours
316
+ ```
262
317
 
263
- The SDK includes custom error classes for better error handling:
318
+ ## Methods
319
+
320
+ | Area | Method | Endpoint |
321
+ |------|--------|----------|
322
+ | Catalogue | `getSports()` | `GET /sports` |
323
+ | | `getMarkets(sport?)` | `GET /markets` |
324
+ | | `getLeagues(sport, { all? })` | `GET /leagues` |
325
+ | | `getBookmakers()` | `GET /bookmakers` |
326
+ | | `getSelectedBookmakers()` | `GET /bookmakers/selected` |
327
+ | | `selectBookmakers(bookmakers)` | `PUT /bookmakers/selected/select` |
328
+ | | `clearSelectedBookmakers()` | `PUT /bookmakers/selected/clear` |
329
+ | Events | `getEvents(params)`, `iterateEvents(params, { pageSize?, maxPages? })` | `GET /events` |
330
+ | | `getEventById(id)` | `GET /events/{id}` |
331
+ | | `getLiveEvents(sport?)` | `GET /events/live` |
332
+ | | `searchEvents(query, { status? })` | `GET /events/search` |
333
+ | Odds | `getEventOdds(params)` | `GET /odds` |
334
+ | | `getOddsForMultipleEvents(params)`, `getOddsSnapshot(params)` | `GET /odds/multi` |
335
+ | | `getUpdatedOddsSince(params)`, `getUpdatedOddsSinceWithMeta(params)`, `pollUpdatedOdds(params)` | `GET /odds/updated` |
336
+ | | `getOddsMovement(params)` | `GET /odds/movements` |
337
+ | | `getOddsSummary(params)` | `GET /odds/summary` |
338
+ | | `getOddsSummaryMulti(params)` | `GET /odds/summary/multi` |
339
+ | Analysis | `getValueBets(params)` | `GET /value-bets` |
340
+ | | `getArbitrageBets(params)` | `GET /arbitrage-bets` |
341
+ | | `getDroppingOdds(params)`, `getDroppingOddsPage(params)`, `iterateDroppingOdds(params)` | `GET /dropping-odds` |
342
+ | Historical | `getHistoricalEvents(params)`, `iterateHistoricalEvents(params)` | `GET /historical/events` |
343
+ | | `searchHistoricalEvents(params)` | `GET /historical/events/search` |
344
+ | | `getHistoricalOdds(params)` | `GET /historical/odds` |
345
+ | | `getClosingLines(params)`, `iterateClosingLines(params)` | `GET /historical/closing-lines` |
346
+ | Settlement | `getSettlements(eventIds)` | `GET /settlements` |
347
+ | | `gradeBets(selections)` (alias `gradeSelections`) | `POST /settlements/grade` |
348
+ | Outrights | `getOutrights(params)` | `GET /outrights` |
349
+ | | `getOutrightOdds(params)` | `GET /outrights/odds` |
350
+ | | `getOutrightResults(id)` | `GET /outrights/results` |
351
+ | Participants | `getParticipants(params)` | `GET /participants` |
352
+ | | `getParticipantById(id)` | `GET /participants/{id}` |
353
+ | | `getParticipantLogo(id)`, `getParticipantLogoUrl(id)` | `GET /participants/{id}/logo` |
354
+ | Mappings | `getMappings(params)`, `iterateMappings(params)` | `GET /mappings` |
355
+ | WebSocket | `new OddsWebSocket(options)` | `wss://api.odds-api.io/v3/ws` |
356
+
357
+ Full parameter and response reference: [docs.odds-api.io/api-reference](https://docs.odds-api.io/api-reference).
358
+
359
+ ## Errors
360
+
361
+ Every error extends `OddsAPIError` and carries the server's own message, plus `status`, `body` and `rateLimit` when there was a response.
362
+
363
+ | Class | When |
364
+ |-------|------|
365
+ | `BadRequestError` | 400: a parameter is missing or invalid (the message says which) |
366
+ | `InvalidAPIKeyError` | 401 |
367
+ | `ForbiddenError` | 403: the plan does not include the endpoint or bookmaker, or an add-on is missing (`isAddOnRequired`) |
368
+ | `NotFoundError` | 404: the message often lists what does exist |
369
+ | `RateLimitError` | 429, with `retryAfter` in seconds (`RateLimitExceededError` is the same class) |
370
+ | `ServerError` | 5xx |
371
+ | `TimeoutError`, `NetworkError` | no response |
372
+ | `OddsWebSocketError` | WebSocket handshake refused or the helper gave up (`code` = HTTP status or close code) |
264
373
 
265
374
  ```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' });
375
+ import { OddsAPIError, RateLimitError, ForbiddenError } from 'odds-api-io';
277
376
 
278
377
  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
- }
378
+ await client.getClosingLines({ /* ... */ });
379
+ } catch (err) {
380
+ if (err instanceof RateLimitError) console.log(`retry in ${err.retryAfter}s`);
381
+ else if (err instanceof ForbiddenError) console.log(err.message);
382
+ else if (err instanceof OddsAPIError) console.log(err.status, err.message);
294
383
  }
384
+
385
+ console.log(client.lastRateLimit); // { limit, remaining, reset } from the last response
295
386
  ```
296
387
 
297
388
  ## Configuration
@@ -299,52 +390,49 @@ try {
299
390
  ```typescript
300
391
  const client = new OddsAPIClient({
301
392
  apiKey: 'your-api-key',
302
- baseUrl: 'https://api2.odds-api.io/v3', // Optional, default shown
303
- timeout: 10000 // Optional, default 10 seconds
393
+ baseUrl: 'https://api.odds-api.io/v3', // default
394
+ timeout: 10000, // ms per attempt
395
+ maxRetries: 2, // retries on 5xx, network errors and short 429 waits; 0 turns them off
396
+ maxRetryDelay: 10000, // a 429 asking for a longer wait is thrown, not waited out
304
397
  });
305
398
  ```
306
399
 
307
- ## TypeScript Support
400
+ Bookmaker selection changes (PUT) are never retried.
308
401
 
309
- This SDK is written in TypeScript and includes complete type definitions:
402
+ ## Migrating from 1.3
310
403
 
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
- ```
404
+ 1.5.0 aligns the types with what the API returns. Code that used the old, inaccurate field names needs updating:
329
405
 
330
- ## Plans and Limits
406
+ - `Event`: `date`, `home`, `away`, `homeId`, `awayId`, `status` (`pending | live | settled | cancelled`), `sport`/`league` as `{ name, slug }`, `scores.periods`.
407
+ - Period keys are `p1`..`pN`, `ft`, `ot`, `ap`. The old `period1`, `overtime`, `penalties` and `fulltime` keys stop being served on 12 November 2026.
408
+ - `EventOdds.bookmakers` is a map of bookmaker name to markets; `OddsMovement` has `opening`, `latest` and `movements`.
409
+ - `ArbitrageBet` uses `profitMargin` and `legs[].side`; `ValueBet` uses `expectedValue` and `betSide`.
410
+ - `Bookmaker` is `{ name, active, createdAt, status, reason }`; `getSelectedBookmakers()` returns `{ bookmakers, count }`.
411
+ - `getDroppingOdds` now sends `markets` (the old `market` option was ignored by the API; it is still accepted and sent as `markets`).
412
+ - Errors keep the server message instead of a fixed text.
413
+ - The default base URL is `https://api.odds-api.io/v3`.
414
+
415
+ ## Examples
331
416
 
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.
417
+ See [`examples/`](./examples):
333
418
 
334
- ## Resources
419
+ - `basic-usage.ts` / `basic-usage.js`: getting started
420
+ - `premier-league-odds.ts`: odds for a league
421
+ - `odds-tracking.ts`: price history and the updated-odds delta
422
+ - `arbitrage-betting.ts`: price gaps across bookmakers
423
+ - `websocket-feed.ts`: REST snapshot plus `OddsWebSocket`
424
+ - `golf-outrights-and-settlement.ts`: outrights and bet grading
335
425
 
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)
426
+ ## Plans and Limits
340
427
 
341
- ## Examples Directory
428
+ 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
429
 
343
- Check the [`examples/`](./examples) directory for more comprehensive examples:
430
+ ## Resources
344
431
 
345
- - `basic-usage.ts` / `basic-usage.js` - Getting started
346
- - `arbitrage-betting.ts` - Finding arbitrage opportunities
347
- - `odds-tracking.ts` - Monitoring odds movements
432
+ - [API documentation](https://docs.odds-api.io/)
433
+ - [Odds-API.io website](https://odds-api.io)
434
+ - [Get your API key](https://odds-api.io/pricing?ref=npm)
435
+ - [Report issues](https://github.com/odds-api-io/odds-api-node/issues)
348
436
 
349
437
  ## License
350
438
 
@@ -354,14 +442,11 @@ Check the [`examples/`](./examples) directory for more comprehensive examples:
354
442
 
355
443
  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
444
 
357
- ---
358
-
359
- Built with ❤️ for the sports betting and analytics community
360
445
 
361
446
  ## Citation
362
447
 
363
448
  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
449
 
365
450
  ```
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
451
+ Outlier AS. odds-api-io: Official Node.js SDK for Odds-API.io (version 1.5.2). https://github.com/odds-api-io/odds-api-node
367
452
  ```