Stream WebSocket

wss://ws.sharpapi.io — Actualizaciones de cuotas y oportunidades en tiempo real mediante WebSocket.

¿Por qué WebSocket?Permalink for this section

WebSocket proporciona una conexión persistente y full-duplex. En comparación con SSE:

Ambos protocolos entregan los mismos datos con la misma latencia. Elige WebSocket cuando necesites cambiar filtros sin reconectar.

AutenticaciónPermalink for this section

Pasa tu API key como parámetro de consulta en la URL de conexión:

wss://ws.sharpapi.io?api_key=sk_live_your_key

También puedes pasar filtros iniciales y suscripciones a canales como parámetros de consulta:

wss://ws.sharpapi.io?api_key=sk_live_your_key&channels=ev,odds&sport=basketball&sportsbook=draftkings,fanduel&league=nba

Parámetros de consultaPermalink for this section

Ciclo de vida de la conexiónPermalink for this section

Cliente                                        Servidor
  |                                               |
  |--- WS Upgrade ?api_key=xxx&channels=ev,odds →|
  |                                               |  Auth + adquirir slot de stream
  |← connected ----------------------------------|  Bienvenida (tier, features, channels)
  |← subscribed ---------------------------------|  Confirmación de filtros
  |← opportunities_snapshot (ev) ----------------|  Oportunidades EV
  |← initial (draftkings) -----------------------|  Cuotas por sportsbook
  |← initial (fanduel) --------------------------|  (fragmentadas por book)
  |← snapshot:complete --------------------------|  Todos los datos iniciales enviados
  |                                               |
  |← odds:update --------------------------------|  Actualización incremental de cuotas
  |← ev:detected --------------------------------|  Oportunidad +EV (nueva o actualizada)
  |← heartbeat ----------------------------------|  Keep-alive (cada 30s)
  |                                               |
  |--- { type: "ping" } →                       |
  |← pong ---------------------------------------|
  |                                               |
  |--- { type: "subscribe", channels, filters } →|  Actualizar canales/filtros
  |← subscribed ---------------------------------|  Nueva suscripción confirmada
  |                                               |
  |--- close ----------------------------------→|  Cierre normal (1000)

Protocolo de mensajesPermalink for this section

Cliente → ServidorPermalink for this section

subscribe — Establece o actualiza canales y filtros. Se envía automáticamente en la conexión si se pasa como parámetros de consulta.

{
  "type": "subscribe",
  "channels": ["ev", "odds"],
  "filters": {
    "sports": ["basketball"],
    "sportsbooks": ["draftkings", "fanduel"],
    "leagues": ["nba"],
    "markets": ["moneyline", "player_points"],
    "eventIds": ["32825-35775-2026-02-08"],
    "min_ev": 3.0,
    "min_profit": 1.5
  }
}

ping — Keepalive. Envía cada 25 segundos para evitar timeouts.

{ "type": "ping" }

resyncPermalink for this section

{ "type": "resync", "channels": ["odds"] }

Reenvía el snapshot inicial para los canales a los que ya está suscrito, en el socket abierto. Sus suscripciones y filtros permanecen intactos, por lo que no se pierde ninguna actualización en el intervalo entre cancelar y volver a suscribirse.

• Confirmado con resync:started, seguido de la misma secuencia de snapshot que produce una nueva suscripción.
• Solo se aceptan canales ya suscritos — esto no es una suscripción encubierta. Nombrar cualquier canal que no tenga rechaza todo el mensaje con channel_not_subscribed.
• Limitado a una por cada 10 segundos por conexión — un rechazo es resync_rate_limited con retry_after_ms, y una solicitud en curso es resync_in_progress. Un volcado de snapshot es costoso; un volcado ilimitado impulsado por el cliente sería una denegación de servicio autoinfligida.
• La compatibilidad se anuncia como features.client_resync en el ack connected — detéctela allí en lugar de sondearlo.

resync_required es la señal separada de servidor a cliente descrita en Resincronización Completa; nunca la reenvíe al servidor.

Servidor → ClientePermalink for this section

connectedPermalink for this section

Se envía inmediatamente tras una autenticación exitosa.

