Limitaciones conocidas

Vacíos e inconsistencias del contrato de la API, señalados en lugar de rellenados.

Esta página es una lista de cosas que el contrato no dice. Las páginas de endpoints de la sección Referencia se generan a partir de openapi.json y describen lo que declara el contrato y nada más. Cuando el contrato guarda silencio, es ambiguo o es inconsistente consigo mismo, esta página lo registra en lugar de rellenar el vacío con una prosa plausible.

Léela antes de construir sobre una operación cuyo comportamiento deduces en lugar de leerlo.

Cada elemento está bajo la parte de la API a la que pertenece. Nada de esto es un compromiso de la hoja de ruta. Son observaciones sobre el contrato tal como está.

La línea base se verificó contra la especificación 0.9.90, y cada entrada de abajo se vuelve a comprobar en cada incremento de la especificación con .github/scripts/known_gaps_check.py. Cada entrada registra un predicado contra el contrato en known-gaps-assertions.json. Cuando un predicado deja de cumplirse, el vacío se llenó, y la CI falla hasta que se elimine la entrada. Las entradas que afirman algo sobre la prosa y no sobre la estructura están marcadas como verificadas a mano y llevan la versión de la especificación contra la que se leyeron por última vez, que la misma validación exige mantener al día.

Una lista de vacíos desactualizada es peor que no tener ninguna. Entre 0.9.27 y 0.9.63 esta se desactualizó. Ocho entradas estaban mal, y tres de ellas describían vacíos que el contrato ya había cerrado. Por eso la verificación ahora es mecánica y no una promesa de volver a leer.

Trading

• Límites de los lotes. No se declara una longitud máxima de lote para POST /orders/batch, y el contrato no dice cómo se pondera un lote frente al límite de solicitudes (una solicitud o una por elemento).
• reduce_only. Declarado como booleano sin descripción. No se especifica su interacción con los tipos de órdenes condicionales y trailing.
• Semántica de los campos de PreviewResponse. Los ocho campos tienen tipo, pero no tienen descripciones en el contrato.
• Dirección del disparador. "Adversa" y "favorable" no están definidas formalmente por side para las familias Stop y Take profit.
• Vigencia × tipos condicionales. El contrato no indica qué valores de time_in_force son válidos para los seis tipos de órdenes condicionales (por ejemplo, PostOnly en un StopMarket).
• Posibilidad de modificación. Más allá de "las órdenes de liquidación no se pueden modificar", el contrato no dice si las órdenes condicionales o trailing se pueden modificar, ni si una modificación puede cambiar time_in_force.
• Eliminación de stop_price. Marcado como deprecado sin una versión ni una fecha de eliminación indicadas.

Posiciones

• Hoy leverage es permanentemente null. El contrato indica que es "actualmente siempre null" con leverage_error: "margin_state_not_mirrored", y no da ningún plazo para completarlo. Los clientes no pueden leer el apalancamiento por posición en estos endpoints.
• No hay filtro por mercado en las posiciones cerradas. GET /positions/closed solo acepta limit y cursor, así que no hay forma de limitar la consulta a un solo mercado. No acepta ni market_id ni symbol. El campo de la respuesta se renombró a symbol en 0.9.74, y el parámetro nunca existió con ninguno de los dos nombres.
• Ventana de retención no indicada. funding_paid está documentado como "limitado por el historial de financiamiento que retiene el indexador", pero no se indica ningún período de retención. La paginación por cursor en estos endpoints ya no forma parte de este vacío: GET /positions/closed documenta una ventana retenida de 200 registros en limit.
• Falta el 429 en las posiciones cerradas. GET /positions/closed y su gemela /api/v1 solo declaran 200 y 401. El contrato omite la respuesta 429 que declara la otra operación de posiciones, aunque se aplica la misma capa de límites de solicitudes.
• Solo margen cruzado. initialMargin se define "según el modelo de margen cruzado del motor", y el contrato señala que el indexador no replica las asignaciones de margen aislado/personalizado. Así que aquí no se puede leer la asignación real de una posición con margen aislado.
• No hay conteo ni total de posiciones abiertas. La respuesta es un arreglo simple sin envoltorio y sin paginación en GET /positions, así que no hay un límite documentado de cuántas posiciones puede llevar una sola respuesta.

