Bot de negociación con la API de Kalshi: solicitudes conciliables

Define la intención económica antes de la solicitud

La estrategia debe expresar lo que desea en términos que conserven su significado fuera del contenido de una solicitud HTTP. Una intención identifica el contrato, el cambio direccional deseado, una cantidad máxima, un precio aceptable y una fecha límite. También registra la aprobación que permitió la acción y la asignación de cuenta que puede consumir.

Ese registro es distinto de un intento de solicitud. Un intento tiene una marca de tiempo, un destino, una firma y una respuesta o un error. Puede haber varios intentos asociados a una intención, pero el cliente no debe confundir el número de intentos con el número de posiciones autorizadas.

Guarda la intención de forma persistente antes de realizar la acción. Si el cliente envía primero y guarda después, un fallo entre esos pasos deja un efecto en la cuenta sin su explicación local. Escribir primero permite que un proceso reiniciado descubra una intención sin resolver e investigue, en lugar de suponer que no se produjo ninguna operación.

El registro no tiene por qué ser grande. Debe contener información suficiente para reproducir la acción económica propuesta y distinguirla de otra propuesta. Un código de motivo como entrada por previsión solo es útil cuando remite a la previsión específica y a la versión de la política que autorizaron la orden.

La guía de diseño de API para bots de mercados de predicción trata la separación entre política y acceso a la cuenta. En este límite, el principio clave es que los detalles de transporte deben implementar una intención aprobada, sin crear una nueva política de negociación mediante valores predeterminados accidentales.

Autenticación de un bot de negociación con la API de Kalshi

La autenticación de un bot de negociación con la API de Kalshi debe seguir exactamente el esquema oficial vigente. La guía de solicitudes autenticadas especifica un identificador de clave API, una marca de tiempo en milisegundos y una firma RSA-PSS en base64 que utiliza SHA256. El mensaje firmado une la marca de tiempo, el método HTTP y la ruta completa de la solicitud sin parámetros de consulta.

La mayoría de los errores de implementación en este punto son errores de representación. Una marca de tiempo en segundos no es una marca de tiempo en milisegundos. Una ruta repetida porque dos funciones auxiliares añaden cada una un prefijo no es la ruta prevista. Firmar un método distinto del enviado produce una solicitud cuyas pruebas de autorización no describen la acción transmitida.

Construye el destino y la ruta de firma a partir de la misma definición validada de solicitud. Esto reduce la posibilidad de que una función firme una ruta mientras otra envía a una ubicación diferente. Las pruebas deben cubrir tanto una ruta con parámetros de consulta como una sin ellos.

Mantén la firma separada de la salida de diagnóstico habitual. Los registros pueden conservar el método, una descripción segura de la ruta, un identificador de intención y la clasificación de la respuesta sin registrar una clave privada. Una exportación para soporte no debe exponer el material que autoriza futuras acciones de cuenta.

Trata un fallo de autenticación como un motivo para examinar las credenciales, la gestión del reloj y la construcción de solicitudes. Repetir la misma solicitud inválida a gran velocidad no la repara. La estrategia debe seguir sin poder crear nueva exposición hasta que el cliente pueda establecer que su vista autenticada de la cuenta es válida.

Utiliza el vocabulario actual de órdenes de eventos

La referencia actual de creación de órdenes V2 utiliza la ruta de órdenes de eventos, un lado bid o ask del libro, una cantidad de contratos en forma de cadena y un precio en dólares de punto fijo. Su precio se expresa en la escala YES: bid compra YES, mientras que ask vende YES. No debe copiarse un contenido de solicitud antiguo en un cliente nuevo sin revisar el contrato actual de la API.

Traduce el lenguaje de la estrategia a esta representación en un solo lugar. Una estrategia puede hablar de obtener exposición a NO, mientras que la solicitud utiliza un precio en la escala YES. Esa traducción debe ser explícita y estar probada para que un cambio posterior de visualización no invierta una orden silenciosamente.

Utiliza un ejemplo hipotético para comprobar la conversión. Si el límite económico previsto es pagar como máximo 32 centavos por NO en un contrato binario sencillo, el precio complementario en la escala YES es de 68 centavos. El adaptador debe preservar conjuntamente la dirección y el límite previstos. Cambiar solo el lado y dejar una convención de precio ajena puede producir una operación diferente.

Mantén separados los modelos de solicitud y respuesta. Una respuesta compacta de creación puede confirmar una orden sin proporcionar todos los campos utilizados en una vista completa de órdenes de cuenta. El cliente no debe rellenar los campos ausentes con supuestos optimistas como ejecución completa o ausencia de exposición restante.

