Polymarket MCP · 5-minute Up/Down

This repository provides a local Model Context Protocol server for BTC, ETH, SOL, and XRP five-minute Up/Down markets on Polymarket. The connected AI chooses whether to trade; the server validates market data, risk limits, order parameters, persistence, and execution state.

The default mode is paper: public market data is real, but funds are virtual. Live mode signs and submits real CLOB orders using credentials supplied by the operator. Start in paper mode and review the risk controls before enabling live mode.

Highlights

• Paper/live separation with persistent, idempotent order receipts.

• Conservative per-trade, daily, market, asset, and position limits.

• SQLite audit trail for quotes, orders, fills, stops, forecasts, resolutions, observations, and diagnostics.

• Optional user-authorized local stop-limit monitor with process locking and restart recovery.

• Chainlink TWAP observations through Polymarket RTDS, with freshness metadata and no invented history.

• MCP errors with stable codes, isError, correlation IDs, and secret-safe diagnostics.

Related MCP server: polymarket-trader-mcp

Quick start

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m pytest -q

Configure the client with examples/mcp.json or examples/codex.toml. The complete setup, configuration table, stop-loss behavior, database backup, and distribution workflow are documented in the language-specific guides above.

Safety and scope

An automatic stop-loss is a local stop-limit on the Up/Down token. It is not an exchange-hosted guarantee and may fail when the market has no liquidity within the configured limit. The monitor must remain running and connected. This project does not create blockchain approvals, transfer funds, or redeem winning positions.

Current validation: 65 automated tests, public paper smoke test, and Chainlink RTDS smoke test. No real live order is submitted by the test suite.

Documentación detallada en español

English version: README.en.md. Las guías en inglés están junto a cada documento español con el sufijo _en.md.

Servidor MCP local en Python para consultar mercados BTC/ETH/SOL/XRP de cinco minutos, operar en paper o live y guardar la actividad en SQLite. La IA del cliente decide las entradas. Un monitor independiente ejecuta únicamente los stop-loss que el usuario solicite.

Versión 0.2.0. Transporte stdio. Requiere Python 3.11 o posterior. El servidor no necesita una API key de un proveedor de IA. Cada persona configura su propia wallet y base de datos; el paquete distribuible no contiene credenciales.

Instalación rápida

Descomprimir el paquete y abrir una terminal en esa carpeta.

Windows / PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
# Sólo en una instalación nueva: no reemplazar un .env existente.
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m polymarket_mcp --check

Linux / macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
# Sólo si todavía no existe .env:
cp -n .env.example .env
.venv/bin/python -m pytest -q
.venv/bin/python -m polymarket_mcp --check

El ejemplo usa OPERATION_MODE=paper, saldo virtual inicial de USD 1000 y datos públicos reales. --check sólo valida configuración y consulta APIs públicas: no inicia el monitor ni firma órdenes. Para uso sin desarrollo se puede instalar con pip install .; indicar siempre POLYMARKET_ENV_FILE con ruta absoluta si se instala como paquete fuera de la carpeta fuente.

Conectar un cliente MCP

El cliente debe lanzar el Python del entorno virtual con run_mcp.py. Usar rutas absolutas y reiniciar la conexión después de instalar o cambiar el .env.

Ejemplo JSON para clientes que aceptan mcpServers:

{
  "mcpServers": {
    "polymarket": {
      "command": "C:/ruta/polymarket-mcp/.venv/Scripts/python.exe",
      "args": ["C:/ruta/polymarket-mcp/run_mcp.py"],
      "env": {
        "POLYMARKET_ENV_FILE": "C:/ruta/polymarket-mcp/.env"
      }
    }
  }
}

En Linux/macOS, usar /ruta/polymarket-mcp/.venv/bin/python. Ajustar la ubicación del archivo JSON según el cliente; ver ejemplo completo.

Codex

Fusionar examples/codex.toml con la configuración del cliente, reemplazando las rutas. Alternativamente, registrar por CLI:

codex mcp add polymarket --env "POLYMARKET_ENV_FILE=C:/ruta/polymarket-mcp/.env" -- "C:/ruta/polymarket-mcp/.venv/Scripts/python.exe" "C:/ruta/polymarket-mcp/run_mcp.py"

