fix: align OpenAPI spec, SDK docs, and API reference with canonical field names

Mlaz-code · claude · Mlaz-code · commit ecb2048a4f8f · 2026-03-21T11:50:04.000-04:00
OpenAPI spec used deprecated field names (ev_percent, true_probability,
devig_book, kelly_fraction) that didn't match the canonical API response
fields. Updated to ev_percentage, fair_probability, sharp_book, kelly_percent
across EVOpportunity and HistoricalOpportunity schemas, examples, and all
doc pages. Fixed SDK install command (@sharpapi/client → @sharp-api/client)
and class names in llms-full.txt. Added llms.txt discovery link tags to
HTML head via Next.js Metadata API.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/app/layout.tsx b/app/layout.tsx
@@ -19,6 +19,14 @@ export const metadata: Metadata = {
     siteName: 'SharpAPI Docs',
     images: [{ url: 'https://sharpapi.io/og-image.png', width: 1200, height: 630, alt: 'SharpAPI - Sports Betting Odds API' }],
   },
+  alternates: {
+    types: {
+      'text/plain': [
+        { url: 'https://docs.sharpapi.io/llms.txt', title: 'LLM-friendly documentation' },
+        { url: 'https://docs.sharpapi.io/llms-full.txt', title: 'LLM-friendly full documentation' },
+      ],
+    },
+  },
 }
 
 export default function RootLayout({ children }) {
diff --git a/content/en/api-reference/opportunities-ev.mdx b/content/en/api-reference/opportunities-ev.mdx
@@ -13,7 +13,7 @@ GET /api/v1/opportunities/ev
 ```
 
 <Callout type="info">
-This endpoint replaces the former `/positive-ev` and `/value-bets` endpoints. All scoring fields (`confidence_score`, `kelly_fraction`, `fair_probability`) are now included in every response.
+This endpoint replaces the former `/positive-ev` and `/value-bets` endpoints. All scoring fields (`confidence_score`, `kelly_percent`, `fair_probability`) are now included in every response.
 </Callout>
 
 ## Authentication
@@ -38,7 +38,7 @@ Requires API key. **Pro tier or higher required.** Your account must have the `e
 | `max_market_width` | number | — | Maximum market width |
 | `max_odds_age` | number | — | Maximum odds age in seconds. Filters out stale opportunities where the underlying odds are older than this threshold. |
 | `date_range` | string | — | Filter by event date: `today`, `tomorrow`, or `week`. Dates are evaluated in **US Eastern Time (ET)**. |
-| `sort` | string | `-ev` | Sort field. Options: `ev`, `confidence`/`confidence_score`, `kelly`/`kelly_fraction`, `time`/`start_time`, `book_count`/`books`. Prefix with `-` for descending. |
+| `sort` | string | `-ev` | Sort field. Options: `ev`, `confidence`/`confidence_score`, `kelly`/`kelly_percent`, `time`/`start_time`, `book_count`/`books`. Prefix with `-` for descending. |
 | `limit` | integer | 50 | Results per page (max 200) |
 | `offset` | integer | 0 | Pagination offset (max 5000) |
 
@@ -121,7 +121,7 @@ for opp in data['data']:
       "start_time": "2026-02-08T19:00:00Z",
       "is_live": false,
       "confidence_score": 87,
-      "kelly_fraction": 0.021,
+      "kelly_percent": 0.021,
       "book_count": 5,
       "arb_available": false,
       "arb_profit": null,
@@ -251,7 +251,7 @@ X-Request-Id: req_abc123def456
 | `start_time` | string\|null | ISO 8601 event start time |
 | `is_live` | boolean | Whether the event is currently live |
 | `confidence_score` | number | Multi-factor confidence score (0-100) |
-| `kelly_fraction` | number\|null | Kelly criterion optimal bet fraction (0.0 to 1.0) |
+| `kelly_percent` | number\|null | Kelly criterion optimal bet fraction (0.0 to 1.0) |
 | `book_count` | number | Number of sportsbooks offering this market |
 | `arb_available` | boolean | Whether an arbitrage exists on this market |
 | `arb_profit` | number\|null | Arbitrage profit percentage if available |
@@ -348,7 +348,7 @@ We recommend setting `min_ev=2` for most use cases. Marginal EV (below 2%) can b
 
 ## Kelly Criterion
 
-The `kelly_fraction` field tells you the optimal fraction of your bankroll to wager according to the Kelly criterion (0.0 to 1.0, e.g. `0.021` = 2.1%):
+The `kelly_percent` field tells you the optimal fraction of your bankroll to wager according to the Kelly criterion (0.0 to 1.0, e.g. `0.021` = 2.1%):
 
 ```
 Kelly% = (edge / odds_to_1) = (fair_prob x decimal_odds - 1) / (decimal_odds - 1)
@@ -370,7 +370,7 @@ Kelly% = (edge / odds_to_1) = (fair_prob x decimal_odds - 1) / (decimal_odds - 1
 ## Best Practices
 
 1. **Set a minimum EV threshold** - Use `min_ev=2` or higher to focus on meaningful edges
-2. **Use Kelly sizing** - Use `kelly_fraction` to determine bet size (multiply by bankroll)
+2. **Use Kelly sizing** - Use `kelly_percent` to determine bet size (multiply by bankroll)
 3. **Filter by confidence** - Use `confidence_score` to prioritize high-confidence opportunities
 4. **Monitor `market_width`** - Narrow markets (low width) indicate more efficient pricing and more reliable EV calculations
 5. **Act quickly** - +EV opportunities are fleeting; lines move fast
diff --git a/content/en/api-reference/stream.mdx b/content/en/api-reference/stream.mdx
@@ -112,7 +112,7 @@ A new positive expected value opportunity has been found. Only sent on `opportun
 ```
 event: ev:detected
 id: evt_00043
-data: [{"id":"a1b2c3d4e5f6","game_id":"nba_phosuns_phi76ers_2026-02-08","ev_percentage":4.35,"odds_american":-105,"odds_decimal":1.952,"no_vig_odds":-101,"selection":"PHO Suns -3.5","market":"point_spread","line":-3.5,"sportsbook":"draftkings","game":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","is_live":false,"confidence_score":72,"kelly_fraction":0.038,"book_count":4,"detected_at":"2026-02-08T18:47:20.000Z"}]
+data: [{"id":"a1b2c3d4e5f6","game_id":"nba_phosuns_phi76ers_2026-02-08","ev_percentage":4.35,"odds_american":-105,"odds_decimal":1.952,"no_vig_odds":-101,"selection":"PHO Suns -3.5","market":"point_spread","line":-3.5,"sportsbook":"draftkings","game":"PHO Suns @ PHI 76ers","sport":"basketball","league":"nba","home_team":"PHI 76ers","away_team":"PHO Suns","start_time":"2026-02-08T19:00:00.000Z","is_live":false,"confidence_score":72,"kelly_percent":0.038,"book_count":4,"detected_at":"2026-02-08T18:47:20.000Z"}]
 ```
 
 ### `ev:expired`
diff --git a/content/en/api-reference/websocket.mdx b/content/en/api-reference/websocket.mdx
@@ -209,7 +209,7 @@ Snapshot of opportunities for a single channel type. Sent once per subscribed op
       "start_time": "2026-02-08T19:00:00.000Z",
       "is_live": false,
       "confidence_score": 72,
-      "kelly_fraction": 0.038,
+      "kelly_percent": 0.038,
       "book_count": 4,
       "detected_at": "2026-02-08T18:47:20.000Z"
     }