{
  "type": "connected",
  "seq": 12847,
  "message": "Welcome to SharpAPI real-time odds stream",
  "stream_id": "ws_mle3husw_ezoyvp",
  "tier": "pro",
  "features": { "ev": true, "arbitrage": true, "middles": true, "low_hold": true },
  "channels": ["ev", "odds"],
  "global_seq": "12847",
  "books": { "max": -1, "allowed": null },
  "streams": { "max": 1, "active": 1 },
  "heartbeat_interval_ms": 30000,
  "pong_timeout_ms": 120000,
  "timestamp": "2026-02-08T18:47:17.559Z"
}

Cuando se rechaza un resume solicitado, ese mismo frame informa el desenlace explícito:

{
  "type": "connected",
  "global_seq": "12847",
  "resumed": false,
  "fallback_reason": "seq_too_old"
}

subscribedPermalink for this section

Confirma tus canales y filtros activos.

{
  "type": "subscribed",
  "channels": ["ev", "odds"],
  "sports": ["basketball"],
  "sportsbooks": ["draftkings", "fanduel"],
  "leagues": ["nba"],
  "markets": null,
  "eventIds": null,
  "min_ev": 3.0,
  "min_profit": 1.5,
  "timestamp": "2026-02-08T18:47:17.561Z"
}

opportunities_snapshotPermalink for this section

Snapshot de oportunidades para un único tipo de canal. Se envía una vez por canal de oportunidades suscrito durante la carga inicial de datos. Solo incluye el tipo de oportunidad al que te has suscrito.

{
  "type": "opportunities_snapshot",
  "ev": [
    {
      "id": "a1b2c3d4e5f6",
      "game_id": "nba_indianapacers_torontoraptors_2026-02-08",
      "ev_percentage": 4.35,
      "odds_american": -110,
      "odds_decimal": 1.909,
      "no_vig_odds": -101,
      "selection": "Tyrese Haliburton Over 22.5",
      "market": "player_points",
      "line": 22.5,
      "sportsbook": "draftkings",
      "game": "Indiana Pacers @ Toronto Raptors",
      "sport": "basketball",
      "league": "nba",
      "home_team": "Toronto Raptors",
      "away_team": "Indiana Pacers",
      "start_time": "2026-02-08T19:00:00.000Z",
      "is_live": false,
      "confidence_score": 72,
      "kelly_percent": 3.8,
      "book_count": 4,
      "detected_at": "2026-02-08T18:47:20.000Z"
    }
  ],
  "timestamp": "2026-02-08T18:47:17.700Z"
}

La clave de nivel superior coincide con el tipo de canal: ev, arbitrage, middles o low_hold. Cada mensaje de snapshot contiene solo un tipo. Los snapshots grandes se fragmentan automáticamente — cuando esto ocurre, los mensajes incluyen los campos chunk y totalChunks.

initialPermalink for this section

Snapshot de cuotas por sportsbook. Se envía una vez por sportsbook cuando el canal odds está suscrito. Requiere el canal odds.

{
  "type": "initial",
  "source": "draftkings",
  "data": [ /* NormalizedOdds[] */ ],
  "count": 1500,
  "timestamp": "2026-02-08T18:47:17.800Z"
}

snapshot:completePermalink for this section

Indica el final de un snapshot inicial, de un fallback de full resync o de un replay exitoso. Es seguro ocultar los estados de carga tras recibirlo. Un snapshot completo lleva books y total_odds. Cuando se rechaza un resume solicitado, lleva además mode: "full_resync" y el mismo fallback_reason que informó connected:

{
  "type": "snapshot:complete",
  "books": ["draftkings", "fanduel", "pinnacle"],
  "total_odds": 2841,
  "mode": "full_resync",
  "fallback_reason": "seq_too_old"
}

Un replay normal o consolidado aceptado tiene otra forma de finalización:

{
  "type": "snapshot:complete",
  "mode": "resume",
  "replayed_count": 127,
  "skipped_count": 3,
  "last_seq": "12974",
  "gap_detected": false
}

Un snapshot nuevo ordinario omite mode y fallback_reason. La aceptación del replay la informa el frame connected anterior, no este frame de finalización.

odds:updatePermalink for this section

Actualización incremental de cuotas desde un único sportsbook.

