Los mercados de predicción se encuentran entre los dominios más técnicamente exigentes para construir APIs. Se trata de instrumentos financieros que caducan, probabilidades que se cotizan en tiempo real, eventos con múltiples resultados y complejas relaciones de capital, y una base de usuarios que incluye tanto a humanos haciendo clic en una interfaz de usuario como a bots de trading automatizados ejecutando estrategias de arbitraje. Cada decisión de diseño se pone a prueba de inmediato.
Polymarket, actualmente la plataforma de mercados de predicción más grande del mundo por volumen, ha construido un ecosistema de API que vale la pena estudiar precisamente por esta razón. No es solo una API CRUD sobre una base de datos. Es una arquitectura cuidadosamente estructurada que maneja la tensión fundamental entre la apertura y la seguridad, entre los datos en tiempo real e históricos, y entre los patrones financieros tradicionales y las primitivas cripto-nativas.
Aquí hay ocho patrones de diseño que vale la pena extraer de cómo lo han logrado.
Patrón 1: Capas de API Separadas por Dominio
Polymarket expone tres APIs distintas, cada una con un dominio claro:
- Gamma API (
gamma-api.polymarket.com) — descubrimiento de mercados, eventos, etiquetas, búsqueda - CLOB API (
clob.polymarket.com) — datos del libro de órdenes, precios, colocación de órdenes - Data API (
data-api.polymarket.com) — posiciones de usuario, trades, análisis, tablas de clasificación
Esto no es solo una convención de nombres, cada API tiene diferentes requisitos de autenticación, diferentes cadencias de actualización y diferentes perfiles de consumidor. La Gamma API es completamente pública, optimizada para la navegación y el descubrimiento. La CLOB API tiene tanto endpoints públicos (cualquiera puede leer el libro de órdenes) como endpoints autenticados (el trading requiere credenciales). La Data API es pública pero direccionada a la wallet — se consultan posiciones por dirección de usuario.
La lección de diseño aquí es que separar por dominio en lugar de por entidad produce APIs más coherentes. Un enfoque ingenuo le daría /markets, /orders, /users todo bajo un mismo techo. Polymarket, en cambio, pregunta: "¿Para qué sirve esta API?" y luego construye alrededor de esa pregunta. El descubrimiento tiene patrones de acceso diferentes a los del trading. El trading tiene requisitos de latencia diferentes a los del análisis. Dar a cada uno su propia URL base significa que cada uno puede evolucionar, escalar y autenticarse de forma independiente.
Patrón 2: Acceso a Datos Priorizando lo Público
Todo lo relacionado con los datos del mercado —precios, libros de órdenes, metadatos de eventos, trades históricos— es completamente público:
curl "https://gamma-api.polymarket.com/events?limit=5"
Sin clave API. Sin OAuth. Sin muros de límite de tasa en los endpoints de lectura. Se obtienen los datos.
Esta es una elección deliberada que la mayoría de las plataformas financieras no hacen. Los exchanges tradicionales custodian los datos del mercado como una fuente de ingresos. Polymarket los trata como infraestructura — cuanta más gente pueda leer y construir sobre los datos, más líquido y útil se vuelve el mercado. Es la lógica de los bienes públicos aplicada a una API.
La consecuencia práctica para los diseñadores de API es digna de mención: separar el acceso de lectura del acceso de escritura como una preocupación de primera clase, en lugar de aplicar la autenticación de manera uniforme, es casi siempre la decisión correcta para plataformas donde el consumo de datos supera ampliamente la producción de datos. Si un usuario puede leer los precios del mercado sin credenciales, se ha eliminado la fricción para el 95% de su audiencia potencial. Solo se añade fricción en el punto donde realmente importa —cuando quieren realizar una orden real.
Patrón 3: Autenticación de Dos Niveles que Refleja la Confianza Real
Los endpoints de trading requieren autenticación, pero el modelo de autenticación de Polymarket tiene una estructura que la mayoría de los diseñadores de API no han visto antes: dos niveles con propósitos distintos.
La Autenticación L1 utiliza una firma EIP-712 de la clave privada del usuario. Demuestra la propiedad de la wallet. Se usa exactamente una vez (o con poca frecuencia) para derivar credenciales API:
// L1: Use su clave privada para derivar credenciales API
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
La Autenticación L2 utiliza HMAC-SHA256 con esas credenciales derivadas. Es lo que se adjunta a cada solicitud de trading:
// Encabezados L2 en cada solicitud de trading
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
La clave es que las diferentes operaciones merecen diferentes ceremonias de seguridad. La creación de claves API requiere probar el control de la wallet — esa es una acción de alto riesgo que debe exigir una firma criptográfica de la clave privada. Pero una vez que se ha establecido esa confianza, las solicitudes de trading rutinarias no deberían requerir volver a firmar con su clave privada en cada llamada. Las credenciales L2 son lo suficientemente ligeras para un uso de alta frecuencia, al tiempo que siguen estando vinculadas a la identidad L1.
Este patrón se extiende mucho más allá de las criptomonedas: piénselo como la diferencia entre "prueba que eres esta persona" (L1, realizado con poca frecuencia con la credencial más fuerte disponible) y "prueba que esta solicitud proviene de ti" (L2, realizado constantemente con una credencial de sesión). La mayoría de las aplicaciones web colapsan estos en un solo flujo de autenticación y pierden el matiz de seguridad.
Patrón 4: Órdenes como Mensajes Firmados, No Llamadas API
Aquí es donde los mercados de predicción difieren más marcadamente del diseño convencional de APIs. Cuando se coloca una orden en Polymarket, no solo se envían datos a un servidor, sino que se crea un mensaje criptográficamente firmado que es un compromiso financiero exigible:
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
Bajo el capó, el SDK construye una estructura de datos tipada EIP-712, la firma con su clave privada y envía la firma junto con la orden. El motor de emparejamiento opera fuera de la cadena, pero cuando las operaciones se emparejan, se liquidan en la cadena a través de Polygon utilizando esas firmas. El operador no puede fabricar operaciones ni mover fondos — el mensaje firmado es la autorización.
Esto cambia la semántica de lo que significa una "llamada API". Normalmente, enviar a un endpoint significa "por favor, haz esto en mi nombre". Aquí, enviar una orden significa "aquí hay un instrumento firmado que autoriza esta operación". La API no es un intermediario que toma decisiones, es un relé para mensajes criptográficamente auto-autorizados.
Para los diseñadores de API fuera del espacio cripto, la conclusión es esta: cuando la carga útil en sí misma puede llevar la autorización en lugar de depender enteramente de las credenciales de la capa de transporte, se obtiene la no repudiación y la verificabilidad de forma gratuita. Los sistemas financieros, los documentos legales y las operaciones de alto riesgo son todos candidatos para este patrón.
Patrón 5: Ontología Explícita en el Modelo de Datos
Polymarket estructura sus datos en torno a dos objetos: Eventos y Mercados. La distinción importa.
Un Evento es una pregunta: "¿Quién ganará la carrera por el Senado de EE. UU. de 2026 en Pensilvania?" Tiene un título, una categoría, una fecha de resolución. Un Mercado es un resultado binario específico negociable dentro de ese evento: "¿Ganará Bob Casey?" Un evento puede contener muchos mercados.
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
Esto es ontología explícita — la API no solo almacena datos, sino que codifica las relaciones conceptuales entre entidades. Los precios se representan como arrays paralelos donde la posición del índice es la convención de vinculación: outcomes[0] corresponde a outcomePrices[0]. La bandera negRisk a nivel de evento señala que los mercados dentro de él tienen relaciones de capital que no existen en mercados independientes.
La mayoría de las APIs aplanan estas relaciones. Polymarket las expone porque son fundamentales para el funcionamiento del sistema. Si está construyendo un trader automatizado y pasa por alto negRisk: true, construirá el modelo de posición incorrecto y potencialmente perderá dinero. El diseño de la API hace visible la estructura conceptual para que omitirla sea una elección consciente, no un valor predeterminado silencioso.
Patrón 6: NegRisk — Relaciones de Capital como Preocupación de Primera Clase
La bandera negRisk en los eventos apunta a uno de los patrones de diseño de API más interesantes de Polymarket: hacer que las equivalencias financieras sean programables.
En un evento estándar de múltiples resultados, cada mercado es independiente. Pero en un evento NegRisk, donde exactamente un resultado puede ganar, existe una relación matemática entre las posiciones:
1 token "No" en el resultado A ≡ 1 token "Sí" en todos los demás resultados
Esto no es solo matemáticas, está implementado en contratos inteligentes y se expone a través de la API. Cuando se tiene una posición "No" en "Otro" en la carrera por el Senado de Pensilvania, se puede convertir:
| Antes | Después |
|---|---|
| 1× No (Otro) | 1× Sí (Casey) + 1× Sí (McCormick) |
La API lo hace explícito: negRisk: true en el objeto del mercado, y negRisk: true requerido en las opciones de su orden al operar en estos mercados. Si lo hace mal, su orden será rechazada o liquidada incorrectamente.
El patrón de diseño aquí es codificar las invariantes del dominio como campos de API tipados en lugar de dejarlos como notas al pie en la documentación. La bandera NegRisk no existe porque sea conveniente tenerla, existe porque omitirla causa un comportamiento incorrecto. Cuando su dominio tiene restricciones estrictas (solo un resultado puede ganar, las posiciones tienen equivalencias de conversión), esas restricciones deben aparecer en la superficie de la API, no solo en la documentación.
Patrón 7: Tamaño de Tick Dinámico como Estado del Mercado
La mayoría de las APIs financieras tratan el tamaño de tick como una configuración estática. La de Polymarket hace algo más interesante: el tamaño de tick cambia dinámicamente según el precio del mercado, y la API expone esto como un flujo de eventos en tiempo real.
Cuando el precio de un mercado se acerca a los extremos (por encima de 0.96 o por debajo de 0.04), el tamaño de tick mínimo se reduce de 0.01 a 0.001:
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
El razonamiento es intuitivo: en probabilidades extremas, un tick de 1 centavo representa un movimiento del 25% (pasar de 0.04 a 0.03). Esto es demasiado grueso para una determinación significativa del precio. Ticks más finos cerca de los extremos permiten que el mercado exprese probabilidades como el 97.3% en lugar de redondear al 97%.
Lo que hace que esto sea notable como una elección de diseño de API es que el tamaño de tick no es un parámetro que se obtiene una vez — es un estado que cambia y debe ser rastreado. El WebSocket expone eventos tick_size_change precisamente para que los clientes puedan mantener su lógica de construcción de órdenes consistente con el estado actual del mercado. Si codifica el tamaño de tick y omite este evento, sus órdenes serán rechazadas.
Esto refleja un principio más amplio: el diseño de API para sistemas financieros debe abrazar el estado como un concepto de primera clase. Los parámetros del mercado no son estáticos. Las reglas de resolución cambian. Los resultados se aclaran. La API necesita comunicar estas transiciones de estado explícitamente, no dejar que los clientes las descubran a través de solicitudes rechazadas.
Patrón 8: Dos Capas de WebSocket para Diferentes Perfiles de Consumidor
Polymarket utiliza dos sistemas WebSocket separados, y entender por qué revela un patrón sobre la segmentación de la audiencia.
El Canal de Mercado (wss://ws-subscriptions-clob.polymarket.com/ws/market) está diseñado para consumidores de trading. Se suscribe por ID de token, recibe instantáneas del libro de órdenes, cambios de precio, ejecuciones de operaciones y cambios de tamaño de tick. Todo está indexado por ID de activo y optimizado para la construcción de órdenes de baja latencia:
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
El Socket de Datos en Tiempo Real (wss://ws-live-data.polymarket.com) está diseñado para un perfil completamente diferente. Transmite comentarios, precios de criptomonedas de Binance y Chainlink, precios de acciones y eventos de interacción social. Se suscribe por tema:
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
Estos dos sistemas atienden a audiencias con necesidades fundamentalmente diferentes. Un creador de mercado necesita deltas del libro de órdenes relevantes en microsegundos. Una interfaz de usuario que muestre "lo que está sucediendo en Polymarket ahora mismo" necesita feeds de comentarios y actividad social. Combinarlos significaría o bien sobreingenierar el feed social con requisitos de latencia de grado de trading, o subingenierar el feed del libro de órdenes con suposiciones de fiabilidad de grado social.
La lección es simple pero a menudo ignorada: cuando sus consumidores en tiempo real tienen una tolerancia a la latencia, volúmenes de datos y modos de fallo significativamente diferentes, ofrézcales infraestructuras separadas. Los endpoints de WebSocket compartidos que intentan servir múltiples propósitos tienden a colapsar al máximo común denominador para la complejidad y al mínimo común denominador para el rendimiento.
Qué Tienen en Común Estos Patrones
El diseño de la API de Polymarket refleja una filosofía particular: la API debe hacer visible la estructura real del dominio, no abstraerla.
La arquitectura de tres capas se asigna a límites de dominio reales. El acceso público primero refleja cómo funciona el valor del mercado de predicción. La autenticación de dos niveles refleja la diferencia real entre probar una identidad y autorizar una acción. Las órdenes como mensajes firmados codifican la garantía no custodial. La jerarquía Evento/Mercado y la bandera NegRisk exponen relaciones que de otro modo serían invisibles. Los tamaños de tick dinámicos mantienen el estado del cliente consistente con el estado del mercado. Las capas de WebSocket separadas atienden a audiencias separadas.
La mayoría de los consejos de diseño de API se centran en la ergonomía: facilitar las llamadas, ser coherente en el nombramiento, predecible en el manejo de errores. La API de Polymarket hace todo eso, pero las elecciones más interesantes giran en torno a la fidelidad al dominio. Cuando el dominio tiene una distinción significativa, la API la muestra. Cuando el dominio tiene una restricción, la API la aplica. Cuando el dominio tiene un estado que cambia, la API lo difunde.
El resultado es una API que exige más de sus consumidores, pero una en la que acertar significa que realmente se comprende el sistema en el que se está operando. Eso no es una coincidencia — para un mercado de predicción, donde el objetivo principal es que los precios reflejen información, una API que te obliga a comprender la estructura del mercado está haciendo exactamente lo que debería.