@@ -322,7 +322,7 @@ New +EV opportunity found. Pro tier or higher only.
       "start_time": "2026-02-08T19:00:00.000Z",
       "is_live": false,
       "confidence_score": 72,
-      "kelly_fraction": 0.038,
+      "kelly_percent": 0.038,
       "book_count": 4,
       "detected_at": "2026-02-08T18:47:20.000Z"
     }
diff --git a/content/en/examples/value-betting.mdx b/content/en/examples/value-betting.mdx
@@ -70,7 +70,7 @@ async function sendAlert(opp) {
       { name: 'Book', value: opp.sportsbook, inline: true },
       { name: 'Odds', value: String(opp.odds_american), inline: true },
       { name: 'EV', value: `+${opp.ev_percentage}%`, inline: true },
-      { name: 'Kelly', value: `${opp.kelly_fraction}`, inline: true },
+      { name: 'Kelly', value: `${opp.kelly_percent}`, inline: true },
       { name: 'Devig', value: `${opp.no_vig_odds} (${opp.sharp_book})`, inline: true },
     )
     .setTimestamp();
@@ -130,7 +130,7 @@ Selection: ${opp.selection}
 Book: ${opp.sportsbook}
 Odds: ${opp.odds_american}
 EV: +${opp.ev_percentage}%
