Polymarket CLI: Guía práctica para datos de mercado y flujos de órdenes desde la terminal

Alcance y el modelo mental detrás de la CLI de Polymarket

La CLI de Polymarket es un binario de Rust publicado por la organización Polymarket. Su propósito declarado es permitirte navegar mercados, colocar órdenes, gestionar posiciones e interactuar con contratos on-chain desde una terminal, o emitir JSON que scripts y agentes puedan consumir. Está etiquetada explícitamente como software experimental y temprano: los comandos, las APIs y el comportamiento pueden cambiar sin previo aviso, y el proyecto advierte contra su uso con grandes cantidades de fondos.

El modelo mental útil tiene tres capas. La primera es una capa de lectura que se comunica con los servicios públicos de mercado y libro de órdenes de Polymarket y no necesita billetera. La segunda es una capa de firma que utiliza una clave privada para autorizar órdenes CLOB y transacciones on-chain. La tercera es una capa de ejecución que envía esas acciones firmadas y devuelve un resultado que debes verificar. Mantener estas capas separadas en tus scripts es la decisión de diseño más importante, porque te permite ejecutar investigación y automatización sin cargar nunca una clave.

Este artículo cubre la instalación, las consultas de solo lectura, los pipelines JSON, la configuración de la billetera, la verificación de órdenes y la solución de problemas. No publica cifras de rendimiento para la CLI ni para ningún proveedor de RPC; cuando la latencia o la fiabilidad importan, el artículo te ofrece un procedimiento de medición en lugar de un resultado afirmado.

• Comandos de solo lectura: listas de mercados, búsquedas, filtros de eventos, consultas de libro de órdenes y precios.
• Comandos de firma: creación de billetera, aprobaciones, colocación de órdenes y cancelación.
• Modos de salida: tablas legibles por humanos por defecto, JSON cuando pasas la bandera de salida.
• Estado: experimental, así que fija versiones y vuelve a probar tras las actualizaciones.

Requisitos previos y supuestos antes de instalar

Necesitas una terminal en macOS o Linux, una forma de instalar binarios (Homebrew o una cadena de herramientas de Rust) y una separación clara entre máquinas de investigación y máquinas de firma. Para operar, necesitas una billetera dedicada con fondos limitados, un endpoint RPC de Polygon que controles o en el que confíes, y el hábito de verificar cada transacción antes de confirmarla.

El orden de configuración documentado de la CLI para la clave privada es: una bandera de línea de comandos, luego una variable de entorno, luego una configuración almacenada. Ese orden importa para la solución de problemas, porque una clave almacenada obsoleta puede anular silenciosamente tu intención si dependes de la configuración interactiva. Prefiere variables de entorno inyectadas por un gestor de secretos en lugar de banderas, ya que las banderas pueden filtrarse en el historial del shell y en los listados de procesos.

Si eres nuevo en la selección de endpoints para la cadena con la que interactúa la CLI, las breves páginas de recomendación del Asistente RPC son el lugar adecuado para elegir un endpoint concreto; esta guía se centra en el flujo de trabajo de la CLI en sí.

• Una dirección de billetera con o sin fondos para consultas de portafolio de solo lectura.
• Una RPC_URL de Polygon de un proveedor que hayas evaluado por fiabilidad.
• Un mecanismo de secretos para PRIVATE_KEY que no sea un archivo de texto plano en una carpeta sincronizada.
• Una versión de la CLI fijada y registrada en tu runbook.

Instalar la CLI con Homebrew, el script de instalación o Cargo

El proyecto documenta tres rutas de instalación: un tap de Homebrew, un script de instalación de shell y la compilación desde el código fuente con Cargo. Homebrew es la opción más auditable en macOS y Linux porque la fórmula está versionada y verificada con checksum. El script de shell es conveniente pero ejecuta contenido remoto, así que léelo antes de ejecutarlo. Compilar desde el código fuente te da el commit exacto que auditaste, que es la opción correcta para cualquier flujo de trabajo que vaya a firmar transacciones.