{
  "type": "odds:update",
  "seq": 46,
  "source": "draftkings",
  "data": [ /* NormalizedOdds[] */ ],
  "count": 23,
  "timestamp": "2026-02-08T18:47:19.123Z"
}

odds:removedPermalink for this section

Cuotas eliminadas por un sportsbook (p. ej. mercado retirado, evento finalizado).

{
  "type": "odds:removed",
  "seq": 47,
  "source": "draftkings",
  "ids": ["odd_id_1", "odd_id_2"],
  "count": 2,
  "timestamp": "2026-02-08T18:47:19.200Z"
}

ev:detectedPermalink for this section

Nueva oportunidad +EV, o una versión actualizada de una ya enviada (mismo id). Solo plan Pro o superior.

{
  "type": "ev:detected",
  "seq": 48,
  "data": [
    {
      "id": "a1b2c3d4e5f6",
      "game_id": "nba_indianapacers_torontoraptors_2026-02-08",
      "ev_percentage": 4.35,
      "odds_american": -110,
      "odds_decimal": 1.909,
      "no_vig_odds": -101,
      "selection": "Tyrese Haliburton Over 22.5",
      "market": "player_points",
      "line": 22.5,
      "sportsbook": "draftkings",
      "game": "Indiana Pacers @ Toronto Raptors",
      "sport": "basketball",
      "league": "nba",
      "home_team": "Toronto Raptors",
      "away_team": "Indiana Pacers",
      "start_time": "2026-02-08T19:00:00.000Z",
      "is_live": false,
      "confidence_score": 72,
      "kelly_percent": 3.8,
      "book_count": 4,
      "detected_at": "2026-02-08T18:47:20.000Z"
    }
  ],
  "timestamp": "2026-02-08T18:47:20.000Z"
}

ev:expiredPermalink for this section

Una oportunidad +EV detectada anteriormente ya no está disponible.

{
  "type": "ev:expired",
  "seq": 49,
  "data": {
    "expired": [
      "32825-35775-2026-02-08:draftkings:Tyrese Haliburton Over 22.5"
    ]
  },
  "timestamp": "2026-02-08T18:47:25.000Z"
}

arb:detectedPermalink for this section

Nueva oportunidad de arbitraje, o una versión actualizada de una ya enviada (mismo id). Solo plan Hobby o superior.

{
  "type": "arb:detected",
  "seq": 50,
  "data": [
    {
      "id": "61c501b83ce932d1",
      "event_id": "nba_indianapacers_torontoraptors_2026-02-08",
      "event_name": "Indiana Pacers @ Toronto Raptors",
      "sport": "basketball",
      "league": "nba",
      "market_type": "moneyline",
      "line": null,
      "profit_percent": 2.8,
      "implied_total": 97.2,
      "is_live": false,
      "legs": [
        {
          "sportsbook": "draftkings",
          "selection": "Indiana Pacers",
          "odds_american": 125,
          "odds_decimal": 2.25,
          "implied_probability": 0.4444,
          "stake_percent": 52.8
        },
        {
          "sportsbook": "fanduel",
          "selection": "Toronto Raptors",
          "odds_american": -110,
          "odds_decimal": 1.909,
          "implied_probability": 0.5238,
          "stake_percent": 47.2
        }
      ],
      "detected_at": "2026-02-08T18:47:21.000Z"
    }
  ],
  "timestamp": "2026-02-08T18:47:21.000Z"
}

arb:expiredPermalink for this section

Una oportunidad de arbitraje detectada anteriormente ya no está disponible.

{
  "type": "arb:expired",
  "seq": 51,
  "data": {
    "expired": [
      "32825-35775-2026-02-08:moneyline"
    ]
  },
  "timestamp": "2026-02-08T18:47:26.000Z"
}

middles:detectedPermalink for this section

Nueva oportunidad de middle, o una versión actualizada de una ya enviada (mismo id). Requiere el canal middles.