Una incompatibilidad de esquema debe detener visiblemente esa vía de acción. Si falta un campo obligatorio o tiene un significado desconocido, aceptarlo silenciosamente puede corromper la contabilidad posterior. Un fallo limitado es preferible a una solicitud aparentemente satisfactoria cuya interpretación económica se desconoce.

Gestiona los precios de punto fijo del bot con la API de Kalshi

Los precios de punto fijo de un bot de negociación con la API de Kalshi deben conservar su exactitud durante la validación, los cálculos y la serialización. La guía oficial de representación de punto fijo describe cadenas en dólares, cantidades fraccionarias de contratos e intervalos de precios específicos de cada mercado. Ya no basta con suponer universalmente que todo precio válido es un centavo entero.

Utiliza aritmética decimal o una representación mediante enteros escalados definida con cuidado. Lo importante es que una entrada válida como 0.1250 conserve su valor previsto. El redondeo del punto flotante binario no debe decidir si un precio propuesto se ajusta a la cuadrícula aceptada del mercado.

En un cálculo ilustrativo, 12.50 contratos a 0.2400 dólares tienen un importe de compra de exactamente 3 dólares antes de comisiones. Un analizador que elimina el medio contrato fraccionario registra en cambio 2.88 dólares, dejando una diferencia de 12 centavos. Un analizador que confunde dólares con centavos crea un error mucho mayor.

Valida los precios frente a la cuadrícula actual del mercado antes de enviarlos. Si un modelo teórico sugiere 0.237 dólares pero la banda pertinente permite un incremento diferente, el cliente necesita una política de redondeo establecida. Redondear hacia un precio más agresivo puede vulnerar el coste máximo de la estrategia, por lo que la política debe respetar el límite económico.

Conserva la entrada original y el valor normalizado entre las pruebas de diagnóstico. Esto permite que un revisor distinga un error de origen de un error de conversión. También facilita probar cambios posteriores de representación, porque los mismos casos registrados pueden pasarse tanto por los adaptadores antiguos como por los nuevos.

Separa la cantidad de contratos, el precio y el efectivo

En una pantalla de órdenes suelen aparecer próximas tres cantidades: contratos, dólares por contrato y efectivo total. No son intercambiables. Un campo llamado amount es demasiado impreciso para un modelo interno, salvo que su unidad sea fija y esté claramente documentada.

Utiliza nombres y tipos que transmitan significado. La cantidad de contratos puede ser fraccionaria. El precio límite describe un importe por contrato. El cargo estimado incluye la cantidad multiplicada por el precio y una provisión para los costes aplicables. El movimiento real de efectivo procede del resultado registrado de cuenta, que puede diferir de la estimación.

Una intención hipotética de comprar 25 contratos a 44 centavos tiene un importe de compra de 11 dólares. No es una instrucción para gastar 25 dólares ni una orden de 44 dólares. Estas distinciones pueden parecer obvias, pero es fácil perderlas cuando varios endpoints utilizan nombres de campos o unidades diferentes.

Incorpora comprobaciones dimensionales en el límite de solicitudes. Un precio fuera del intervalo permitido del contrato, una cantidad de compra negativa o una estimación de efectivo que no pueda conciliarse con la cantidad y el precio deben rechazarse antes de firmar. Estas comprobaciones son más útiles que descubrir el error después de que la plataforma rechace la solicitud.

La visión general de la API de negociación en mercados de predicción sitúa estas representaciones en un contexto de integración más amplio. Un cliente sólido mantiene explícitas las unidades desde la observación de origen hasta el informe de cuenta, en lugar de depender de que una interfaz de usuario las deduzca al final.

Conserva un identificador entre intentos inciertos

Crea un identificador local de intención y un identificador de orden de cliente adecuado antes del envío. Guarda la relación con el identificador de orden del servidor cuando se conozca. Estas identidades permiten conectar un registro posterior de cuenta con la acción que lo produjo.

La guía oficial de inicio rápido describe la detección de duplicados mediante el identificador de orden de cliente. Esa función es útil, pero el cliente debe mantener igualmente su propio diario de intenciones y examinar las pruebas actuales de cuenta. No conviertas una comprobación documentada de duplicados en una afirmación sin fundamento de que cualquier solicitud puede repetirse para siempre y bajo cualquier condición.