Las opciones command, args, env, startup_timeout_sec y tool_timeout_sec están documentadas en MCP de Codex. La política de permisos del cliente sigue aplicándose. No poner claves de wallet en archivos de configuración para compartir.

Primer uso

Pedido sugerido:

Consultá modo, saldo, límites y salud del monitor. Analizá BTC Up/Down de cinco minutos con las reglas, el libro y los datos disponibles de Chainlink. Registrá tu probabilidad estimada. Antes de operar, mostrámela junto con la cotización y el motivo. Si te pido SL, configurá sus parámetros y explicame su precio mínimo de salida. Informame los movimientos con sus estados reales.

Flujo habitual: get_status → get_portfolio → discover_markets → get_market_snapshot / get_market_context → record_forecast → quote_trade → execute_trade → poll_updates.

BUY amount es nominal en dólares, al que se suma la comisión. SELL amount es cantidad de shares. Los importes admiten hasta dos decimales; limit_price debe respetar el tick. Todas las órdenes son FOK: ejecución completa dentro del límite o rechazo.

Ejemplo de cotización, usando un slug que exista actualmente:

{"slug":"btc-updown-5m-TIMESTAMP","outcome":"up","side":"BUY","amount":"5.00","limit_price":"0.55"}

Para ejecutar con SL optativo:

{"quote_id":"ID_DEVUELTO","reason":"Motivo de la decisión","stop_loss_percent":"20","stop_slippage":"0.03"}

La configuración del SL y la intención de compra se guardan en la misma transacción. En live espera confirmación de la entrada para calcular el disparador. Repetir execute_trade con el mismo quote_id devuelve la misma orden: no crea otra compra ni cambia un SL existente.

Stop-loss automático

Se puede configurar al comprar o después mediante set_stop_loss. Nunca se activa sólo por iniciar el servidor. Por ejemplo, una entrada media a 0,50 con loss_percent=20 dispara al observar un bid de 0,40 o menor. Con tolerancia absoluta slippage=0.03, el precio mínimo de venta es 0,37, ajustado al tick hacia arriba.

Es un stop-limit local sobre el token Up/Down, no sobre la cotización de BTC/ETH y no una orden stop alojada en el exchange. El porcentaje excluye comisiones; no garantiza una pérdida máxima ni una salida. Sin liquidez suficiente dentro del límite, el monitor registra el problema y vuelve a evaluar mientras el mercado siga operable. Un timeout con envío incierto se reconcilia y no se reenvía con otra intención.

El monitor vive dentro del proceso MCP. Para mantenerlo funcionando al cerrar el cliente, ejecutar en otra terminal o mediante un supervisor:

.\.venv\Scripts\python.exe -m polymarket_mcp --worker

Usar el mismo .env, modo y DATABASE_PATH. Un bloqueo del sistema operativo elige un único monitor por base/modo; otro proceso puede tomar el relevo al salir el primero. El equipo debe permanecer encendido y con conexión. get_status.monitor informa heartbeat y salud; list_stop_losses muestra los errores de cada SL.

La pausa total detiene compras, ventas nuevas y SL. set_reduce_only(true) bloquea compras y permite salidas, salvo que también exista pausa total. Detalles y ejemplos: Stop-loss.

Historial y base de datos

Todo se guarda en data/trading.sqlite3 por defecto. La base conserva cotizaciones, órdenes, eventos de movimientos, posiciones paper, stops, pronósticos, resoluciones oficiales, observaciones Chainlink y diagnósticos. Reiniciar no borra el historial ni recarga el saldo paper.

Consultar get_trade_history para el estado acumulado de cada orden; get_movements para la auditoría con cursor y filtros; get_metrics para latencias, fallos, variaciones de precio y evaluación de pronósticos. poll_updates además sincroniza y puede liquidar posiciones paper. Los eventos de una misma orden no representan compras adicionales.

La base no contiene claves privadas, firmas ni credenciales. Sí contiene información financiera y motivos escritos por el usuario/IA: tratarla como privada. No ofrece un endpoint de SQL arbitrario.