{
  "type": "middles:detected",
  "seq": 52,
  "data": [
    {
      "id": "abc123",
      "event_id": "nba_indianapacers_torontoraptors_2026-02-08",
      "event_name": "Indiana Pacers @ Toronto Raptors",
      "sport": "basketball",
      "league": "nba",
      "market_type": "player_points",
      "side1": {
        "book": "draftkings",
        "selection": "Over 22.5",
        "line": 22.5,
        "odds": { "american": -110, "decimal": 1.909, "probability": 0.5238, "fair_probability": 0.51 },
        "stake_percent": 50,
        "odds_age_seconds": 3.2,
        "deep_link": null
      },
      "side2": {
        "book": "fanduel",
        "selection": "Under 23.5",
        "line": 23.5,
        "odds": { "american": -105, "decimal": 1.952, "probability": 0.5122, "fair_probability": 0.49 },
        "stake_percent": 50,
        "odds_age_seconds": 1.8,
        "deep_link": null
      },
      "middle_size": 1,
      "middle_numbers": [23],
      "middle_probability": 0.12,
      "expected_value": 3.5,
      "roi_percentage": 4.2,
      "quality_score": 85,
      "detected_at": "2026-02-08T18:47:22.000Z"
    }
  ],
  "timestamp": "2026-02-08T18:47:22.000Z"
}

middles:expiredPermalink for this section

Una oportunidad de middle detectada anteriormente ya no está disponible.

{
  "type": "middles:expired",
  "seq": 53,
  "data": {
    "expired": ["abc123"]
  },
  "timestamp": "2026-02-08T18:47:27.000Z"
}

low_hold:detectedPermalink for this section

Nueva oportunidad de low-hold, o una versión actualizada de una ya enviada (mismo id). Requiere el canal low_hold.

{
  "type": "low_hold:detected",
  "seq": 54,
  "data": [
    {
      "id": "def456",
      "event_id": "nba_indianapacers_torontoraptors_2026-02-08",
      "event_name": "Indiana Pacers @ Toronto Raptors",
      "sport": "basketball",
      "league": "nba",
      "market_type": "moneyline",
      "line": null,
      "home_team": "Toronto Raptors",
      "away_team": "Indiana Pacers",
      "start_time": "2026-02-08T19:00:00.000Z",
      "hold_percentage": 1.2,
      "is_live": false,
      "all_books": ["draftkings", "fanduel"],
      "side1": {
        "selection": "Indiana Pacers",
        "books": ["draftkings"],
        "line": null,
        "odds": { "american": -108, "decimal": 1.926, "implied_probability": 0.5192, "fair_probability": 0.5096 },
        "deep_links": { "draftkings": "https://sportsbook.draftkings.com/event/..." }
      },
      "side2": {
        "selection": "Toronto Raptors",
        "books": ["fanduel"],
        "line": null,
        "odds": { "american": 110, "decimal": 2.1, "implied_probability": 0.4762, "fair_probability": 0.4904 },
        "deep_links": { "fanduel": "https://sportsbook.fanduel.com/event/..." }
      },
      "detected_at": "2026-02-08T18:47:22.000Z"
    }
  ],
  "timestamp": "2026-02-08T18:47:22.000Z"
}

low_hold:expiredPermalink for this section

Una oportunidad de low-hold detectada anteriormente ya no está disponible.

{
  "type": "low_hold:expired",
  "seq": 55,
  "data": {
    "expired": ["def456"]
  },
  "timestamp": "2026-02-08T18:47:28.000Z"
}

heartbeatPermalink for this section

Un frame de liveness a nivel de aplicación, enviado en una cadencia fija a cada conexión autenticada independientemente de la actividad del mercado — sigue llegando en un libro nocturno tranquilo. Su intervalo se anuncia como heartbeat_interval_ms en el ack connected (30 s hoy).

{
  "type": "heartbeat",
  "seq": 150,
  "global_seq": "150",
  "timestamp": "2026-02-08T18:48:17.559Z"
}

Lleva el valor de secuencia actual, lo que lo hace útil más allá de la liveness. Léalo como una verificación bilateral en lugar de una regla de una línea, ya que es un único contador compartido por cada canal y libro en la instancia del servidor a la que está conectado:

• Que avance no significa que sus datos estén fluyendo. Se mueve cuando cualquier libro emite contenido, por lo que no puede revelar un estancamiento en un único libro — un libro silencioso mientras los demás transmiten mantiene el contador subiendo.
• Que se detenga no siempre significa que algo está roto. Es igualmente plano en una pizarra genuinamente tranquila, como un partido nocturno donde nada se mueve.

