bhardwajaditya/trader-in-broker

¿Qué hace trader-in-broker?

El Ejecutor de Órdenes es el único skill en este paquete que puede llevar a una orden real, por lo que es el más estricto. Una orden llega al mercado solo después de pasar por estas compuertas, cada vez, para cada orden:

1. trader-in-risk aprobó esta orden exacta hoy (coincide por huella digital; los mismos ORDER_FIELDS y hash que trader-in-risk/check.py).
2. "paper": false en trader-in/config.json. Con paper (el valor predeterminado) nunca se envía nada; los fills van a un libro contable simulado local.
3. El usuario escribió un sí explícito para esta orden en el chat.
4. El usuario hizo clic en "Permitir una vez" en la tarjeta de permiso de Claude para cada llamada place_order, porque las herramientas de órdenes están configuradas como "Necesita aprobación".

Sin sí, no hay orden. Un sí cubre un ticket (su compra y sus patas de stop y objetivo), nunca un lote.

${CLAUDE_SKILL_DIR} a continuación es la carpeta de este skill (donde se encuentra este SKILL.md).

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                      # cada ticket, LISTO o no
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "sí"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" paper-fill --index 1 --price 1196.30           # paper: la compra
python3 "${CLAUDE_SKILL_DIR}/ticket.py" paper-fill --symbol RELIANCE --side sell --qty 12 --price 1212.70 --leg target
python3 "${CLAUDE_SKILL_DIR}/ticket.py" paper                     # el libro contable paper y P&L
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --leg entry --status placed --broker-id ID --filled-qty 12 --filled-price 1196.30
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --leg stop --status placed --broker-id ID
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol RELIANCE --side sell --qty 12 --price 1212.70 --leg target
python3 "${CLAUDE_SKILL_DIR}/ticket.py" flatten --symbol RELIANCE --qty 12
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py nunca habla con un broker. Renderiza tickets, verifica que una respuesta sea un sí real para esa orden, mantiene el libro contable paper, construye el ticket de cierre (flatten) y mantiene el registro en trader-in/state/broker.json. --now "2026-10-27 10:15" (o solo 10:15) fija el reloj en IST. Los símbolos se aceptan como RELIANCE, RELIANCE.NS, NSE:RELIANCE, M&M, BSE:500325, 500325.BO.

Qué lee y escribe

archivo	qué
trader-in/orders.json	las órdenes propuestas (trader-in-budget las escribe; flatten las reemplaza)
trader-in/config.json	broker (kite o upstox), paper, product, flat_by, costs, capital_inr
trader-in/state/risk.json	los veredictos de trader-in-risk; solo un APROBADO de hoy está LISTO
trader-in/state/broker.json	cada sí, no, colocado, pata colocada y llenada, con la pérdida máxima de cada entrada incluyendo costos
trader-in/state/paper.json	el libro contable paper: efectivo, posiciones abiertas, operaciones cerradas, P&L realizado después de costos estimados
trader-in/portfolio.json	efectivo y acciones (posiciones clave por symbol como RELIANCE.NS, con exchange)
trader-in/plan.json	la hora de cierre para flatten
trader-in/universe.json	(Upstox) ISINs del escáner, si están presentes
trader-in/state/EQUITY_L.csv	(Upstox) lista de acciones de NSE, descargada una vez cuando se necesita un ISIN

Una operación, tres órdenes (lee esto antes de cada bracket)

trader-in-budget escribe un "bracket" (entrada, stop, objetivo). Zerodha y Upstox ya no ofrecen órdenes bracket para esto, por lo que el ticket lo convierte en:

pata	orden	cuándo
1	COMPRA, LÍMITE al precio de entrada (o MERCADO), MIS o CNC	ahora
2	VENTA, SL-M con trigger_price = el stop	solo después de que la pata 1 se haya llenado
3	VENTA, LÍMITE al objetivo	solo después de que la pata 1 se haya llenado

Las patas 2 y 3 NO están vinculadas (sin OCO). Cuando una se llena, la otra sigue activa. Cáncelala de inmediato, o puede llenarse también y dejar al usuario en corto (para MIS) o ser rechazada (para CNC). /trader-in-alerts puede vigilar los niveles de stop y objetivo y sonar cuando se alcance cualquiera. Si se colocan antes de que la pata 1 se llene, las patas 2 y 3 son órdenes de venta simples y pueden abrir una posición corta.

