Resumen
Si buscaste la documentación de la API de Polymarket, probablemente quieras hacer una de tres cosas: leer datos de mercados y eventos en vivo, transmitir libros de órdenes y operaciones, o colocar y gestionar órdenes mediante programación. Esas tareas las sirven diferentes API, y el camino más rápido es identificar cuál coincide con tu carga de trabajo antes de leer una sola referencia de endpoint.
A alto nivel, la superficie de Polymarket se divide en un lado público de lectura (mercados, eventos, series, libros de órdenes, historial de precios, búsqueda) y un lado autenticado de trading (órdenes, cartera, saldos y flujos WebSocket privados). También existen productos de datos de terceros para casos de uso históricos y analíticos. Cada uno tiene su propia URL base, modelo de autenticación y comportamiento de límite de velocidad, por lo que confundirlos es la fuente más común de confusión.
También hay una capa on-chain. La actividad de Polymarket se liquida en Polygon, lo que significa que los equipos que necesitan verificar liquidaciones, indexar actividad de billeteras o conciliar sus propios registros eventualmente necesitan un endpoint RPC de Polygon junto con las API REST. OnFinality proporciona acceso a la API RPC e infraestructura de nodos dedicados para Polygon y otras redes compatibles cuando tu integración supera los endpoints públicos.
Esta página mapea el panorama de la documentación, muestra cómo elegir la API correcta para tu carga de trabajo y cubre los detalles operativos —claves, paginación, WebSockets y RPC de Polygon— que la documentación de referencia asume que ya conoces.
Puntos clave
- Polymarket expone una API pública de lectura para mercados, eventos y libros de órdenes, y una API autenticada para órdenes, cartera y saldos — comienza decidiendo en qué lado vive tu aplicación.
- Los datos en tiempo real de libros de órdenes y operaciones se entregan a través de flujos WebSocket, que requieren un manejo diferente de reconexión y contrapresión que el sondeo REST.
- Las API de datos de terceros y los SDK pueden acelerar el trabajo analítico, pero debes confirmar la frescura, cobertura y licencias antes de depender de ellos.
- La liquidación de Polymarket ocurre en Polygon, por lo que la mayoría de las integraciones serias también necesitan un endpoint RPC de Polygon confiable para verificación e indexación.
- Trata las claves de API, los límites de paginación y el comportamiento de límite de velocidad como restricciones de diseño, no como algo secundario — dan forma a tu lógica de caché y reintentos.
- Para cargas de trabajo en producción, evalúa RPC gestionado y nodos dedicados según tu volumen de lectura, necesidades de archivo y requisitos de failover.
¿Qué API de Polymarket se ajusta a tu carga de trabajo?
El conjunto de documentación parece grande porque cubre varios productos distintos. Antes de leer las referencias de endpoints, decide qué hace realmente tu aplicación con los datos de Polymarket. Esa única decisión elimina la mayor parte de la documentación.
Usa la siguiente tabla como guía de enrutamiento. No sustituye la referencia oficial, pero te indica qué referencia abrir primero.
- Comienza con la API pública de lectura si estás mostrando datos; elimina la autenticación de tu primer prototipo.
- Agrega la API autenticada solo cuando necesites acciones vinculadas a la cuenta.
- Planifica WebSockets desde el principio si tu interfaz muestra precios en vivo — adaptar la transmisión más tarde es más trabajo que diseñarla desde el inicio.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Leer datos de mercados y eventos | API pública de lectura (mercados, eventos, series, libros de órdenes, historial de precios, búsqueda) | No se necesita clave de API para navegar, por lo que puedes prototipar de inmediato y cachear agresivamente. |
| Colocar o gestionar órdenes | API de trading autenticada con configuración de clave de API | Cada solicitud está vinculada a una cuenta, por lo que el manejo de claves, permisos y errores se vuelven parte de tu diseño. |
| Transmitir precios y operaciones en vivo | Canales WebSocket públicos para libros de órdenes y operaciones | La transmisión evita los costos de sondeo pero requiere lógica de reconexión y cuidado con el orden de los mensajes. |
| Transmitir actualizaciones privadas de la cuenta | Canales WebSocket autenticados para órdenes, posiciones, saldos | Estos canales transportan el estado de la cuenta, por lo que la autenticación y el ciclo de vida de la sesión importan más que el rendimiento bruto. |
| Análisis histórico e investigación | API de datos de terceros y SDK de la comunidad | La cobertura, frecuencia de actualización y términos varían según el proveedor; valida antes de construir un producto sobre ellos. |
| Verificar liquidación on-chain | Endpoint RPC de Polygon para logs, recibos y lecturas de contratos | Las API REST describen el estado de la plataforma; la cadena es la fuente de verdad para liquidación y conciliación. |
API pública de lectura: qué obtienes sin clave
El lado público de la documentación cubre descubrimiento y datos de mercado: listar mercados y eventos, obtener libros de órdenes y mejor oferta/demanda, precios de liquidación, historial de precios y búsqueda de texto completo en eventos y mercados. Como no se requiere clave, este es el lugar correcto para comenzar cualquier integración de solo lectura.
La restricción práctica aquí no es la autenticación sino el volumen. Las listas de mercados y eventos cambian constantemente, y el sondeo ingenuo de listas grandes agotará tu presupuesto de solicitudes. Diseña una capa de caché con valores de tiempo de vida cortos para endpoints de listas y valores más largos para datos históricos, y prefiere flujos WebSocket para cualquier cosa que deba actualizarse en tiempo casi real.
- Cachea los endpoints de listas; son las llamadas de mayor volumen en la mayoría de las aplicaciones de solo lectura.
- Usa la paginación deliberadamente — obtén solo las páginas que tu interfaz realmente renderiza.
- Mantén las consultas de precios históricos separadas de las consultas de precios en vivo para que puedas ajustar cada una de forma independiente.
API de trading autenticada: claves, alcances y manejo de fallos
La API autenticada es donde viven las órdenes, la cartera, los saldos y el poder de compra. Cada solicitud lleva una clave de API, por lo que la página de autenticación de la documentación es lo primero que debes leer — no los endpoints de órdenes. La emisión de claves, la separación de entornos y el alcance de permisos determinan cómo estructuras tu servicio.
Trata las llamadas de trading como operaciones que cambian el estado. Eso significa idempotencia donde la API lo admita, manejo explícito de órdenes rechazadas y parcialmente ejecutadas, y registro que capture identificadores de solicitud para que el soporte pueda rastrear un problema. Nunca incrustes claves en el código del lado del cliente; enruta las llamadas de trading a través de un servicio backend que controles.
- Almacena las claves en un gestor de secretos, no en archivos de entorno comprometidos en un repositorio.
- Separa las credenciales de lectura y escritura si la plataforma lo permite.
- Registra los identificadores de solicitud y respuesta para cada operación de orden — los necesitarás durante la revisión de incidentes.
Flujos WebSocket versus sondeo REST
Tanto el lado público como el autenticado de la plataforma exponen endpoints WebSocket, y elegir entre transmisión y sondeo es una de las mayores decisiones arquitectónicas en una integración de Polymarket. El sondeo es más simple de implementar y más fácil de depurar; la transmisión es más económica a escala y te brinda datos más frescos.
Si transmites, presupuesta tiempo para el trabajo del ciclo de vida de la conexión: reconectar con retroceso exponencial, volver a suscribirse después de reconectar, detectar conexiones inactivas con latidos y manejar mensajes fuera de orden o duplicados en tu reductor de estado. Un flujo que muere silenciosamente es peor que el sondeo, porque tu interfaz sigue mostrando precios obsoletos sin ningún error.
- Agrega una verificación de latido que marque un flujo como no saludable después de una ventana de silencio definida.
- Vuelve a suscribirte explícitamente después de cada reconexión; no asumas que el servidor restaura las suscripciones.
- Mantén un respaldo REST para vistas críticas para que una interrupción del flujo se degrade gracefully.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Frescura de los datos | Transmisión para precios y libros de órdenes; sondeo aceptable para metadatos estáticos | Los precios obsoletos engañan a los usuarios y pueden desencadenar malas decisiones automatizadas. |
| Perfil de costos | La transmisión reduce el volumen de solicitudes; el sondeo escala linealmente con los usuarios | Los presupuestos de solicitudes y el comportamiento de límite de velocidad determinan tu factura de infraestructura. |
| Visibilidad de fallos | Detección de latidos y obsolescencia en flujos | La muerte silenciosa de un flujo es el incidente de producción más común en aplicaciones de transmisión. |
| Complejidad | Lógica de reconexión, resuscripción y deduplicación de mensajes | Subestimar este trabajo es la causa habitual de lanzamientos tardíos. |
Dónde entra en juego el RPC de Polygon
La actividad de Polymarket se liquida en Polygon. Las API REST y WebSocket te dicen lo que reporta la plataforma; la cadena te dice lo que realmente sucedió. Si concilias ejecuciones, verificas transacciones de liquidación, indexas actividad de billeteras o construyes análisis sobre eventos on-chain, necesitas un endpoint RPC de Polygon además de las API de Polymarket.
Para verificación ligera, un endpoint RPC gestionado suele ser suficiente. Para indexación con muchos logs, consultas de archivo en rangos largos o depuración estilo trace, un nodo dedicado te brinda capacidad aislada y comportamiento predecible. OnFinality ofrece tanto acceso a la API RPC como nodos dedicados, y puedes revisar la página de la red Polygon para detalles de endpoints y precios de RPC antes de comprometerte.
- Usa RPC para recibos, logs y lecturas de contratos — no para metadatos de mercado, que la API REST ya proporciona.
- Agrupa y cachea consultas eth_getLogs; los rangos de bloques amplios son la causa más común de tiempos de espera.
- Mantén tu proveedor de RPC separado de tu proveedor de datos para que una interrupción no derribe ambas rutas.
Lista de verificación para producción
Una vez que tu integración funciona en un entorno de pruebas, el trabajo restante es operativo. Usa esta lista de verificación para decidir si estás listo para lanzar y qué decisiones de infraestructura aún deben tomarse.
- Realiza pruebas de carga con paginación realista de listas, no solo con obtenciones de registros individuales.
- Ejecuta un simulacro de fallo: mata un flujo y un endpoint RPC primario y confirma que tu aplicación se degrada limpiamente.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Gestión de claves | Secretos almacenados centralmente, rotados según un calendario, con alcance por servicio | Las claves de trading filtradas son un riesgo financiero directo. |
| Comportamiento de límite de velocidad | Limitación del lado del cliente, reintentos con retroceso exponencial y una cola para tráfico en ráfaga | Los reintentos sin control amplifican las interrupciones en lugar de sobrevivirlas. |
| Salud del flujo | Latidos, alertas de obsolescencia y resuscripción automática | Detecta fallos silenciosos antes de que los usuarios vean precios incorrectos. |
| Verificación on-chain | Endpoint RPC con failover y límites de consulta de logs comprendidos | La conciliación de liquidaciones falla silenciosamente si las llamadas RPC expiran. |
| Observabilidad | Latencia de solicitudes, tasas de error y recuentos de reconexión de flujos en paneles | No puedes depurar lo que no mides. |
| Rutas de respaldo | Respaldo REST para flujos, RPC secundario para lecturas | Mantiene las vistas principales funcionando durante interrupciones parciales. |
Errores comunes de documentación y cómo evitarlos
La mayor parte de la confusión en torno a la documentación de la API de Polymarket proviene de mezclar entornos y productos. La documentación de EE. UU., la documentación internacional y los productos de datos de terceros describen superficies diferentes con diferentes URL base y modelos de autenticación. Copiar un fragmento de una en un proyecto construido para otra es la forma más rápida de obtener un 401 o 404 confuso.
El segundo error es tratar los gists de la comunidad y los envoltorios de SDK como autoritativos. Son útiles para orientarse, pero las rutas de endpoints, los parámetros y los límites pueden cambiar. Confirma cualquier cosa de la que dependas contra la referencia oficial del producto que realmente estás integrando, y fija las versiones de tu SDK para que un cambio upstream no rompa tu compilación de la noche a la mañana.
- Registra de qué producto de documentación proviene cada endpoint en los comentarios de tu código.
- Fija las versiones del SDK y de la biblioteca cliente en tu archivo de bloqueo.
- Vuelve a leer el registro de cambios antes de las versiones principales; las superficies de API evolucionan.
Preguntas frecuentes
¿Existe una API oficial de Polymarket?
Sí. Polymarket publica documentación para una API pública de lectura que cubre mercados, eventos y libros de órdenes, y una API autenticada que cubre órdenes, cartera y datos de cuenta, además de flujos WebSocket para actualizaciones en tiempo real. Siempre confirma los detalles contra la referencia oficial del producto y la región que estás integrando.
¿Necesito una clave de API para leer datos de mercado de Polymarket?
Los endpoints públicos de lectura para mercados, eventos, series, libros de órdenes y búsqueda están diseñados para usarse sin clave de API. Los endpoints autenticados para trading y estado de cuenta requieren configuración de clave. Consulta la documentación actual para conocer los límites que se aplican al tráfico no autenticado.
¿Puedo obtener datos de Polymarket en tiempo real?
Sí, a través de endpoints WebSocket. Los canales públicos transmiten actualizaciones de libros de órdenes y operaciones, mientras que los canales autenticados transmiten cambios privados de órdenes, posiciones y saldos. Planifica la reconexión, resuscripción y detección de obsolescencia desde el principio.
¿Por qué necesitaría un endpoint RPC de Polygon para una integración de Polymarket?
Polymarket liquida en Polygon. Si necesitas verificar transacciones de liquidación, indexar eventos on-chain o conciliar tus propios registros contra la cadena, necesitas acceso RPC a Polygon además de las API REST y WebSocket de Polymarket.
¿Son las API de datos de Polymarket de terceros lo suficientemente confiables para producción?
Pueden ser útiles para análisis histórico e investigación, pero la cobertura, frescura y términos varían según el proveedor. Valida los datos contra la API oficial o los registros on-chain antes de depender de una fuente de terceros para cualquier cosa de cara al usuario.
¿Cómo elijo entre RPC gestionado y un nodo dedicado para Polygon?
Comienza con RPC gestionado si tus necesidades son verificación, búsqueda de recibos y consultas de logs moderadas. Pasa a un nodo dedicado cuando necesites capacidad aislada para rangos de archivo, indexación pesada o rendimiento predecible bajo carga sostenida. Revisa precios de RPC y redes compatibles para comparar opciones.
Ethereum
Solana
Polygon
Base
Arbitrum
BNB Chain
Polkadot
Optimism