Trate un global_seq plano como señal de estancamiento solo cuando sus propias filas también estén desactualizadas y espere actividad. Reconectarse solo por un contador plano vuelca un snapshot completo en un mercado tranquilo — la espiral descrita a continuación. Para liveness por libro, rastree cuándo recibió por última vez una fila para cada libro que le importa: el frame heartbeat de WebSocket no lleva marcas de tiempo por libro.

Esta es solo una señal de estancamiento, nunca un punto de control de reconexión — vea Reconexión con Replay para el recibo seguro.

watchdog_ms = min(3 * heartbeat_interval_ms, pong_timeout_ms - heartbeat_interval_ms)

pongPermalink for this section

Respuesta a un ping del cliente.

{
  "type": "pong",
  "timestamp": "2026-02-08T18:47:42.000Z"
}

errorPermalink for this section

Notificación de error. La conexión puede permanecer abierta (para errores no fatales) o cerrarse (para errores de autenticación/límite).

{
  "type": "error",
  "code": "unknown_message_type",
  "message": "Unknown message type: foobar"
}

La capa WebSocket emite un conjunto pequeño y fijo de códigos de error a nivel de frame para errores de protocolo del cliente. Son distintos de los códigos de error HTTP devueltos por los endpoints REST.

Los frames WebSocket también pueden transportar los códigos al estilo HTTP invalid_api_key, tier_restricted y too_many_streams — estos hacen que el servidor cierre la conexión después de enviar el frame. Consulta Visión general de la API → Códigos de error para la lista completa.

Códigos de cierrePermalink for this section

Números de secuenciaPermalink for this section

global_seq es un checkpoint de cadena decimal seguro para JavaScript para el replay de reconexión de mejor esfuerzo. Los frames de datos reproducibles también pueden llevar seq, el mismo checkpoint global de proceso en una representación entera heredada. Estos valores no son contadores por conexión y no son contiguos para un suscriptor filtrado: los frames de otros canales, libros y suscriptores también consumen valores.

Las brechas numéricas observadas, por tanto, no indican pérdida o un mensaje descartado. Reacciona a las señales de recuperación explícitas — resync_required, gap_detected y un resume rechazado — en lugar de requerir continuidad N+1. Los frames de snapshot y control no contienen uniformemente ninguno de los campos de secuencia. Los datos reproducidos conservan su checkpoint original y añaden "replay": true.

La entrega entre libros también puede reordenar los valores globales del proceso, por lo que un cliente puede observar 101 antes de 100. Nunca calcules un checkpoint de reconexión a partir del último valor observado, un máximo acumulado, máximos por fuente o continuidad aparente. No existe ningún checkpoint calculable por el cliente que avance entre los recibos emitidos por el servidor.

Reconexión con ReplayPermalink for this section

Para una desconexión breve, reconecta con los mismos canales y filtros más el último recibo del servidor confirmado. from_seq solo solicita un replay local al proceso de mejor esfuerzo:

wss://ws.sharpapi.io?api_key=YOUR_KEY&channels=ev,odds&sport=basketball&sportsbook=draftkings,fanduel&league=nba&from_seq=12900

Cuando se acepta, connected incluye "resumed": true; los frames reproducidos están marcados con "replay": true, y la fase de replay termina con snapshot:complete en "mode": "resume". La recepción del last_seq de ese frame de finalización es lo que hace avanzar el checkpoint seguro. connected.global_seq en un resume aceptado describe el fin previsto del replay, no la prueba de que todos los frames de replay llegaron al cliente. Un replay normal envía los frames elegibles estrictamente después de from_seq en orden de buffer y recupera los frames que llegaron durante ese recorrido. Una brecha amplia solo de cuotas puede consolidarse en cambio al estado actual de filas modificadas en lugar de cada transición intermedia. Si la consolidación no es elegible o supera su límite de envío, el servidor recurre explícitamente a un snapshot completo; no trunca el replay silenciosamente. Aplica actualizaciones y eliminaciones de forma idempotente.

Cuando el checkpoint no puede ser respetado, el resultado es explícito: connected incluye "resumed": false y "fallback_reason", seguido de snapshots autoritativos y snapshot:complete con "mode": "full_resync". Los motivos actuales incluyen parse_error, foreign_seq, process_restarted, seq_too_old, gap_too_large y disabled.