Cada ticket muestra los costos estimados (espec §6: corretaje mínimo ₹20, 0.03% por pata MIS, STT, cargos de intercambio y SEBI, timbre, 18% GST) y la pérdida máxima en el stop incluyendo los costos de ida y vuelta. Esa misma cifra se registra para el límite de pérdida diaria de trader-in-risk. Los costos son siempre una estimación: la nota de contrato contiene los reales.

Paper (el valor predeterminado)

Los brokers indios no tienen cuenta paper, por lo que paper es un libro contable local en trader-in/state/paper.json. No se envía nada a ningún lado.

1. ticket.py show, un ticket LISTO, el sí del usuario, ticket.py approve.
2. Cuando el precio cotiza en la entrada, ticket.py paper-fill --index N (el precio límite) o --price P. Una compra límite no puede llenarse por encima de su límite.
3. Cuando el stop o el objetivo se negocian, registra ESA venta: paper-fill --symbol RELIANCE --side sell --qty 12 --price 1188.10 --leg stop. El libro contable registra el P&L bruto, los costos estimados de ida y vuelta y el neto.
4. ticket.py paper imprime efectivo, posiciones abiertas y P&L realizado.

La entrada paper se registra como placed (con "paper": true), por lo que trader-in-risk la cuenta contra los límites de operaciones por día y pérdida diaria exactamente como una real.

Configuración A: Zerodha Kite (servidor MCP oficial) — el predeterminado

El servidor de Zerodha es github.com/zerodha/kite-mcp-server (MIT, Go). Verificado contra su código fuente y README el 2026-10-27 (último commit 5e044dc, tag v0.4.0-dev24).

El servidor alojado no puede colocar órdenes. El README dice que el alojado https://mcp.kite.trade/mcp "excluye operaciones de trading potencialmente destructivas por seguridad", y las propias páginas de Zerodha lo describen como de solo lectura (una publicación de Z-Connect dice que las órdenes GTT eran la excepción; el alcance ha cambiado con el tiempo, así que verifica con la lista de herramientas de Claude después de conectarte). Es gratuito y no necesita clave API: la herramienta login devuelve un enlace de Kite, el usuario inicia sesión con su propia contraseña de Kite y 2FA en el navegador, nunca en el chat.

Alojado, solo lectura (cotizaciones, tenencias, posiciones, márgenes, órdenes, historial):