-Kelly: ${opp.kelly_fraction}
+Kelly: ${opp.kelly_percent}
   `.trim();
 
   await bot.sendMessage(chatId, message, { parse_mode: 'Markdown' });
diff --git a/content/en/quickstart.mdx b/content/en/quickstart.mdx
@@ -158,7 +158,7 @@ Response:
         "probability": 0.535
       },
       "ev_percentage": 4.35,
-      "kelly_fraction": 0.0218
+      "kelly_percent": 0.0218
     }
   ],
   "meta": {
diff --git a/content/en/sdks/python.mdx b/content/en/sdks/python.mdx
@@ -40,8 +40,8 @@ for arb in arbs.data:
 evs = client.ev.get(min_ev=3.0, sport="basketball")
 for opp in evs.data:
     print(f"+{opp.ev_percentage:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
-    if opp.kelly_fraction:
-        print(f"  Kelly: {opp.kelly_fraction:.1%}, Confidence: {opp.confidence_score}")
+    if opp.kelly_percent:
+        print(f"  Kelly: {opp.kelly_percent:.1%}, Confidence: {opp.confidence_score}")
 
 # Best odds across sportsbooks
 odds = client.odds.best(league="nba", market="moneyline")
@@ -83,7 +83,7 @@ for opp in evs.data:
     print(f"+{opp.ev_percentage:.1f}% on {opp.selection} @ {opp.sportsbook}")
     print(f"  Fair probability: {opp.fair_probability}")
     print(f"  Devig: {opp.devig_method} via {opp.sharp_book}")
-    print(f"  Kelly: {opp.kelly_fraction:.1%}")
+    print(f"  Kelly: {opp.kelly_percent:.1%}")
     print(f"  Confidence: {opp.confidence_score}/100")
 ```
 
diff --git a/content/en/sdks/typescript.mdx b/content/en/sdks/typescript.mdx
@@ -115,7 +115,7 @@ interface EVOpportunity {
   league: string;
   is_live: boolean;
   confidence_score: number;
-  kelly_fraction: number | null;
+  kelly_percent: number | null;
   possibly_stale: boolean;
   oldest_odds_age_seconds: number | null;
   warnings: string[];
diff --git a/public/llms-full.txt b/public/llms-full.txt
@@ -869,7 +869,7 @@ curl -H "X-API-Key: YOUR_KEY" \
       },
       "ev_percentage": 4.35,
       "edge": 0.023,
-      "kelly_fraction": 0.0218,
+      "kelly_percent": 0.0218,
       "kelly_half": 0.0109,
       "recommended_stake_pct": 1.09,
       "deep_link": "https://sportsbook.draftkings.com/...",
@@ -889,7 +889,7 @@ curl -H "X-API-Key: YOUR_KEY" \
 
 **Key fields**:
 - `ev_percentage`: Expected value as a percentage (e.g., 4.35 = 4.35% edge)