Si un replay comienza pero después termina con "gap_detected": true, descarta el checkpoint almacenado y reconcilia mediante REST u obtén un snapshot nuevo reconectando sin from_seq. La conexión nueva envía un nuevo snapshot autoritativo.

from_seq es una optimización de latencia sobre el buffer de replay corto, no un mecanismo de completitud. No existe ningún checkpoint calculable por el cliente que avance entre los recibos del servidor. Usa un snapshot completo o reconciliación REST cuando el estado completo sea importante.

let resumeCheckpoint;
let pendingSnapshotFloor;
 
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
 
  if (msg.type === 'connected') {
    // Un piso fresco/de resincronización completa solo es seguro tras completar su snapshot.
    pendingSnapshotFloor = msg.resumed === true ? undefined : msg.global_seq;
  }
 
  if (msg.type === 'snapshot:complete' && msg.mode === 'resume') {
    if (msg.gap_detected) {
      // El servidor declaró este recorrido con hueco: el checkpoint no es reutilizable.
      resumeCheckpoint = undefined;
      reconcileThroughRestOrRequestFreshSnapshot();
    } else {
      // Recibo del servidor: todos los frames de replay antes de este límite fueron entregados.
      resumeCheckpoint = msg.last_seq;
    }
    pendingSnapshotFloor = undefined;
  } else if (
    msg.type === 'snapshot:complete' &&
    (msg.mode === 'full_resync' || msg.mode === undefined) &&
    pendingSnapshotFloor
  ) {
    // La línea base autoritativa fresca/completa ahora está terminada.
    resumeCheckpoint = pendingSnapshotFloor;
    pendingSnapshotFloor = undefined;
  }
 
  if (msg.replay) {
    console.log('Replayed event:', msg.type);
  }
};
 
// On reconnect:
function reconnect() {
  const params = new URLSearchParams({
    api_key: 'YOUR_KEY',
    channels: 'ev,odds'
  });
  if (resumeCheckpoint) params.set('from_seq', resumeCheckpoint);
  ws = new WebSocket(`wss://ws.sharpapi.io?${params}`);
}

Resincronización CompletaPermalink for this section

Use cualquiera de los tres métodos de snapshot fresco admitidos:

1. Reconéctese sin from_seq, luego restaure los canales y filtros previstos en la URL de conexión o en los mensajes de suscripción. La nueva conexión envía un snapshot completo inmediatamente después de la autenticación.
2. Cancele la suscripción al canal afectado y vuelva a suscribirse. La transición hace que el canal sea nuevo y envía un snapshot fresco.
3. Envíe resync con los canales afectados en el socket abierto — la suscripción nunca se interrumpe, por lo que nada se pierde en una ventana de cancelación. Vea resync.

Un subscribe duplicado o una actualización solo de filtros no activa un snapshot.

El servidor envía resync_required cuando la contrapresión descarta deltas en vivo:

{
  "type": "resync_required",
  "reason": "backpressure",
  "dropped": 54,
  "message": "Deltas were dropped due to slow consumption. Request /api/v1/odds for a full snapshot or reconnect."
}

dropped es el número de frames descartados para su conexión desde el resync_required anterior — no un total de por vida, y no una cifra de toda la flota. Está ahí para que pueda dimensionar la brecha: unos pocos frames en un mercado tranquilo es una decisión diferente a varios cientos en medio de una pizarra activa.

El frame solo se envía cuando ese recuento es mayor que cero, por lo que recibirlo siempre significa pérdida real. Recupérese conciliando a través de REST o usando cualquier método de snapshot fresco anterior; no reenvíe resync_required al servidor.

Ejemplos de códigoPermalink for this section

