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.

Para una conexión autenticada, solicite una URL de OTP nueva antes de cada reconexión. Cada URL funciona una sola vez.

// 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.

Puede conciliar las transferencias y retiros de agentes de pago mediante el ID de solicitud. Envíe un request_id único con cada uno y, si se pierde la respuesta, consulte su resultado con Transfer status o Withdrawal status en lugar de enviarlo de nuevo. Una compra no tiene búsqueda por ID de solicitud: req_id solo vincula una respuesta con su solicitud. Para evitar una compra duplicada, compre mediante el ID de propuesta: el mismo ID de propuesta no puede comprarse dos veces.

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

Solicite una URL autenticada WebSocket con POST /trading/v1/options/accounts/{accountId}/otp. Envíe su token en el encabezado Authorization: Bearer. Consulte la documentación de Opciones WebSocket para obtener más información.

Añada el encabezado Deriv-App-ID cuando use un token de acceso personal (PAT). Los tokens de acceso de OAuth 2.0 no necesitan este encabezado. Consulte la guía de autenticación para obtener más información.

Conéctese directamente a la URL en data.url. La URL contiene una contraseña de un solo uso (OTP), por lo que no necesita enviar un mensaje de autenticación después de conectarse.

La contraseña de un solo uso es válida durante 120 segundos y funciona una sola vez. Solicite una URL de OTP nueva antes de cada reconexión.

Use tokens con el menor privilegio que requiera la tarea; solicite únicamente los scopes que necesiten sus endpoints, como trade o account_manage; un token que no tenga un scope requerido se rechaza con un error 403.

Para aplicaciones orientadas al usuario, utilice el OAuth flujo de código de autorización 2.0 con PKCE en lugar de integrar tokens en el código. 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 de corta duración, por lo que debe intercambiarlos de inmediato y nunca almacenarlos ni incluirlos en registros. Genere un code_verifier y state nuevos para cada solicitud y elimínelos cuando el intercambio se complete correctamente. Los tokens de acceso vencen después del número de segundos indicado en expires_in. Deriv no emite tokens de actualización, por lo que ejecute de nuevo el flujo de autorización cuando un token venza o una llamada devuelva un error 401. Si un nuevo token de acceso también recibe un 401, no inicie el flujo de nuevo. En su lugar, revise el Authorization encabezado y el endpoint. Consulte la OAuth guía de 2.0 para conocer 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.

// Run this on your server, or in the browser only with a short-lived OAuth 2.0 access token.
// Never ship a Personal Access Token (PAT) in client-side code.
async function connectAuthenticated(accountId, token) {
  const response = await fetch(
    `https://api.derivws.com/trading/v1/options/accounts/${accountId}/otp`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        // Add this header for PAT authentication only:
        // "Deriv-App-ID": "<app-id>",
      },
    }
  );

  if (!response.ok) {
    throw new Error(`OTP request failed (${response.status})`);
  }

  const result = await response.json();
  const url = result?.data?.url;
  if (!url) {
    throw new Error("OTP response did not include a WebSocket URL");
  }

  return new WebSocket(url);
}

connectAuthenticated("<account-id>", "<token>");
// Request a fresh OTP URL before every reconnect.

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 acumular suscripciones con el tiempo.

Una buy respuesta con un objeto error significa que no se creó ningún contrato. Si la respuesta se pierde o se agota el tiempo de espera, consulte statement antes de enviar la compra nuevamente. Solicite action_type buy, un date_from justo antes de enviarlo y description configurado en 1. Haga coincidir la fila con su ID de aplicación, importe, shortcode y hora de la transacción; luego, consulte su contract_id con proposal_open_contract.

statement enumera cada compra ejecutada tan pronto como se confirma, por lo que si no hay una fila coincidente, no se compró ningún contrato. req_id solo vincula una respuesta con su solicitud. Un ID de propuesta no puede comprarse dos veces, pero una compra con parámetros no se elimina por duplicación, por lo que enviar buy: 1 de nuevo puede abrir un segundo contrato. Por eso, comprar mediante el ID de propuesta es la opción más segura.

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.