Después de la instalación, confirma que el binario se resuelve e imprime su salida de ayuda antes de hacer cualquier otra cosa. Esto detecta problemas de PATH y discrepancias de versión desde el principio.

brew tap Polymarket/polymarket-cli
brew install polymarket

# Alternative: build from a pinned commit
git clone https://github.com/Polymarket/polymarket-cli
cd polymarket-cli
git checkout <PINNED_COMMIT>
cargo install --path .

# Verify
polymarket --help
polymarket --version

Investigación de mercado de solo lectura sin billetera

La forma más rápida de validar una instalación es navegar por los mercados, lo que no requiere billetera. Empieza con un límite pequeño para que puedas inspeccionar el formato de la tabla, luego busca por palabra clave y filtra eventos por etiqueta. Estos comandos son seguros de ejecutar en cualquier máquina porque no tocan ninguna clave.

Un bucle de investigación práctico es: listar mercados activos, buscar un tema, obtener un mercado específico por slug y luego extraer datos del libro de órdenes o de precios para los mercados que preseleccionaste. Mantén el límite pequeño mientras exploras; los listados grandes son más difíciles de leer y más lentos de canalizar.

# List a few markets
polymarket markets list --limit 5

# Search by keyword
polymarket markets search "election"

# Filter events by tag
polymarket events list --tag politics

# Fetch one market by slug
polymarket markets get <MARKET_SLUG>

La salida JSON como contrato entre la CLI y tus scripts

La propiedad más valiosa de la CLI para la automatización es que los mismos comandos pueden emitir JSON. Trata ese JSON como un contrato versionado: analiza solo los campos que necesitas, tolera campos desconocidos y falla de forma ruidosa cuando un campo requerido desaparezca tras una actualización. Así es como mantienes vivo un pipeline de investigación a través del ritmo de versiones experimentales.

El siguiente ejemplo canaliza JSON hacia un pequeño filtro de Python. Utiliza solo la biblioteca estándar y un comando de marcador de posición, para que puedas adaptarlo a los campos de mercado que emita tu versión instalada. Lo importante es el patrón: capturar JSON, validar la forma y luego actuar.

import json, subprocess, sys

raw = subprocess.check_output(
    ["polymarket", "-o", "json", "markets", "list", "--limit", "20"],
    text=True,
)
data = json.loads(raw)

# The exact envelope depends on your CLI version; inspect it once, then pin.
markets = data if isinstance(data, list) else data.get("markets", [])
for m in markets:
    slug = m.get("slug") or m.get("question")
    if slug:
        print(slug)

if not markets:
    sys.exit("No markets parsed; check JSON shape after upgrade")

Configuración de la billetera, precedencia de claves y pasos de aprobación

Operar requiere una clave privada para firmar órdenes y transacciones on-chain. La precedencia documentada es: bandera de CLI, luego variable de entorno, luego configuración almacenada. Usa la ruta de la variable de entorno en la automatización y la configuración interactiva solo en una máquina que controles físicamente. Nunca hagas commit de una clave y nunca la pegues en una sesión de terminal compartida.

Antes de colocar cualquier orden, confirma la dirección de billetera que usará la CLI y completa el paso de aprobación que el proyecto documenta para el gasto de tokens. Las aprobaciones son acciones on-chain; verifícalas en un explorador de bloques en lugar de confiar solo en el mensaje de éxito de la CLI.

export POLYMARKET_PRIVATE_KEY=<PRIVATE_KEY>

# Interactive setup (only on a controlled machine)
polymarket setup

# Or create and approve explicitly
polymarket wallet create
polymarket approve set

# Confirm which address is active before trading
polymarket wallet address

Un procedimiento de verificación para mediciones de órdenes y latencia

Dado que la CLI es experimental y las condiciones de red varían, no confíes en un único mensaje de éxito. Construye un pequeño arnés de verificación que registre, para cada intento de orden, la marca de tiempo antes del envío, la marca de tiempo después de que la CLI retorne, el identificador de orden devuelto y el estado on-chain o del libro de órdenes que observes después. Ejecútalo repetidamente con una orden de tamaño de prueba y tabula los resultados.