// Subscribe to EV opportunities + odds only (skip middles, low_hold, arbitrage)
const ws = new WebSocket(
  'wss://ws.sharpapi.io?api_key=YOUR_KEY&channels=ev,odds&sport=basketball&league=nba'
);
 
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
 
  switch (msg.type) {
    case 'connected':
      console.log(msg.message, '| tier:', msg.tier, '| channels:', msg.channels);
      break;
    case 'subscribed':
      console.log('Channels:', msg.channels, '| Filters:', msg.sportsbooks, msg.leagues);
      break;
    case 'opportunities_snapshot':
      if (msg.ev) console.log(`EV snapshot: ${msg.ev.length} opportunities`);
      break;
    case 'initial':
      const books = Object.keys(msg.data);
      console.log(`Odds snapshot: ${books.length} books`);
      break;
    case 'snapshot:complete':
      console.log('All initial data received');
      break;
    case 'odds:update':
      console.log(`${msg.source}: ${msg.data.length} odds updated`);
      break;
    case 'ev:detected':
      msg.data.forEach(ev =>
        console.log(`+EV: ${ev.selection} at ${ev.ev_percentage}%`)
      );
      break;
    case 'heartbeat':
      break; // silent keepalive
  }
};
 
ws.onclose = (event) => {
  console.log(`Closed: ${event.code} ${event.reason}`);
};
 
// Send ping every 25s to keep alive
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 25000);
 
// Update channels and filters without reconnecting
function updateSubscription(channels, { sports, sportsbooks, leagues } = {}) {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels,
    filters: { sports, sportsbooks, leagues }
  }));
}

import WebSocket from 'ws';
 
// Subscribe to low-hold only — no odds dump, no EV/arb/middles
const ws = new WebSocket(
  'wss://ws.sharpapi.io?api_key=YOUR_KEY&channels=low_hold'
);
 
ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
 
  if (msg.type === 'connected') {
    console.log(msg.message);
    console.log('Tier:', msg.tier, '| Channels:', msg.channels);
  }
  else if (msg.type === 'opportunities_snapshot' && msg.low_hold) {
    console.log(`Low-hold snapshot: ${msg.low_hold.length} opportunities`);
  }
  else if (msg.type === 'snapshot:complete') {
    console.log('Initial data complete');
  }
  else if (msg.type === 'low_hold:detected') {
    console.log(`+${msg.data.length} low-hold opportunities`);
  }
  else if (msg.type === 'low_hold:expired') {
    console.log(`-${msg.data.expired.length} low-hold expired`);
  }
});
 
ws.on('close', (code, reason) => {
  console.log(`Closed: ${code} ${reason}`);
  if (code !== 1000 && !(code === 4001 && String(reason).includes('displaced'))) {
    // Reconnect logic here
  }
});
 
// Keepalive
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }));
  }
}, 25000);

import json
import websocket
import threading
import time
 
API_KEY = "YOUR_KEY"
# Subscribe to middles channel only
URL = f"wss://ws.sharpapi.io?api_key={API_KEY}&channels=middles&league=nba"
 
def on_message(ws, raw):
    msg = json.loads(raw)
    msg_type = msg["type"]
 
    if msg_type == "connected":
        print(f'{msg["message"]} | tier: {msg["tier"]} | channels: {msg["channels"]}')
    elif msg_type == "opportunities_snapshot" and "middles" in msg:
        print(f'Middles snapshot: {len(msg["middles"])} opportunities')
    elif msg_type == "snapshot:complete":
        print("Initial data complete")
    elif msg_type == "middles:detected":
        for m in msg["data"]:
            print(f'Middle: {m["event_name"]} — EV {m.get("expected_value", "?")}%')
    elif msg_type == "middles:expired":
        print(f'Expired: {len(msg["data"]["expired"])} middles')
    elif msg_type == "heartbeat":
        pass  # silent keepalive
 
def on_close(ws, code, reason):
    print(f"Closed: {code} {reason}")
 
def on_open(ws):
    # Start ping thread
    def ping():
        while ws.sock and ws.sock.connected:
            ws.send(json.dumps({"type": "ping"}))
            time.sleep(25)
    threading.Thread(target=ping, daemon=True).start()
 
ws = websocket.WebSocketApp(URL,
    on_message=on_message,
    on_close=on_close,
    on_open=on_open)
 
ws.run_forever()

import { SharpAPI } from '@sharpapi/client';
 
const api = new SharpAPI('YOUR_KEY');
 
const stream = api.stream.oddsWs({
  channels: ['ev', 'odds'],
  sport: ['basketball'],
  sportsbook: ['draftkings', 'fanduel'],
  league: ['nba'],
});
 
stream.on('connected', ({ message, tier, channels }) => {
  console.log(message, '| tier:', tier, '| channels:', channels);
});
 
