¿Polymarket tiene una API? Guía de arquitectura, acceso e integración

Respuesta directa y alcance

Polymarket sí tiene una API. De hecho, expone múltiples superficies de API según lo que necesites hacer. La API pública (a menudo llamada Gamma API) proporciona metadatos de mercado, listados de eventos e información de precios sin autenticación. La API autenticada (la CLOB API) gestiona la colocación y cancelación de órdenes y las consultas de cartera, y requiere firmas de wallet o credenciales de API. Por separado, dado que Polymarket liquida en Polygon, todas las operaciones y posiciones también son visibles on-chain y se pueden consultar a través de proveedores RPC de propósito general o servicios de indexación.

Esta guía se centra en la arquitectura técnica y el flujo de trabajo de integración. No recomienda un proveedor específico para los endpoints propios de Polymarket, pero sí explica cómo elegir infraestructura RPC para los componentes on-chain. Para recomendaciones concretas de endpoints y proveedores, utiliza el Asistente RPC.

• API pública: descubrimiento de mercados, libros de órdenes, precios y búsqueda.
• API autenticada: trading, gestión de órdenes y datos de cuenta.
• Datos on-chain: operaciones, posiciones y liquidaciones en Polygon.
• El acceso puede estar restringido según la jurisdicción; consulta la documentación oficial para tu región.

Supuestos y requisitos previos

Antes de integrar, necesitas comprender claramente tu caso de uso. ¿Estás construyendo un panel de solo lectura, un bot de trading o un pipeline de analítica? Cada uno requiere una combinación diferente de capas de API e infraestructura. También necesitarás un endpoint RPC de Polygon si planeas interactuar directamente con contratos inteligentes o verificar el estado on-chain. Para cargas de trabajo en producción, se recomienda un nodo dedicado o un proveedor RPC fiable; los endpoints públicos compartidos tienen límites de tasa y no son adecuados para trading.

También deberías estar familiarizado con las API HTTP, JSON y la firma criptográfica básica (EIP-712 para el exchange internacional de Polymarket). Para el exchange regulado en EE. UU., el acceso requiere un proceso de solicitud y KYC, así que planifica el tiempo de incorporación.

• Una URL RPC de Polygon (por ejemplo, de un proveedor o tu propio nodo).
• Una wallet compatible con Ethereum con una clave privada para firmar (nunca la codifiques directamente).
• Credenciales de API si utilizas la CLOB API autenticada.
• Un entorno de desarrollo con curl o un lenguaje de programación de tu elección.

Modelo mental: las tres capas de datos de Polymarket

Piensa en los datos de Polymarket como tres capas concéntricas. La capa más externa es la API pública de datos de mercado, optimizada para el descubrimiento y la visualización. Responde preguntas como "¿qué mercados existen?" y "¿cuál es el precio actual?" sin requerir identidad. La capa intermedia es la API de trading, que requiere autenticación y es con estado: gestiona órdenes, posiciones y saldos. La capa más interna es la propia blockchain, donde cada operación y liquidación se registra como un evento on-chain. Esta capa es inmutable y auditable, pero requiere una conexión RPC para consultarla.

Una integración robusta a menudo combina capas. Por ejemplo, un bot de trading podría usar la API pública para el descubrimiento de mercados, la API autenticada para la colocación de órdenes y llamadas RPC directas para verificar la liquidación o monitorizar la actividad de la wallet. Comprender qué capa es responsable de qué evita llamadas redundantes y mejora la fiabilidad.

API pública: descubrimiento de mercados y precios

La API pública es el punto de entrada más sencillo. Normalmente expone endpoints para listar mercados, obtener libros de órdenes y recuperar el historial de precios. No se requiere clave de API, pero se aplican límites de tasa. La URL base exacta y las rutas de los endpoints dependen de si utilizas la versión internacional o la de EE. UU.; consulta siempre la documentación oficial para el host correcto. El siguiente ejemplo utiliza una URL base de marcador de posición para ilustrar el patrón de solicitud.