La siguiente tabla es una plantilla, no datos medidos. Rellénala con tus propias ejecuciones. Si estás comparando endpoints RPC para la ruta de firma, ejecuta el mismo arnés contra cada endpoint y mantén todo lo demás constante.

• Columnas: número de ejecución, etiqueta del endpoint, marca de tiempo de envío, marca de tiempo de retorno, ID de orden presente, estado del libro coincidente, notas.
• Muestra mínima: suficientes ejecuciones para que un valor atípico no domine tu conclusión.
• Control: misma máquina, misma versión de la CLI, mismo tamaño de orden, misma ventana temporal.

Plantilla de tabla de resultados para tus propias ejecuciones

Solución de los fallos que rompen los scripts de trading en terminal

La mayoría de los fallos se agrupan en cuatro categorías: problemas de instalación y PATH, cambios en la forma del JSON tras una actualización, sorpresas de precedencia de claves y lagunas en la verificación de transacciones. Abórdalos en ese orden, porque un binario roto o un sobre JSON cambiado se disfrazarán de problema de trading.

Si un comando que funcionaba ayer ahora falla, revisa primero la versión. Si el análisis JSON se rompe, vuelca la salida sin procesar una vez y compara los nombres de los campos. Si la billetera equivocada firma, imprime la dirección activa y desactiva cualquier configuración almacenada. Si una orden parece tener éxito pero el libro no la refleja, espera y vuelve a consultar en lugar de reenviar, lo que puede duplicar la exposición.

• Comando no encontrado: confirma la ruta de instalación y el PATH del shell.
• Errores de análisis: fija la versión de la CLI y valida explícitamente la forma del JSON.
• Firmante incorrecto: revisa la precedencia de bandera, entorno y configuración almacenada en ese orden.
• Órdenes duplicadas: nunca reintentes a ciegas; consulta el estado primero.
• Fallos de aprobación: verifica las aprobaciones de tokens en un explorador de bloques.

Limitaciones, compensaciones y cuándo no usar la CLI

La CLI es una interfaz ligera y rápida, no un sistema de gestión de riesgos. No reemplaza los límites de posición, los interruptores de emergencia ni el monitoreo independiente. Su estado experimental significa que se esperan cambios disruptivos, por lo que cualquier automatización en producción debe fijar versiones, ejecutarse en un modo de pruebas con órdenes minúsculas y alertar sobre desviaciones en la forma del JSON.

Para ejecución de alta frecuencia o alto valor, un servicio dedicado con semántica de reintentos explícita, claves de idempotencia y registro estructurado suele ser más adecuado que los scripts de shell. La CLI sigue siendo excelente para investigación, consultas ad hoc y pipelines JSON orientados a agentes donde un humano revisa la salida.

Si tu cuello de botella es la fiabilidad del endpoint y no el comportamiento de la CLI, la solución pertenece a tu capa de infraestructura. Revisa la guía de endpoints multicadena y las opciones de nodos dedicados antes de reescribir tus scripts.

Próximos pasos: endurecer tu flujo de trabajo con la CLI de Polymarket

Convierte el bucle de investigación de solo lectura en un trabajo programado que escriba instantáneas JSON en el almacenamiento, luego compara instantáneas consecutivas para detectar cambios en el mercado. Añade el arnés de verificación al mismo repositorio para que el comportamiento de las órdenes y los datos de investigación compartan un único historial de versiones. Registra la versión de la CLI y la etiqueta del endpoint RPC en cada instantánea.

Cuando estés listo para elegir infraestructura, comienza con la guía de endpoints RPC, compara precios para el rendimiento que realmente necesitas y solo entonces pasa a nodos dedicados si tus mediciones lo justifican. Mantén la CLI como la interfaz y tu propio código como la fuente de verdad para los límites y la verificación.

• Fija la versión de la CLI y documenta las pruebas de actualización.
• Almacena instantáneas JSON con marcas de tiempo y etiquetas de endpoint.
• Ejecuta el arnés de verificación de órdenes antes de aumentar el tamaño.
• Separa las máquinas de investigación de las máquinas de firma.