stream.on('opportunities_snapshot', ({ ev, arbitrage, middles, low_hold }) => {
  if (ev) console.log(`EV snapshot: ${ev.length}`);
  if (low_hold) console.log(`Low-hold snapshot: ${low_hold.length}`);
});
 
stream.on('snapshot:complete', () => {
  console.log('All initial data received');
});
 
stream.on('odds:update', ({ data, source }) => {
  console.log(`${source}: ${data.length} odds updated`);
});
 
stream.on('ev:detected', ({ data }) => {
  data.forEach(ev =>
    console.log(`+EV: ${ev.selection} at ${ev.ev_percentage}%`)
  );
});
 
stream.on('error', ({ message }) => {
  console.error('Error:', message);
});
 
stream.connect();
 
// Update channels and filters later without reconnecting
stream.updateSubscription({
  channels: ['low_hold'],
  sports: ['football'],
  sportsbooks: ['pinnacle'],
  leagues: ['nfl'],
});
 
// Disconnect when done
// stream.disconnect();

Límites de streams concurrentesPermalink for this section

El límite es por clave de API y se comparte entre WebSocket y SSE. No es por URL de conexión: un segundo socket con canales distintos no obtiene su propio slot.

Streams Concurrentes AdicionalesPermalink for this section

Ejecutar más de un socket simultáneo sobre una sola clave — un par de failover hot/warm, o una conexión por worker en tu propia flota — es un aumento de capacidad aprovisionado sobre tu clave (un override maxStreams por clave), no un cambio de código de tu lado. Es un add-on de pago en cualquier plan de pago — contacta con ventas indicando cuántos streams necesitas; surte efecto en tu siguiente conexión, sin rotación de clave y sin redespliegue.

Confirma lo que te concedieron leyendo streams.max en el ack de connected — informa del límite que realmente se aplica, así nunca tienes que deducir tu límite a partir de un desplazamiento:

"streams": { "max": 4, "active": 2 }

Acuñar una clave separada por proceso es la alternativa y no necesita aprovisionamiento — cada clave lleva su propio slot.

Buenas prácticasPermalink for this section

1. Usa canales — Suscríbete solo a los datos que necesitas. channels=low_hold omite todo el volcado de cuotas y otros tipos de oportunidades, reduciendo el payload inicial de megabytes a kilobytes
2. Envía pings cada 25 segundos — El servidor envía heartbeats cada 30s, pero los pings explícitos previenen los timeouts de proxy/firewall
3. Usa filtros — Pasa los parámetros sport, sportsbook, league, market y event_id para acotar los datos dentro de tus canales suscritos
4. Define umbrales — Usa min_ev y min_profit para filtrar las oportunidades de bajo valor en el servidor, reduciendo el ruido
5. Actualiza vía subscribe — Cambia canales, filtros y umbrales sin reconectar
6. Maneja los códigos de cierre — 4001 significa clave incorrecta o desplazamiento por una sesión más reciente (distínguelos por el motivo de cierre), 4003 significa que los permisos cambiaron durante el stream (bajada de plan, clave revocada, complemento eliminado) — reconecta para reautorizar, tras comprobar que el plan aún lo permite
7. Realiza seguimiento de los recibos del servidor — Confirma snapshot:complete.last_seq tras un resume exitoso, o el piso connected.global_seq pendiente solo después de que su snapshot fresco/completo termine; nunca derives from_seq de datos arbitrarios o frames de heartbeat
8. Implementa la reconexión — A diferencia de SSE, WebSocket no se reconecta automáticamente. Usa retroceso exponencial (1s, 2s, 4s, …) con replay de from_seq para cortes breves
9. Espera a snapshot:complete — Esto indica que se han enviado todos los datos iniciales. Oculta los estados de carga después de recibirlo
10. Maneja odds:removed — Elimina las cuotas de tu estado local cuando recibas este mensaje para evitar mostrar datos obsoletos
11. Cierra las conexiones no utilizadas — Cada clave permite 1 stream concurrente por defecto; una segunda conexión con la misma clave desplaza a la más antigua (cierre 4001)

RelacionadoPermalink for this section

• Referencia de la API SSE Stream — Alternativa con Server-Sent Events
• Visión general del streaming — Conceptos y comparativa
• Guía de streaming WebSocket — Guía de inicio