Cuenta

• direction no está enumerado. POST /account/margin no declara ningún esquema de solicitud. Su ejemplo muestra "direction": "add", y el resumen y la descripción del 400 implican que también se puede quitar margen, pero el contrato nunca indica el valor para quitarlo. Tampoco nombra los tipos de los campos ni marca ningún campo como obligatorio.
• Dos operaciones no declaran esquema de solicitud. POST /account/deposit y POST /account/margin solo tienen ejemplos de solicitud, así que los clientes generados a partir del contrato reciben cuerpos de solicitud sin tipo para ambas. Sus respuestas sí tienen tipo (DepositResponse, AdjustMarginResponse); lo que no está declarado es el lado de la solicitud.
• Dos rutas de depósito superpuestas. POST /account/deposit y POST /deposits depositan colateral y devuelven DepositResponse, y el contrato no dice cuál preferir ni en qué difieren operativamente. Como las respuestas coinciden, la forma devuelta no permite distinguirlas.
• Los vocabularios de estado no coinciden. Withdrawal.status es pending / settled / failed, y FundsEntry.status es pending / submitted / confirmed / failed. El mismo ciclo de vida tiene dos conjuntos de nombres y una cantidad distinta de etapas, así que no existe una correspondencia completa entre ellos. submitted no tiene equivalente en Withdrawal, y settled no tiene ninguno en FundsEntry.
• Las mayúsculas del nivel de límites de solicitudes son inconsistentes. RateLimitStatus.tier está documentado en minúsculas (pro, marketmaker, unlimited). El ejemplo del cuerpo del 429 devuelve "tier": "Pro". Las operaciones de administración de niveles usan MarketMaker y Pro. El contrato no indica una forma canónica.
• La cobertura del 429 es desigual. Varias operaciones sujetas a la misma capa de límites de solicitudes solo declaran 200 y 401: las dos operaciones de historial de patrimonio, las dos de historial de órdenes, los dos GET y PUT de cancelación al desconectar, GET /withdrawals, GET /deposits, POST /deposits, GET /orders/{order_id} y las dos operaciones de estado de límites de solicitudes.
• Las ventanas de retención son una cantidad de registros, no una duración. Cada operación ahora indica el tamaño de su ventana retenida (1,000 ejecuciones, 500 registros de historial de órdenes, 200 posiciones cerradas, 720 puntos de patrimonio, 10,000 operaciones). Ninguna operación dice cuánto tiempo atrás abarca eso, así que un cliente no puede saber si un recorrido cubre una semana o un año. El subconteo de volume_30d ya no forma parte de este vacío: volume_30d_estimated indica qué garantía se aplica.
• Los máximos de limit son menores que lo que dice la prosa en dos lugares. GET /withdrawals y GET /deposits limitan limit a 100 con un valor predeterminado de 100, así que el parámetro solo puede reducir la página. No hay forma de paginar más allá de 100 registros, porque ninguna de las dos operaciones acepta un cursor.
• EquityPoint.equity es un número JSON. Todos los demás campos monetarios de esta etiqueta son cadenas decimales sin pérdida. El propio contrato señala la diferencia con PortfolioPoint.equity e indica a los clientes que comparen por valor decimal, pero la representación como float sigue en el wire.
• early_access_allowed está presente o ausente, no es verdadero o falso. El contrato dice que aparece "solo cuando la validación de acceso anticipado está activa" sin indicar qué rige la validación ni qué significa su ausencia para quien llama.
• No hay nivel ni programa de descuentos por cuenta. AccountFees.tier siempre es base, discounts siempre está vacío y FeeDiscount no tiene propiedades definidas. Las comisiones efectivas por mercado para los mercados del búfer de ejecuciones retenido actualmente se entregan en markets. La ausencia de un mercado no dice nada sobre la actividad histórica de la cuenta. Quienes llaman deben seguir tratando schedule como una cadena abierta y distinguir per_market, reference y el centinela unknown con valor cero.
• Hoy Position.leverage es permanentemente null en cada respuesta que incluye una posición (AccountSummary, AccountState), con leverage_error: "margin_state_not_mirrored". Consulta GET /positions.