be-components 7.7.2 → 7.7.4

package/lib/commonjs/BetRouter/types/LIQUIDITY_CLIENT_GUIDE.md

@@ -0,0 +1,399 @@
+# Liquidity API - Client Integration Guide
+
+This guide shows how to use the liquidity endpoint to build a contest liquidity dashboard component.
+
+---
+
+## 📋 Endpoint
+
+**`GET /liquidity/contest/:router_contest_id`**
+
+**Query Parameters:**
+- `partner_ids` (optional): Comma-separated partner IDs to fetch liquidity from
+  - Example: `"partner1,partner2"`
+  - If omitted, fetches from all active partners
+- `include_opportunities` (optional): Set to `'true'` to include calculated opportunities in response
+  - Example: `"true"`
+  - Default: `false` (opportunities not included)
+  - When `true`, the response includes `opportunity_count` and `opportunities` array
+
+---
+
+## 🎯 Use Case: Contest Liquidity Dashboard
+
+Display all available betting opportunities for a specific contest with prices from different partners.
+
+---
+
+## 💻 TypeScript Example
+
+```typescript
+import {
+  RouterLiquidityProps,
+  RouterContestProps,
+  RouterPartnerProps,
+  PartnerMarketProps,
+  RouterMarketProps,
+  RouterMarketSideProps,
+  RouterMarketVariableProps,
+  ApiContracts,
+  ExtractSuccessResponse
+} from './types/betrouter';
+
+// Type-safe response
+type LiquidityResponse = ExtractSuccessResponse<'GET /liquidity/contest/:router_contest_id'>;
+
+async function fetchContestLiquidity(
+  contestId: string,
+  partnerIds?: string[],
+  includeOpportunities: boolean = false
+): Promise<LiquidityResponse> {
+  const url = new URL(`/liquidity/contest/${contestId}`, 'https://api.example.com');
+
+  if (partnerIds && partnerIds.length > 0) {
+    url.searchParams.set('partner_ids', partnerIds.join(','));
+  }
+
+  if (includeOpportunities) {
+    url.searchParams.set('include_opportunities', 'true');
+  }
+
+  const response = await fetch(url.toString());
+  return response.json();
+}
+```
+
+---
+
+## 📊 Response Structure
+
+### Without Opportunities (default)
+
+```typescript
+{
+  message: "Successfully fetched liquidity",
+  contest: {
+    router_contest_id: "contest-123",
+    contest_label: "Lakers vs Celtics",
+    scheduled_datetime: "2025-10-30T19:00:00Z",
+    status: "open"
+  },
+  partners: [
+    {
+      partner_id: "bettoredge-id",
+      name: "BettorEdge",
+      status: "active"
+    }
+  ],
+  liquidity_count: 42,
+  liquidities: [
+    {
+      router_liquidity_id: "liq-123",
+      liquidity_hash: "partner:contest:market:side:variable:participant:timeframe:price",
+      title: "Lakers to win Full Game",  // 🎯 HUMAN-READABLE TITLE
+      router_contest_id: "contest-123",
+      partner_market_id: "pm-123",
+      price: 0.55,
+      available: 100,
+      expire_datetime: "2025-10-30T19:00:00Z",
+      buy_id: "order-456",
+      create_datetime: "2025-10-30T12:00:00Z",
+      last_update_datetime: "2025-10-30T12:00:00Z"
+    },
+    {
+      router_liquidity_id: "liq-124",
+      liquidity_hash: "partner:contest:market:side:variable:participant:timeframe:price",
+      title: "Lakers -3.5 Full Game",  // 🎯 SPREAD WITH VARIABLE
+      router_contest_id: "contest-123",
+      partner_market_id: "pm-124",
+      price: 0.52,
+      available: 200,
+      expire_datetime: "2025-10-30T19:00:00Z",
+      buy_id: "order-457",
+      create_datetime: "2025-10-30T12:00:00Z",
+      last_update_datetime: "2025-10-30T12:00:00Z"
+    }
+  ],
+  partner_markets: [ /* All partner_markets for context */ ],
+  router_markets: [ /* All router_markets for grouping */ ],
+  router_market_sides: [ /* All sides for filtering */ ],
+  router_market_variables: [ /* All variables for display */ ]
+}
+```
+
+### With Opportunities (include_opportunities=true)
+
+When `include_opportunities=true`, the response includes two additional fields:
+
+```typescript
+{
+  // ... all fields from above ...
+  opportunity_count: 3,  // Number of arbitrage opportunities found
+  opportunities: [
+    {
+      opportunity_type: "arbitrage",
+      router_contest_id: "contest-123",
+      router_market_id: "rm-spread",
+      expected_profit: 15.50,
+      total_cost: 100,
+      legs: [
+        {
+          partner_id: "bettoredge-id",
+          partner_name: "BettorEdge",
+          router_liquidity_id: "liq-123",
+          amount: 50,
+          // ... leg details
+        },
+        {
+          partner_id: "kalshi-id",
+          partner_name: "Kalshi",
+          router_liquidity_id: "liq-456",
+          amount: 50,
+          // ... leg details
+        }
+      ]
+    }
+    // ... more opportunities
+  ]
+}
+```
+
+**Benefits of `include_opportunities=true`:**
+- Single API call instead of two separate calls
+- No duplicate data fetching - uses the same liquidity data
+- Opportunities are calculated server-side with the same data already fetched
+- Efficient and type-safe
+
+---
+
+## 🎨 Example React Component
+
+```tsx
+import { useState, useEffect } from 'react';
+import type { RouterLiquidityProps, RouterPartnerProps } from './types/betrouter';
+
+interface ContestLiquidityProps {
+  contestId: string;
+  partnerIds?: string[];
+}
+
+export function ContestLiquidity({ contestId, partnerIds }: ContestLiquidityProps) {
+  const [liquidities, setLiquidities] = useState<RouterLiquidityProps[]>([]);
+  const [partners, setPartners] = useState<RouterPartnerProps[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    async function fetchData() {
+      const url = new URL(`/liquidity/contest/${contestId}`, window.location.origin);
+
+      if (partnerIds && partnerIds.length > 0) {
+        url.searchParams.set('partner_ids', partnerIds.join(','));
+      }
+
+      const response = await fetch(url.toString());
+      const data = await response.json();
+
+      setLiquidities(data.liquidities);
+      setPartners(data.partners);
+      setLoading(false);
+    }
+
+    fetchData();
+  }, [contestId, partnerIds]);
+
+  if (loading) return <div>Loading liquidity...</div>;
+
+  return (
+    <div className="liquidity-table">
+      <h2>Available Betting Opportunities</h2>
+      <p>Showing liquidity from: {partners.map(p => p.name).join(', ')}</p>
+
+      <table>
+        <thead>
+          <tr>
+            <th>Market</th>
+            <th>Price</th>
+            <th>Available</th>
+            <th>Partner</th>
+          </tr>
+        </thead>
+        <tbody>
+          {liquidities.map((liq) => (
+            <tr key={liq.router_liquidity_id}>
+              <td>{liq.title}</td> {/* 🎯 HUMAN-READABLE */}
+              <td>{(liq.price * 100).toFixed(1)}%</td>
+              <td>${liq.available}</td>
+              <td>
+                {partners.find(p =>
+                  p.partner_id === liq.partner_market_id.split('-')[0]
+                )?.name}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+```
+
+---
+
+## 🎯 Key Features
+
+### ✅ Pre-rendered Titles
+The `title` field is **already rendered server-side** using the market side's `renderer` template:
+- **Moneyline:** "Lakers to win Full Game"
+- **Spread:** "Lakers -3.5 Full Game"
+- **Totals:** "Total Points over 220.5 Full Game"
+
+**You don't need to render titles client-side - just display `liquidity.title`!**
+
+### ✅ Type Safety
+All types are available from the shared types folder:
+```typescript
+import {
+  RouterLiquidityProps,
+  RouterContestProps,
+  PartnerMarketProps,
+  ApiContracts,
+  ExtractSuccessResponse
+} from './types/betrouter';
+```
+
+### ✅ Partner Filtering
+Fetch liquidity from specific partners only:
+```typescript
+// Only BettorEdge
+fetchContestLiquidity(contestId, ['bettoredge-partner-id']);
+
+// BettorEdge and Kalshi
+fetchContestLiquidity(contestId, ['bettoredge-id', 'kalshi-id']);
+
+// All partners
+fetchContestLiquidity(contestId);
+```
+
+### ✅ Rich Context Data
+Response includes all related entities for building complex UIs:
+- `partner_markets` - Link liquidity to markets
+- `router_markets` - Group by market type
+- `router_market_sides` - Filter by side (home/away/over/under)
+- `router_market_variables` - Display spread/total values
+
+---
+
+## 🔄 Grouping Liquidity by Market
+
+```typescript
+function groupLiquiditiesByMarket(
+  liquidities: RouterLiquidityProps[],
+  partnerMarkets: PartnerMarketProps[],
+  routerMarkets: RouterMarketProps[]
+) {
+  const grouped = new Map<string, RouterLiquidityProps[]>();
+
+  liquidities.forEach(liq => {
+    const partnerMarket = partnerMarkets.find(pm => pm.partner_market_id === liq.partner_market_id);
+    if (!partnerMarket) return;
+
+    const routerMarket = routerMarkets.find(rm => rm.router_market_id === partnerMarket.router_market_id);
+    if (!routerMarket) return;
+
+    const key = routerMarket.market_label; // "Moneyline", "Spread", etc.
+
+    if (!grouped.has(key)) {
+      grouped.set(key, []);
+    }
+    grouped.get(key)!.push(liq);
+  });
+
+  return grouped;
+}
+```
+
+---
+
+## 🎨 Example UI Display
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Lakers vs Celtics - October 30, 2025 7:00 PM             │
+│ Showing liquidity from: BettorEdge, Kalshi                │
+├────────────────────────────────────────────────────────────┤
+│                                                            │
+│ Moneyline                                                  │
+│ ┌────────────────────────┬──────┬────────┬──────────────┐ │
+│ │ Market                 │ Price│Available│ Partner      │ │
+│ ├────────────────────────┼──────┼────────┼──────────────┤ │
+│ │ Lakers to win Full Game│ 55%  │ $100   │ BettorEdge   │ │
+│ │ Lakers to win Full Game│ 54%  │ $200   │ Kalshi       │ │
+│ │ Celtics to win Full...│ 48%  │ $150   │ BettorEdge   │ │
+│ └────────────────────────┴──────┴────────┴──────────────┘ │
+│                                                            │
+│ Spread                                                     │
+│ ┌────────────────────────┬──────┬────────┬──────────────┐ │
+│ │ Market                 │ Price│Available│ Partner      │ │
+│ ├────────────────────────┼──────┼────────┼──────────────┤ │
+│ │ Lakers -3.5 Full Game │ 52%  │ $250   │ BettorEdge   │ │
+│ │ Lakers -3.5 Full Game │ 51%  │ $300   │ Kalshi       │ │
+│ │ Celtics +3.5 Full Game│ 50%  │ $200   │ BettorEdge   │ │
+│ └────────────────────────┴──────┴────────┴──────────────┘ │
+│                                                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📚 Related Types Reference
+
+```typescript
+interface RouterLiquidityProps {
+  router_liquidity_id: string;
+  liquidity_hash: string;  // Unique identifier with all context
+  title: string;           // 🎯 Human-readable title (pre-rendered)
+  router_contest_id: string;
+  partner_market_id: string;
+  price: number;           // Probability (0-1)
+  available: number;       // Amount available to bet
+  expire_datetime: string;
+  buy_id?: string;         // Partner's order ID
+  create_datetime: string;
+  last_update_datetime: string;
+}
+
+interface RouterContestProps {
+  router_contest_id: string;
+  contest_label: string;
+  scheduled_datetime: string;
+  status: 'open' | 'closed' | 'settled';
+  // ... other fields
+}
+
+interface RouterPartnerProps {
+  partner_id: string;
+  name: string;  // "BettorEdge", "Kalshi", "BetOpenly"
+  status: 'active' | 'inactive';
+  // ... other fields
+}
+```
+
+---
+
+## ✅ Summary
+
+**What you get:**
+- ✅ Pre-rendered, human-readable titles for all liquidity
+- ✅ Type-safe API contracts
+- ✅ All related data for complex UIs
+- ✅ Partner filtering support
+- ✅ Real-time price and availability data
+
+**What you need to do:**
+1. Copy the `/src/types` folder to your client project
+2. Import the types
+3. Fetch from `GET /liquidity/contest/:router_contest_id`
+4. Display `liquidity.title` (already formatted!)
+5. Build your UI
+
+**No client-side title rendering needed!** 🎉