• Claude Desktop: Configuración > Desarrollador > Editar Config, agrega el bloque "kite" de claude_desktop_config.example.json (ejecuta npx mcp-remote https://mcp.kite.trade/mcp; necesita Node.js), reinicia.
• Claude Code: claude mcp add --transport http kite https://mcp.kite.trade/mcp (o el mismo comando npx mcp-remote como servidor stdio: claude mcp add kite -- npx mcp-remote https://mcp.kite.trade/mcp).

Para colocar órdenes a través de Claude, el usuario ejecuta su propia copia del servidor con su propia aplicación Kite Connect:

1. Crea una aplicación Kite Connect en developers.kite.trade (verifica el precio actual allí). Su URL de redireccionamiento debe apuntar al callback del servidor local; en el código fuente del servidor, la ruta de callback es /callback en APP_HOST:APP_PORT (predeterminado http://localhost:8080/callback). No probamos esto de principio a fin.
2. A partir del 1 de abril de 2026, las páginas de soporte de Zerodha dicen que la colocación de órdenes a través de la API necesita una IP estática incluida en la lista blanca con Zerodha (reglas minoristas-algorítmicas de NSE/SEBI). Una conexión doméstica sin IP estática puede hacer que las órdenes sean rechazadas. Verifica la regla actual de Zerodha antes de ponerlo en vivo.
3. Constrúyelo: git clone https://github.com/zerodha/kite-mcp-server && cd kite-mcp-server && go build -o kite-mcp-server (Go 1.21+).
4. Agrega el bloque "kite-orders" de claude_desktop_config.example.json: la ruta completa al binario, APP_MODE stdio, y el usuario escribe KITE_API_KEY y KITE_API_SECRET en ese archivo ellos mismos. En Claude Code: claude mcp add kite-orders -e APP_MODE=stdio -e KITE_API_KEY="$KITE_API_KEY" -e KITE_API_SECRET="$KITE_API_SECRET" -- /full/path/to/kite-mcp-server con los valores exportados primero en el shell del usuario. Mantén solo uno de kite / kite-orders si no necesitas ambos.
5. Reinicia, pídele a Claude que llame a login, el usuario abre el enlace e inicia sesión. Las sesiones de Kite caducan diariamente (los tokens de acceso de Kite Connect duran hasta la mañana siguiente), así que espera tener que iniciar sesión nuevamente cada día de negociación.

Las claves y tokens nunca van en el chat. Nunca los pidas, nunca leas el archivo de configuración de vuelta en la conversación. Si el usuario pega una clave o token, dile que elimine ese mensaje y lo regenere en developers.kite.trade.

Permisos de herramientas. Personalizar > Conectores (Claude Desktop), abre el servidor Kite, establece:

• place_order, modify_order, cancel_order, place_gtt_order, modify_gtt_order, delete_gtt_order: Necesita aprobación. Nunca "Permitir siempre".
• herramientas de solo lectura (get_profile, get_margins, get_holdings, get_positions, get_orders, get_order_history, get_order_trades, get_trades, get_gtts, get_quotes, get_ltp, get_ohlc, get_historical_data, search_instruments, login): "Permitir siempre" está bien.
• En Claude Code, mantenlas en "ask" en .claude/settings.json: "permissions": {"ask": ["mcp__kite-orders__place_order", "mcp__kite-orders__modify_order", "mcp__kite-orders__cancel_order"]}; nunca pongas una herramienta de orden en allow. El servidor también acepta EXCLUDED_TOOLS=place_order,modify_order,cancel_order para una copia de solo lectura.

Argumentos de place_order (del código fuente del servidor): variety (regular), exchange (NSE/BSE), tradingsymbol, transaction_type (BUY/SELL), quantity (int), product (MIS/CNC), order_type (MARKET/LIMIT/SL/SL-M), price (LIMIT, SL), trigger_price (SL, SL-M), validity (DAY), opcional tag (≤ 20 caracteres; el ticket agrega trin + 12 hex de la huella digital para que la orden pueda ser encontrada más tarde). La herramienta del servidor no tiene argumento market_protection; NSE ahora aplica protección de mercado a las órdenes API MARKET y SL-M, por lo que una orden de mercado puede ser convertida a un límite protegido por el broker. Las entradas límite evitan esto. Para BSE, el tradingsymbol de Kite es el nombre del scrip, no el código numérico: búscalo con search_instruments.

Configuración B: Upstox ("broker": "upstox")

• El servidor MCP oficial de Upstox (https://mcp.upstox.com/mcp, instalado desde el plugin upstox/upstox-plugin-marketplace upstox-mcp) es de solo lectura: la página de Upstox dice que no se pueden colocar órdenes a través de él. Las conexiones caducan diariamente (consentimiento OAuth en el navegador).
• El skill de agente oficial de Upstox (/plugin install upstox-skill@upstox-plugins-official en Claude Code, después de /plugin marketplace add upstox/upstox-plugin-marketplace) puede colocar órdenes con la API de órdenes v3. Lee un token de acceso diario de la variable de entorno UPSTOX_ACCESS_TOKEN (establecida por el usuario en su propio shell, nunca en el chat), muestra su propia vista previa y espera confirmación. Upstox dice que no se ejecuta en el chat simple de Claude Desktop.
• O el usuario coloca la orden en la aplicación Upstox desde el ticket.

El ticket imprime el cuerpo para POST https://api-hft.upstox.com/v3/order/place (v2 /v2/order/place está marcada como obsoleta; toma los mismos campos menos slice): quantity (int), product (I intradía = MIS, D entrega = CNC), validity DAY, price (0 para MARKET / SL-M), instrument_token, order_type, transaction_type, disclosed_quantity 0, trigger_price (0 a menos que sea SL / SL-M), is_amo false (Upstox lo ignora), tag, y market_protection: -1 (automático) en MARKET y SL-M, ya que 0 es rechazado para órdenes de mercado API.

instrument_token es NSE_EQ|<ISIN> (o BSE_EQ|<ISIN>). El ISIN proviene de, en orden: --isin, un isin en la orden, trader-in/universe.json del escáner, o si no, la lista EQUITY_L.csv de NSE (descargada una vez con un User-Agent de navegador a trader-in/state/EQUITY_L.csv, archives. luego nsearchives.). Limitación de BSE: la lista de NSE solo asigna símbolos de NSE. Un código de scrip de BSE como 500325.BO no se puede asignar, así que pasa --isin; para un símbolo de nombre .BO se usa el ISIN de la lista de NSE (misma empresa), pero verifícalo. No verificamos el formato del archivo de instrumentos de Upstox aquí. Sin ISIN, un ticket de Upstox en vivo no está LISTO; los tickets paper no necesitan uno.

Pasos: la entrada

1. ticket.py show. Solo los tickets LISTO van al usuario. Un ticket que NO está LISTO o BLOQUEADO regresa a /trader-in-risk (no tiene JSON de broker).
2. Muestra UN ticket, incluyendo la advertencia de no OCO, y pregunta: "¿Colocar esta orden? Responde sí o no." Una orden por pregunta. Nunca ofrezcas "sí a todo".
3. ticket.py approve --index N --reply "<la respuesta del usuario, palabra por palabra>". "No registrado" significa que la respuesta no fue un sí explícito para esta orden ("claro", "haan", "sí a todo", un sí nombrando otra acción o cantidad). Pregunta de nuevo. Nunca conviertas una respuesta en un sí por ti mismo.
4. Paper: paper-fill como se indicó anteriormente. En vivo, Kite: llama a place_order exactamente con el JSON de la pata 1; el usuario hace clic en "Permitir una vez". Confirma el fill (get_order_history / get_positions), luego place_order pata 2, luego pata 3, cada una con su propio "Permitir una vez". En vivo, Upstox: entrega los cuerpos al skill de agente Upstox o a la aplicación, una pata a la vez, mismo orden.
5. Registra cada pata en vivo: ticket.py result --index N --leg entry|stop|target --status placed|denied|failed --broker-id <id> (--filled-qty, --filled-price en la entrada). Solo la entrada cuenta como una orden para trader-in-risk; las patas se registran como leg_placed. Una orden fallida no se reintenta sin una nueva verificación y un nuevo sí.

Pasos: mientras está abierta, y salida por flat_by

• /trader-in-alerts vigila el stop, el objetivo y la hora de cierre.
• Cuando el stop o el objetivo se llena: en vivo, ticket.py fill ... --leg stop (te recuerda que canceles la otra pata ahora: get_orders, luego cancel_order, Necesita aprobación); paper, paper-fill ... --leg stop.
• Para flat_by (15:10 IST predeterminado), cualquier cosa que aún esté abierta se cierra. Los brokers cierran automáticamente las posiciones MIS abiertas a partir de aproximadamente las 15:20 IST y cobran una tarifa por ello (Zerodha lista ₹50 + GST por orden), así que no se lo dejes a ellos:
  1. En vivo: pregunta al broker cuántas acciones se mantienen: get_positions (solo lectura).
  2. ticket.py flatten --symbol RELIANCE --qty 12 escribe una VENTA MERCADO (mismo producto) en trader-in/orders.json.
  3. Índice 1, mostrar, aprobar (el sí del usuario, "Permitir una vez").
  4. Después de que se llene: paper-fill (paper) o fill (en vivo), luego marca la pata como cancelada (no se pudo llenar porque se canceló).
• Si no queda tiempo (flat_by en menos de 5 minutos), menciona que el broker cerrará automáticamente la posición con una tarifa y pregunta si el usuario quiere que el skill intente cerrarla primero.

Modo de depuración

TICKET_DEBUG=1 python3 "${CLAUDE_SKILL_DIR}/ticket.py" show imprime rastreos de pila y el árbol de datos completo que se está renderizando. Útil cuando el ticket no se muestra como se esperaba.

Referencias

• Zerodha Kite MCP server: https://github.com/zerodha/kite-mcp-server (MIT, Go)
• Zerodha Kite Connect developer docs: https://kite.trade/docs/connect/v3/
• Upstox MCP server (solo lectura): https://mcp.upstox.com/mcp
• Upstox agent skill (puede colocar órdenes, necesita UPSTOX_ACCESS_TOKEN): plugin upstox-skill@upstox-plugins-official