curl -s "https://PUBLIC_API_BASE/markets?limit=5" | jq '.data[] | {question, slug, volume}'

API autenticada: trading y gestión de cartera

El trading requiere autenticación. El exchange internacional de Polymarket utiliza un esquema de dos niveles: la autenticación de nivel 1 utiliza una firma EIP-712 de tu wallet para demostrar la propiedad, y el nivel 2 utiliza credenciales de API (clave, secreto, passphrase) para firmar cada solicitud con HMAC. El exchange de EE. UU. utiliza un modelo diferente con claves de API obtenidas después del KYC. En ambos casos, nunca debes exponer claves privadas o secretos de API en el código del lado del cliente.

El siguiente fragmento de Python demuestra cómo podrías estructurar una solicitud firmada utilizando la biblioteca requests y eth_account para firmar. Es ilustrativo y omite el manejo de errores por brevedad.

import requests, time, hmac, hashlib, base64
from eth_account import Account
from eth_account.messages import encode_typed_data

# Placeholders: replace with your own values
PRIVATE_KEY = "YOUR_PRIVATE_KEY"
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"
API_PASSPHRASE = "YOUR_PASSPHRASE"
BASE_URL = "https://AUTHENTICATED_API_BASE"

account = Account.from_key(PRIVATE_KEY)

# Example: sign a message to obtain L2 credentials (simplified)
# In practice, follow the official authentication flow.

def sign_request(method, path, body=""):
    timestamp = str(int(time.time() * 1000))
    message = timestamp + method + path + body
    signature = hmac.new(
        base64.b64decode(API_SECRET),
        message.encode(),
        hashlib.sha256
    ).digest()
    return base64.b64encode(signature).decode()

headers = {
    "POLY_API_KEY": API_KEY,
    "POLY_PASSPHRASE": API_PASSPHRASE,
    "POLY_TIMESTAMP": str(int(time.time() * 1000)),
    "POLY_SIGNATURE": sign_request("GET", "/orders"),
}

resp = requests.get(f"{BASE_URL}/orders", headers=headers)
print(resp.json())

Datos on-chain e infraestructura RPC

Dado que Polymarket se ejecuta en Polygon, cada operación y liquidación es un evento on-chain. Puedes consultar estos eventos directamente utilizando un endpoint RPC de Polygon. Esto es útil para construir analíticas, verificar ejecuciones o monitorizar la actividad de la wallet sin depender de la API de trading. Sin embargo, los endpoints RPC públicos a menudo tienen límites de tasa y pueden no proporcionar los datos históricos que necesitas. Para sistemas en producción, utiliza un nodo dedicado o un servicio RPC gestionado que ofrezca datos de archivo y alto rendimiento.

Al seleccionar un proveedor RPC, considera la latencia de las solicitudes, los límites de tasa, el soporte de archivo y la fiabilidad. OnFinality proporciona endpoints RPC gestionados para Polygon y otras redes; puedes comparar planes en la página de precios. Para una discusión más profunda sobre la arquitectura RPC, consulta la guía de endpoints RPC.

• Utiliza eth_getLogs para consultar eventos de contratos de Polymarket.
• Filtra por dirección de contrato y tema para reducir el volumen de datos.
• Para consultas históricas, asegúrate de que tu proveedor admita datos de archivo.
• Considera suscripciones WebSocket para flujos de operaciones en tiempo real.

curl -s -X POST "YOUR_POLYGON_RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
      "address": "0xCONTRACT_ADDRESS",
      "fromBlock": "0x0",
      "toBlock": "latest",
      "topics": ["0xEVENT_TOPIC"]
    }],
    "id": 1
  }'

Procedimiento de verificación: probar tu integración

Después de configurar tus llamadas a la API, verifica cada capa de forma independiente. Comienza con la API pública: obtén una lista de mercados y confirma que la respuesta contiene los campos esperados. Luego prueba la autenticación llamando a un endpoint autenticado de solo lectura (como /orders) y comprobando que devuelve un estado 200. Finalmente, prueba las consultas on-chain obteniendo el número de bloque más reciente y un registro de eventos conocido. Registra la latencia y la tasa de éxito de cada llamada.