Si una orden agota el tiempo de espera después de transmitirse, el resultado es desconocido. El cliente debe conservar la intención económica original y su capacidad reservada. Después puede examinar órdenes y ejecuciones o realizar un reintento documentado que preserve la identidad adecuada. Crear por defecto un identificador nuevo ante la incertidumbre implica el riesgo de un segundo compromiso independiente.

Una respuesta de duplicado puede ser en sí misma una prueba útil. Puede indicar que la acción original llegó a la plataforma, pero por sí sola no demuestra qué cantidad se ejecutó. Sigue la identidad hasta el registro de cuenta y resuelve la exposición restante.

Conserva el diario entre reinicios. Un identificador guardado únicamente en la memoria del proceso desaparece precisamente cuando la recuperación puede necesitarlo más. Aquí la durabilidad no es una preferencia abstracta de base de datos; preserva la conexión entre una decisión aprobada y los efectos de cuenta que quizá ya existan.

Clasifica la política de reintentos del bot con la API de Kalshi

Una política de reintentos para un bot de negociación con la API de Kalshi debe distinguir entradas inválidas, permisos denegados, presión sobre los límites de solicitudes, fallos de transporte y resultados económicos inciertos. Estas categorías no se resuelven con la misma respuesta. Un único bucle genérico de reintentos puede convertir un pequeño problema de conexión en un problema de cuenta mayor.

Una cuadrícula de precios inválida o una cantidad mal formada requiere corrección. Una denegación de acceso exige comprender el permiso o estado de la cuenta. La presión sobre los límites requiere regular el ritmo y establecer prioridades. Una respuesta perdida después de una escritura requiere conciliación. Un fallo temporal de lectura puede permitir otro intento de observación sin autorizar ninguna posición nueva.

Cada reintento debe seguir respetando la fecha límite de la intención. Una entrada basada en el precio que tenía sentido antes de una publicación puede dejar de ser aplicable tras varios segundos de retraso. Entregar satisfactoriamente una operación caducada no es ejecutar correctamente la política original.

Utiliza esperas progresivas acotadas para tareas de comunicación repetibles, con límites tanto de intentos como de tiempo transcurrido. Los límites deben elegirse según el valor y la urgencia de la tarea. Agotar la política de reintentos debe producir un estado sin resolver claro, no un bucle invisible que continúe indefinidamente.

Registra el motivo de cada intento. Un revisor posterior debe poder ver si el cliente obtenía pruebas nuevas, reintentaba una acción documentada segura frente a duplicados o investigaba una incertidumbre. Esa distinción ayuda a identificar si el problema real está en la respuesta de la plataforma, en la construcción local de solicitudes o en los supuestos temporales de la estrategia.

Mantén capacidad de lectura disponible para la recuperación

Un cliente puede perder un control útil si las consultas habituales consumen la capacidad necesaria para examinar una orden incierta. Por tanto, el presupuesto de solicitudes debe reservar margen para la recuperación de cuenta y la reducción del riesgo, en lugar de tratar todas las solicitudes como igualmente valiosas.

Los límites actuales de Kalshi utilizan costes en tokens y presupuestos específicos de cada cuenta. La documentación de límites de solicitudes distingue los recursos de lectura y escritura y describe los detalles actuales de enrutamiento. Un cliente debe obtener la configuración aplicable, en lugar de suponer un único número fijo de solicitudes por segundo para todas las cuentas y endpoints.

Considera un programador hipotético con una asignación de lectura limitada. Un examen completo de cientos de mercados no relacionados puede tener menos prioridad que comprobar si se ejecutó una orden reciente. Si el examen bloquea esa comprobación, la estrategia puede permanecer incierta más tiempo y perder acciones legítimas o realizar acciones inseguras.

El procesamiento por lotes y la transmisión continua pueden reducir parte del trabajo, pero no eliminan la necesidad de comprender la semántica de los endpoints. Un lote puede contener resultados mixtos. Una transmisión puede desconectarse. El programador debe priorizar la información necesaria para establecer las obligaciones actuales de la cuenta.

Mide el coste de las solicitudes por finalidad. Separa descubrimiento, observación normal, seguimiento de órdenes y recuperación. Esto permite reducir el trabajo en segundo plano cuando aumenta la presión sin desactivar accidentalmente las comprobaciones que protegen la cuenta.

Reconstruye las ejecuciones parciales sin contar dos veces

Una ejecución parcial cambia tanto las existencias como la exposición restante de la orden. El cliente necesita preservar esos dos hechos. Una cantidad solicitada de 30 con 12 ejecutados y 18 todavía activos difiere de una orden cerrada que solo ejecutó 12.