-- `kelly_fraction`: Full Kelly criterion stake as fraction of bankroll
+- `kelly_percent`: Full Kelly criterion stake as fraction of bankroll
 - `kelly_half`: Half Kelly (more conservative, recommended)
 - `edge`: Raw probability edge (sharp probability - implied probability)
 - `sharp_odds`: Reference line from Pinnacle
@@ -1366,22 +1366,22 @@ SharpAPI uses canonical event IDs (e.g., `evt_nba_lal_bos_20260126`) to match th
 
 ### TypeScript / JavaScript
 ```
-npm install @sharpapi/client
+npm install @sharp-api/client
 ```
 ```typescript
-import { SharpApiClient } from '@sharpapi/client';
-const client = new SharpApiClient('sk_live_your_key');
-const { data, meta } = await client.getOdds({ league: 'nba' });
+import { SharpAPI } from '@sharp-api/client';
+const api = new SharpAPI('sk_live_your_key');
+const { data } = await api.odds.get({ league: 'nba' });
 ```
 
 ### Python
 ```
 pip install sharpapi
 ```
 ```python
-from sharpapi import SharpApiClient
-client = SharpApiClient("sk_live_your_key")
-odds = client.get_odds(league="nba")
+from sharpapi import SharpAPI
+client = SharpAPI("sk_live_your_key")
+odds = client.odds.get(league="nba")
 ```
 
 ### Other Languages
diff --git a/public/llms.txt b/public/llms.txt
@@ -39,7 +39,7 @@
 
 ## Optional
 