La siguiente tabla describe una matriz de verificación simple. Ejecuta cada prueba tres veces y anota los resultados en tu propio entorno. No confíes en benchmarks inventados; mide con tu infraestructura real.

• API pública: GET /markets devuelve 200 y JSON válido.
• API autenticada: GET /orders con encabezados válidos devuelve 200.
• RPC: eth_blockNumber devuelve una altura de bloque reciente.
• RPC: eth_getLogs para un contrato conocido devuelve los eventos esperados.

Errores comunes y solución de problemas

Los desarrolladores encuentran con frecuencia discrepancias en la documentación, especialmente con la API de EE. UU. Por ejemplo, los parámetros de consulta pueden requerir snake_case en lugar de camelCase, y los filtros de mercados activos pueden devolver eventos obsoletos. Valida siempre las respuestas contra el esquema oficial y prepárate para ajustar los nombres de los campos. El geobloqueo es otro problema común: la API internacional puede ser inaccesible desde ciertas jurisdicciones, y la API de EE. UU. requiere KYC. Si recibes un estado 403 o 451, verifica tu región y el estado de tu cuenta.

El límite de tasa es otro desafío. La API pública tiene límites más estrictos que la API autenticada. Implementa retroceso exponencial y almacena en caché las respuestas cuando sea posible. Para consultas on-chain, agrupa las solicitudes eth_getLogs y utiliza un proveedor con límites generosos. Si encuentras datos inconsistentes entre la API y el estado on-chain, recuerda que la API puede ser eventualmente consistente; la blockchain es la fuente de verdad.

• Verifica el uso de mayúsculas y minúsculas en los parámetros (snake_case vs camelCase).
• Comprueba que tu IP no esté geobloqueada.
• Maneja las respuestas 429 con reintentos y retroceso.
• Utiliza la blockchain para reconciliar discrepancias.

Limitaciones y compensaciones

La API de Polymarket es potente pero no es un almacén de datos de propósito general. La API pública está diseñada para el descubrimiento de mercados, no para análisis históricos masivos. Si necesitas agregación entre mercados o rellenos históricos a largo plazo, es posible que tengas que indexar datos on-chain tú mismo o utilizar un servicio de indexación de terceros. La API autenticada es con estado y está sujeta a tiempos de inactividad; construye mecanismos de respaldo y un manejo de órdenes idempotente.

Las consultas on-chain ofrecen el registro histórico más fiable pero requieren más infraestructura. Debes gestionar conexiones RPC, manejar reorganizaciones y almacenar datos de forma eficiente. Para trading de alta frecuencia, la latencia al endpoint RPC importa; colocar tu infraestructura junto con tu proveedor puede ayudar. En última instancia, la arquitectura correcta depende de tu caso de uso: un panel puede depender de la API pública, mientras que un bot de trading necesita una combinación de API autenticada y RPC dedicado.

Próximos pasos: construir una integración resistente

Comienza prototipando con la API pública para comprender el modelo de datos. Luego, configura un endpoint RPC de Polygon de un proveedor como OnFinality y prueba las consultas on-chain. Una vez que te sientas cómodo, solicita credenciales de API e implementa el flujo de autenticación. Separa siempre tus rutas de lectura y escritura, y monitoriza ambas en busca de errores y latencia.

Para implementaciones en producción, considera usar un nodo dedicado para evitar límites de tasa y garantizar un rendimiento constante. Puedes explorar las ofertas de nodos dedicados de OnFinality y comparar los precios de RPC. Si necesitas ayuda para elegir un proveedor RPC para Polygon, el Asistente RPC puede proporcionar una recomendación breve basada en tus requisitos.

• Prototipa con la API pública y RPC de testnet.
• Implementa la autenticación y el almacenamiento seguro de claves.
• Configura la monitorización de llamadas a la API y RPC.
• Escala con infraestructura dedicada a medida que crezca el volumen.