Mejores prácticas

Gestión de conexiones

Abra una única conexión WebSocket y reutilícela para cada solicitud y suscripción, en lugar de abrir una conexión por llamada. Multiplexa las solicitudes a través del socket compartido y relacione cada respuesta con su solicitud utilizando req_id.

Cuando la conexión se interrumpa, reconéctese con retroceso exponencial (por ejemplo, 1s, 2s, 4s, 8s, con límite máximo) más un pequeño jitter, en lugar de reintentar en un bucle continuo. Envíe un ping periódico para mantener la conexión activa y detectar desconexiones silenciosas de forma temprana.

// keepalive: send a ping on an interval over the shared socket
setInterval(() => socket.send(JSON.stringify({ ping: 1 })), 30000);

Limitación de velocidad y regulación de solicitudes

Limite las solicitudes salientes para mantenerse dentro de los límites de velocidad de la API. Ponga en cola y regule las llamadas en lugar de enviar grandes ráfagas, y aplique un anti-rebote a las acciones iniciadas por el usuario para que una sola interacción no se expanda en muchas solicitudes.

Si se le aplica un límite de velocidad, espere de forma exponencial antes de volver a intentarlo, aumentando el tiempo de espera tras cada rechazo. Prefiera las suscripciones sobre el sondeo para los datos que se actualizan continuamente, de modo que el servidor envíe los cambios en lugar de que usted los solicite de nuevo.

Cuando reintente una operación no idempotente, como una compra o un retiro, proporcione un ID de solicitud para poder consultar su estado final y conciliar el resultado, en lugar de reenviarla sin verificación y arriesgarse a un duplicado.

Para ver las cifras en sí — los límites de solicitudes por IP y por cuenta, y los presupuestos compartidos de los que se nutren los grupos de llamadas de WebSocket — consulte Límites.

Autenticación e higiene de tokens

Autentique una conexión una sola vez enviando authorize con un token válido antes de realizar solicitudes de ámbito de cuenta. Utilice tokens con el mínimo privilegio que requiere la tarea, solicitando únicamente los alcances que sus endpoints necesitan, como trade o account_manage; un token que carezca de un alcance requerido será rechazado con un error 403.

Para aplicaciones orientadas al usuario, utilice el flujo de código de autorización de OAuth 2.0 con PKCE en lugar de incrustar tokens. Realice siempre el intercambio de tokens en su backend, no en el navegador, y valide el parámetro state en el callback antes de utilizar el código de autorización. Los códigos de autorización son de un solo uso y tienen una vida útil corta, por lo que debe intercambiarlos de inmediato y nunca almacenarlos ni registrarlos. Genere un nuevo code_verifier y un nuevo state para cada solicitud, y elimínelos una vez que el intercambio se realice correctamente. Los tokens de acceso tienen una vida útil corta, generalmente de una hora, por lo que debe gestionar su vencimiento actualizando el token o volviendo a ejecutar el flujo de autorización en lugar de asumir que sigue siendo válido. Consulte la guía de OAuth 2.0 para la implementación completa.

Nunca incorpore tokens de API de larga duración en código del lado del cliente, repositorios públicos o artefactos de compilación. Almacene los secretos en el lado del servidor, rótalos con regularidad y revoque cualquier token que pueda haber quedado expuesto.

// authenticate the connection before account-scoped calls
socket.send(JSON.stringify({ authorize: "<your-token>" }));

Gestión de errores y limpieza de suscripciones

Inspeccione siempre el campo error en cada respuesta antes de utilizar sus datos, y registre el código y el mensaje de error en su propio sistema de registro. Relacione las respuestas con las solicitudes usando req_id para que un error se atribuya a la llamada correcta.

Libere las suscripciones que ya no necesite: use forget con un id de suscripción para detener un flujo individual, y forget_all por tipo de flujo para detener todos los flujos de ese tipo. La limpieza evita suscripciones no liberadas y tráfico innecesario.

// stop a single stream by its subscription id
socket.send(JSON.stringify({ forget: subscriptionId }));
// stop every stream of a given type
socket.send(JSON.stringify({ forget_all: "ticks" }));

Ciclo de vida del contrato

Una operación pasa por un ciclo de vida breve: solicite un precio con proposal, ejecútelo con buy, siga la posición abierta con proposal_open_contract y ciérrela con sell o déjela liquidar al vencimiento. Compre contra una propuesta reciente en lugar de una cotización desactualizada, ya que los precios tienen una vida útil corta. Pase un precio máximo en la llamada buy para que los movimientos entre la cotización y la ejecución no resulten en un peor precio de llenado.

Realice el seguimiento de cada contrato abierto suscribiéndose a proposal_open_contract en lugar de sondear portfolio. La suscripción envía actualizaciones de precio al contado y de ganancias, y activa los indicadores is_sold e is_expired en el momento en que el contrato se liquida.

Cuando is_sold pase a ser verdadero, llame a forget en esa suscripción para liberar el flujo y evitar fugas de suscripciones con el tiempo. Si una respuesta de buy se pierde o agota el tiempo de espera, reconcilie buscando la posición en portfolio o en proposal_open_contract antes de volver a intentarlo, para no comprar dos veces.

Antes de cerrar anticipadamente, verifique los indicadores propios del contrato: utilice sell solo cuando is_valid_to_sell sea verdadero, y use cancel únicamente dentro de la ventana de cancelación de operaciones para las transacciones compatibles. Para los tipos de contrato admitidos, establezca el stop loss y el take profit con contract_update para que las salidas se realicen en el servidor, en lugar de monitorear el flujo y vender manualmente.

// track an open contract, then release the stream once it settles
socket.send(JSON.stringify({
  proposal_open_contract: 1,
  contract_id: contractId,
  subscribe: 1,
}));

// on each update, when data.proposal_open_contract.is_sold is true:
//   socket.send(JSON.stringify({ forget: subscriptionId }));

Paginación

Para los endpoints que devuelven listas, solicite los datos por páginas en lugar de obtenerlos todos a la vez. Utilice los parámetros limit y offset para recorrer los resultados, y mantenga tamaños de página moderados para reducir la latencia y el uso de memoria.

Continúe solicitando páginas posteriores hasta que una página devuelva menos filas que el límite que solicitó, lo que indica que ha llegado al final del conjunto de datos.