Conoce si cada campo es acumulativo o incremental. Si una respuesta muestra una cantidad total ejecutada de 12 y una respuesta posterior muestra 20, la ejecución adicional es de ocho. Sumar ambos totales crea una posición falsa de 32. Los eventos incrementales de ejecución requieren otro tratamiento, incluida la detección de duplicados.

Una cancelación puede coincidir en el tiempo con una ejecución. El registro final debe admitir que parte de la cantidad se ejecutara antes de retirar el resto de la orden. Que una cancelación haya tenido éxito no deshace ejecuciones anteriores ni demuestra que la solicitud original no tuviera efecto.

Utiliza las posiciones de cuenta como comprobación cruzada, reconociendo que las instantáneas pueden representar momentos de observación distintos. El objetivo es una conciliación explicada, no forzar a que todas las respuestas de los endpoints sean idénticas en cada instante. Conserva las marcas de tiempo y la secuencia de pruebas utilizadas para resolver una diferencia.

La guía de sincronización de cuentas de mercados de predicción desarrolla este razonamiento a nivel de sistema. En el límite de la API, la tarea esencial es conservar suficientes detalles de identidad y cantidad para que una conciliación posterior pueda realizarse con precisión.

Prueba el límite con fallos deliberados

Las pruebas útiles del cliente se centran en errores que pueden cambiar el significado económico. Prueba una cantidad fraccionaria, un precio en el límite de una banda, una intención caducada y un campo de respuesta desconocido. Cada caso debe tener una decisión esperada que pueda revisarse sin una operación real.

Después, prueba la incertidumbre de comunicación. Simula que desaparece una respuesta después de aceptarse una solicitud. Reinicia el cliente mientras esa intención siga sin resolverse. El comportamiento esperado es recuperar la intención existente y examinar su resultado de cuenta, no comenzar una nueva decisión de estrategia desde un estado vacío.

Prueba también datos de origen mal formados. Un precio ausente no debe convertirse en cero. Una cadena que no pueda interpretarse no debe convertirse en una cantidad predeterminada. Rechazar datos inutilizables con una explicación es un resultado de prueba satisfactorio.

Mantén las credenciales y las acciones reales de cuenta fuera de las ejecuciones automatizadas habituales de pruebas. Un conjunto controlado de datos de prueba puede establecer el comportamiento de conversión y clasificación. Un ejercicio de demostración autorizado por separado puede probar después la conectividad sin tratar la liquidez ficticia como prueba de la calidad de ejecución real.

Por último, conserva los casos de fallo a medida que evoluciona la API. El valor de un conjunto de regresión es preservar las expectativas económicas mientras cambia la forma de la solicitud. Una actualización es aceptable cuando sigue produciendo el comportamiento limitado previsto, no simplemente cuando compila o devuelve un estado HTTP satisfactorio.

Convierte los cambios de API en una tarea de traducción revisada

Un cambio en la API debe provocar una revisión de los supuestos del adaptador. Los nuevos nombres de campos pueden ser sencillos, pero un cambio en la convención de precios, el significado de la cantidad o la integridad de la respuesta puede alterar el comportamiento de cuenta aunque el código siga funcionando.

Mantén un pequeño registro de compatibilidad que enumere la documentación revisada, las formas de solicitud admitidas y los casos de prueba que establecen su significado. Evita describir un cliente como permanentemente compatible. La compatibilidad es una evidencia vinculada a una versión y a un conjunto probado de operaciones.

Al migrar, compara los resultados normalizados de ejemplos guardados. La misma intención económica debe producir límites y dirección equivalentes en la nueva representación. El mismo historial de ejecuciones debe producir la misma posición y explicación del efectivo. Las diferencias deben comprenderse antes de habilitar nuevas acciones.

Un adaptador de alcance limitado hace manejable este trabajo. La investigación de estrategias puede seguir expresándose en contratos explícitos, probabilidades y límites económicos, mientras un único límite revisado gestiona las convenciones actuales de la plataforma. Esa separación convierte el mantenimiento de la API en un problema concreto de traducción y proporciona al propietario una base más clara para decidir cuándo el cliente está listo para actuar de nuevo.

Guías relacionadas y ejemplos resueltos

• Negociación automatizada con la API de Kalshi: sigue cada decisión — Construye un cliente auditable desde el descubrimiento de mercados hasta la conciliación de cuenta.
• API de negociación de Kalshi: elige la interfaz de datos adecuada — Selecciona interfaces de mercado y cuenta teniendo en cuenta los presupuestos de solicitudes y las convenciones de datos.