Crear una copia consistente, incluyendo datos que estén en WAL:

.\.venv\Scripts\python.exe scripts/backup_db.py --source data/trading.sqlite3 --output backups/trading-copia.sqlite3

El script se niega a sobrescribir un destino existente. Consultas SQL, esquema y precauciones de restauración: Datos y operación.

Configuración

El .env tiene prioridad sobre variables heredadas. POLYMARKET_ENV_FILE selecciona otro archivo; si se indica y no existe, el arranque falla. Cambios de configuración requieren reiniciar todos los procesos que usan esa configuración.

La exposición sólo cubre movimientos registrados por este MCP. Los fills live confirmados tienen coste nominal conocido; la comisión efectiva puede faltar. Mientras una compra esté pendiente se reserva su débito completo, incluso si ya hay fills parciales, de forma conservadora. Las resoluciones oficiales liberan exposición de mercados terminados. Rechazos verificables y fallos completos liberan presupuesto; cancelaciones conservan la reserva diaria.

En live configurar WALLET_PRIVATE_KEY, POLYMARKET_API_KEY, POLYMARKET_API_SECRET, POLYMARKET_API_PASSPHRASE, POLYMARKET_SIGNATURE_TYPE y, si corresponde, POLYMARKET_FUNDER_ADDRESS. Tipos 1/2/3 requieren funder. La base live queda vinculada a la wallet: usar otra base para otra wallet. No compartir la misma base entre configuraciones con distintos activos o límites. SQLite debe estar en disco local, no en una carpeta sincronizada o unidad de red.

Este MCP no crea approvals, transfiere fondos ni ejecuta redeem. POLYGON_RPC_URL está reservado y no se utiliza. El canje de posiciones ganadoras live se realiza desde Polymarket. Se verifica geoblock antes de enviar.

Herramientas y límites conocidos

La referencia de 21 herramientas detalla parámetros, errores y efectos. La arquitectura describe concurrencia y recuperación.

• Paper usa profundidad y comisiones, pero no reproduce competencia por liquidez, todos los redondeos ni la latencia del exchange. Un resultado paper no acredita rentabilidad live.

• submitted y MATCHED no son liquidación confirmada. Los fills se reconocen al llegar a CONFIRMED. Si falta la orden remota, se conserva evidencia de fills confirmados, pero se mantiene unknown hasta verificar cobertura completa.

• Una caída entre guardar la intención y hacer el POST deja submitting. Se conserva y se investiga; no hay reenvío automático ni herramienta para declararla rechazada sin evidencia.

• RTDS no proporciona historial previo ni replay: la serie empieza cuando el colector recibe datos. Hay indicadores de antigüedad y ausencia de referencia inicial. No se deduce un ganador de esas observaciones.

• Posiciones live de Data API: hasta 500, con posible demora. PnL neto live completo y comisión efectiva por fill no están disponibles en esta versión.

• Las entradas nuevas requieren llamadas del cliente. El monitor sólo reconcilia, recopila datos y ejecuta SL ya autorizados. No envía mensajes a Telegram ni a otros chats.

Pruebas y distribución

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts/smoke_public.py
.\.venv\Scripts\python.exe scripts/smoke_feed.py --seconds 15
.\.venv\Scripts\python.exe scripts/build_share.py

Los tests usan bases temporales y un broker simulado. La firma V2 se prueba con una clave pública de fixture, nunca con la wallet del usuario. Los smoke tests consultan servicios públicos y no leen .env; la compra smoke es virtual. No se valida live enviando dinero real.

build_share.py crea un ZIP mediante una lista explícita de archivos. Compartir ese ZIP, no comprimir toda la carpeta de trabajo: se excluyen .env, bases, configuraciones personales, backups, bots heredados y entorno virtual. Cada destinatario instala las dependencias y crea su propio .env. Ver guía de distribución y actualización.

Referencias oficiales: SDK CLOB V2, ciclo de órdenes, errores CLOB, Chainlink TWAP, errores MCP. Integraciones consultadas el 13 de septiembre de 2026.