-- [TypeScript SDK](https://docs.sharpapi.io/en/sdks/typescript): `npm install @sharpapi/client`
+- [TypeScript SDK](https://docs.sharpapi.io/en/sdks/typescript): `npm install @sharp-api/client`
 - [Python SDK](https://docs.sharpapi.io/en/sdks/python): `pip install sharpapi`
 - [Streaming Guide](https://docs.sharpapi.io/en/streaming/overview): SSE and WebSocket setup
 - [Arbitrage Concepts](https://docs.sharpapi.io/en/concepts/arbitrage): How arbitrage detection works
diff --git a/public/openapi.json b/public/openapi.json
@@ -1567,7 +1567,7 @@
                     {
                       "id": "a1b2c3d4e5f67890",
                       "game_id": "nba-20260309-lal-bos",
-                      "ev_percent": 4.2,
+                      "ev_percentage": 4.2,
                       "odds_american": 135,
                       "odds_decimal": 2.35,
                       "no_vig_odds": 125,
@@ -1583,14 +1583,14 @@
                       "start_time": "2026-03-09T19:30:00Z",
                       "is_live": false,
                       "market_width": 6.5,
-                      "true_probability": 0.444,
+                      "fair_probability": 0.444,
                       "devig_method": "multiplicative",
-                      "devig_book": "pinnacle",
+                      "sharp_book": "pinnacle",
                       "external_event_id": "dk-123456",
                       "selection_id": "sel-789",
                       "detected_at": "2026-03-09T14:22:15Z",
                       "confidence_score": 78,
-                      "kelly_fraction": 0.031,
+                      "kelly_percent": 0.031,
                       "book_count": 8,
                       "arb_available": false,
                       "arb_profit": null,
@@ -2187,7 +2187,7 @@
                   "type": "string",
                   "description": "Server-Sent Events stream. Each event has `event:` type, `data:` JSON payload, and `id:` for reconnection."
                 },
-                "example": "event: connected\ndata: {\"filters\":{\"channel\":\"opportunities\",\"sport\":null},\"session_id\":\"abc123\"}\nid: 1709993400000-1\n\nevent: ev:detected\ndata: {\"id\":\"a1b2c3d4e5f67890\",\"ev_percent\":4.2,\"sportsbook\":\"draftkings\",\"selection\":\"Los Angeles Lakers\",\"market\":\"moneyline\",\"sport\":\"basketball\",\"league\":\"nba\"}\nid: 1709993400000-2\n\nevent: heartbeat\ndata: {\"ts\":1709993430000}\nid: 1709993430000-3\n"
+                "example": "event: connected\ndata: {\"filters\":{\"channel\":\"opportunities\",\"sport\":null},\"session_id\":\"abc123\"}\nid: 1709993400000-1\n\nevent: ev:detected\ndata: {\"id\":\"a1b2c3d4e5f67890\",\"ev_percentage\":4.2,\"sportsbook\":\"draftkings\",\"selection\":\"Los Angeles Lakers\",\"market\":\"moneyline\",\"sport\":\"basketball\",\"league\":\"nba\"}\nid: 1709993400000-2\n\nevent: heartbeat\ndata: {\"ts\":1709993430000}\nid: 1709993430000-3\n"
               }
             }
           },
@@ -4683,7 +4683,7 @@
         "required": [
           "id",
           "game_id",
-          "ev_percent",
+          "ev_percentage",
           "odds_american",
           "odds_decimal",
           "no_vig_odds",
@@ -4699,14 +4699,14 @@
           "start_time",
           "is_live",
           "market_width",
-          "true_probability",
+          "fair_probability",
           "devig_method",
-          "devig_book",
+          "sharp_book",
           "external_event_id",
           "selection_id",
           "detected_at",
           "confidence_score",
-          "kelly_fraction",
+          "kelly_percent",
           "book_count",
           "arb_available",
           "arb_profit",
@@ -4727,9 +4727,9 @@
             "type": "string",
             "nullable": true
           },
-          "ev_percent": {
+          "ev_percentage": {
             "type": "number",
-            "description": "Expected value percentage",
+            "description": "Expected value as a percentage (e.g., 4.2 = 4.2% EV)",
             "example": 4.2
           },
           "odds_american": {
@@ -4795,19 +4795,19 @@
             "nullable": true,
             "description": "Spread between best and worst odds across books"
           },
-          "true_probability": {
+          "fair_probability": {
             "type": "number",
             "nullable": true,
-            "description": "Devigged true probability"
+            "description": "No-vig (devigged) fair probability (0.0 to 1.0)"
           },
           "devig_method": {
             "type": "string",
             "description": "Method used to remove vig",
             "example": "multiplicative"
           },
-          "devig_book": {
+          "sharp_book": {
             "type": "string",
-            "description": "Sharp book used as reference",
+            "description": "Sharp book used as reference (e.g., pinnacle)",
             "example": "pinnacle"
           },
           "external_event_id": {
@@ -4829,7 +4829,7 @@
             "description": "Multi-factor confidence score (0-100)",
             "example": 78
           },
-          "kelly_fraction": {
+          "kelly_percent": {
             "type": "number",
             "nullable": true,
             "description": "Optimal bet fraction (0.0-1.0) from Kelly criterion"
@@ -5912,15 +5912,15 @@
               "decimal_odds": {
                 "type": "number"
               },
-              "ev_percent": {
+              "ev_percentage": {
                 "type": "number",
                 "nullable": true
               },
               "no_vig_price": {
                 "type": "number",
                 "nullable": true
               },
-              "true_probability": {
+              "fair_probability": {
                 "type": "number",
                 "nullable": true
               },
@@ -5932,14 +5932,14 @@
                 "type": "number",
                 "nullable": true
               },
-              "kelly_fraction": {
+              "kelly_percent": {
                 "type": "number",
                 "nullable": true
               },
               "devig_method": {
                 "type": "string"
               },
-              "devig_book": {
+              "sharp_book": {
                 "type": "string"
               },
               "book_count": {

Original file line number	Diff line number	Diff line change
`@@ -158,7 +158,7 @@ Response:`
`158`	`158`	`"probability": 0.535`
`159`	`159`	`},`
`160`	`160`	`"ev_percentage": 4.35,`
`161`		`- "kelly_fraction": 0.0218`
	`161`	`+ "kelly_percent": 0.0218`
`162`	`162`	`}`
`163`	`163`	`],`
`164`	`164`	`"meta": {`