cripsy_binary_API v0.3.1 Repositorio Markdown

Qué es cripsy_binary_API

Qué es cripsy_binary_API

cripsy_binary_API es una API moderna, en Rust, para operar contra brókers de

opciones binarias. Diseñada desde cero, con estas propiedades:

API con llamadas bloqueantes, sin tokio ni await (solo IQ Option).

respuesta se correlaciona por request_id; los resultados de las órdenes

llegan por eventos.

IQ Option y Deriv integrados, con las capacidades exclusivas de IQ Option en

IqOptionExtras.

75 activos por sesión sin rechazos; Deriv entrega la cadencia del producto

(0,5–1 tick/s en la medición pública). Sin polling en ninguno de los dos.

pública.

Estado actual

IQ Option

ComponenteEstado
Autenticación y sesión (login + WSS + perfil)Listo, verificado contra el bróker
Catálogo de activos (binary, turbo y blitz)Listo, verificado contra el bróker
Velas históricas (hasta 1s × 7 días)Listo, verificado contra el bróker
Stream de velas multi-tamaño y ticksListo, verificado contra el bróker
Órdenes clásicas (turbo/binary)Listo, verificado en cuenta demo
Órdenes digitales (protocolo v2)Listo, verificado en cuenta demo
Órdenes blitz (protocolo v2)Listo, verificado en cuenta demo (apertura + cierre por evento)
Venta anticipada (buyback)Lista, verificada en cuenta demo
Perfil fundamental del activoListo, verificado contra el bróker
Historial de posicionesListo, verificado (PnL realizado)
Live-deals y comisionesSuscripción lista; el volumen de eventos depende del bróker
Resultados por evento y cachéListo, verificado en cuenta demo
Fachada sincrónica (SyncBroker)Lista, verificada contra el bróker
Indicadores técnicos del brókerCanal implementado; el bróker rechaza hoy todos los activos

Deriv

ComponenteEstado
Modo público (sin credenciales)Listo, verificado: catálogo, velas, payout y ticks
Sesión autenticada (OTP + App ID)Lista, verificada en cuenta demo
Compra y venta rise/fallListas, verificadas en cuenta demo
Cierre por evento e historialListos, verificados (profit_table paginado)
Reconexión con OTP nuevoLista, verificada (2 396 ms, replay de suscripciones)
Reconciliación de cierresLista, verificada con 72 s sin red y un solo evento
Blitz, digital, indicadores, live-dealsNo soportado; rechazo explícito

Qué no hace

bróker no los soporta. Puedes calcular los tuyos con el histórico y el stream.

construyas encima.

Cómo leer esta documentación

Todas las llamadas del trait Broker son async y devuelven

Result<_, BrokerError> (salvo name() e is_connected()).

GrupoDocumentoContenido
Generaldocs/01_introduccion.es.mdAlcance, estado y qué no hace
IQ Optiondocs/iqoption/01_cuenta/01_sesion_cuentas.es.mdConexión, cuentas demo/real y balances
IQ Optiondocs/iqoption/02_mercado/01_historicos.es.mdHistóricos, límites, velas en vivo, ticks y fachada sincrónica
IQ Optiondocs/iqoption/03_ordenes/01_binary.es.mdClásicas, digitales v2 y blitz
IQ Optiondocs/iqoption/04_operativa/02_reconexion.es.mdIndicadores del bróker y reconexión
Derivdocs/deriv/01_introduccion.es.mdAlcance, modos público/autenticado y estado
Derivdocs/deriv/02_cuenta/01_cuentas_identificadores.es.mdPAT, OTP, cuentas e identificadores
Derivdocs/deriv/03_mercado/01_catalogo_velas_ticks.es.mdCatálogo, velas, ticks, payout y densidad
Derivdocs/deriv/04_ordenes/01_rise_fall_historial.es.mdRise/fall, cierre por evento e historial
Derivdocs/deriv/05_operativa/01_reconexion_reconciliacion.es.mdReconexión y reconciliación de cierres
Derivdocs/deriv/06_limites/01_limites.es.mdCupos y capacidades no soportadas
Pythondocs/python/01_python.es.mdPyO3/maturin: instalación, superficie y límites
Generaldocs/herramientas/01_herramientas.es.mdInstalación, scripts y cómo añadir otro bróker

Requisitos

no necesita ninguna).

Limitaciones conocidas

reautentica, restaura perfil, catálogo y suscripciones, y lo informa con

Event::Disconnected y Event::Reconnected { intentos, downtime_ms }.

Mientras no hay socket, las llamadas devuelven BrokerError::NotConnected.

reenviarlas significaría operar con un mercado distinto al decidido.

datos ocurridos durante la caída se recuperan con el histórico, no por el

stream.

alimentada por eventos; no consulta al bróker. Sin el stream activo, una orden

puede quedarse en Pending.

activo; el parámetro de expiración no cambia la consulta. Los cambios en vivo

llegan por Event::PayoutChanged.

suscripción se retira en el siguiente despacho de velas.

el stream entrega Event::EventsLost { count } y continúa.

activo; hoy los rechaza para los activos probados.

de forma explícita en lugar de simularse.

Asset.opcode usan un sustituto determinista documentado.

Deriv

Deriv

Segundo bróker soportado, sobre la API moderna (developers.deriv.com):

REST para cuentas y OTP, WebSocket JSON para mercado y ejecución.

Alcance

activos que el bróker habilite.

consumidor puede analizar todo el mercado aunque solo opere rise/fall.

demás familias. No se simulan sobre rise/fall; se añadirán como tipos de

dominio cuando se amplíe el producto. No es una limitación técnica del

adaptador, es el alcance actual del contrato.

Dos modos

ModoRequisitosQué permite
Públiconingunocatálogo, velas, ticks y cotización de payout
AutenticadoPAT con scope trade (o OAuth) + App IDademás balance, compra, venta e historial

El modo público es el valor por defecto: si no hay token, la sesión no inventa

una cuenta ni permite operar. Las claves son tuyas y viven en .env (ignorado

por git); la plantilla está en .env.example.

Secciones

DocumentoContenido
docs/deriv/02_cuenta/01_cuentas_identificadores.es.mdConexión, PAT, OTP, cuentas y sustitutos deterministas
docs/deriv/03_mercado/01_catalogo_velas_ticks.es.mdCatálogo, velas, ticks, payout y densidad medida
docs/deriv/04_ordenes/01_rise_fall_historial.es.mdCompra/venta rise/fall, cierre por evento e historial
docs/deriv/05_operativa/01_reconexion_reconciliacion.es.mdOTP nuevo, replay de suscripciones y reconciliación
docs/deriv/06_limites/01_limites.es.mdCupos, capacidades no soportadas e identificadores

Estado verificado

ComponenteEstado
Modo público (sin credenciales)Verificado: catálogo, velas, payout y ticks
Sesión autenticada (OTP + App ID)Verificada en cuenta demo
Compra y venta rise/fallVerificadas en cuenta demo
Cierre por evento e historialVerificados (profit_table paginado)
Reconexión con OTP nuevoVerificada (2 396 ms, replay de suscripciones)
Reconciliación de cierresVerificada con 72 s sin red y un solo evento
Blitz, digital, indicadores, live-dealsNo soportado; rechazo explícito

Qué no hace

mercado.

Cuentas e identificadores

Cuentas e identificadores

Conexión

use cripsy_binary_api::broker::{Broker, BrokerParams, DerivBroker, DerivConfig};

// Solo mercado (gratuito, sin credenciales).
let broker = DerivBroker::connect(BrokerParams::Deriv(DerivConfig::publico())).await?;

// Cuenta demo o real: el OTP se pide por REST y la URL del socket es efímera.
let broker = DerivBroker::connect(BrokerParams::Deriv(DerivConfig {
    token: std::env::var("DERIV_TOKEN").ok(),
    app_id: std::env::var("DERIV_APPID").ok(),
    account_id: std::env::var("DERIV_ACCOUNT_ID").ok(),
    ..DerivConfig::default()
})).await?;

nuevo. La API lo hace sola: tú no ves ni gestionas el OTP.

Variables de entorno

DERIV_TOKEN = "tu-token-con-scope-trade"
DERIV_APPID = "tu-app-id"
DERIV_ACCOUNT_ID = "DOT00000000"

DERIV_ACCOUNT_ID es opcional si la cuenta activa del token ya es la correcta.

Las claves se leen del entorno y nunca se imprimen ni se serializan.

Cuentas

Deriv identifica cuentas con cadenas (DOT…, VRTC… demo; CR… real). Hasta

que el contrato admita cadenas, Session.balance_id y AccountBalance.id

exponen un sustituto determinista documentado, y Asset.opcode es 0

porque Deriv no publica identificador numérico. Usa symbol/account_id.

El modo demo o real lo determina la cuenta asociada al token; no se elige con

AccountSelection como en IQ Option. session() y get_balance() devuelven la

cuenta activa y su saldo. switch_account no está soportado por el adaptador:

Deriv no ofrece ese cambio en esta integración.

Mercado: catálogo, velas y ticks

Mercado: catálogo, velas y ticks

Capacidades

OperaciónMétodoEstado
Catálogo de activoslist_assetsverificado
Estado de mercadoasset_statusverificado
Velas históricasget_candlesverificado (granularidades 1 m – 1 d)
Velas en vivosubscribe_candlesimplementado
Ticks nativossubscribe_ticks → Event::PriceTickverificado
Payout cotizadoget_payoutverificado

El histórico de Deriv no ofrece velas de 1 segundo en esta integración: la

granularidad mínima es 1 minuto y la máxima 1 día. El límite de velas por

petición lo aplica el bróker.

Velas

let velas = broker.get_candles(CandleRequest {
    symbol: "R_100".into(),
    interval: 60,
    count: 100,
    end_time: None,
}).await?;

interval va en segundos y end_time es el inicio de una vela cerrada. La

suscripción en vivo usa CandleSubscribe y entrega solo el tamaño pedido.

Ticks nativos

broker.subscribe_ticks("R_100").await?;
let mut eventos = broker.events().await?;
while let Some(ev) = eventos.next().await {
    if let Event::PriceTick { symbol, tick } = ev {
        // tick.price, tick.bid, tick.ask, tick.at_ms
    }
}

No hay polling: se entrega el stream del bróker tal cual.

Payout

get_payout(symbol, seconds) devuelve la cotización publicada para el activo y

la duración pedida. No se consulta por importe ni por strike; el importe se elige

al comprar y el bróker puede rechazarlo según sus mínimos y máximos.

let payout = broker.get_payout("R_100", 60).await?;
println!("{} %", payout.profit_percent);

Densidad medida

Gateway público, ventana de 8 s, 9 de noviembre de 2026:

ActivoClaseTicksDensidadHueco medio
R_100índice sintético4~0,5/s1 993 ms
1HZ100Víndice sintético 1 s81,0/s998 ms
1HZ10Víndice sintético 1 s81,0/s1 002 ms
frxAUDCADforex81,0/s1 002 ms
cryBTCUSDcripto81,0/s998 ms
frxXAGUSDmateria prima6–80,75–1,0/s1 000–1 183 ms

La cadencia es del producto (el índice de 2 s entrega uno cada 2 s) y el

gateway público agrega forex y cripto a ~1 tick/s. No es polling: se

entrega el stream del bróker tal cual. Con credenciales, la densidad puede

variar; se documentará cuando se mida.

Órdenes rise/fall e historial

Órdenes rise/fall e historial

Compra

use cripsy_binary_api::domain::{BuyBinaryRequest, Direction, OptionType};

let id = broker.buy_binary(BuyBinaryRequest {
    symbol: "R_100".into(),
    amount: 1.0,
    direction: Direction::Call,
    expiration_minutes: 1,
    option_type: OptionType::Binary,
}).await?;

expiration_minutes se expresa en minutos. El adaptador valida que el activo

esté abierto y que el importe respete el mínimo publicado; el máximo lo aplica

el bróker.

Cierre por evento

El resultado llega por el stream de eventos, no por polling:

let mut eventos = broker.events().await?;
while let Some(ev) = eventos.next().await {
    if let Event::OrderClosed { id, result } = ev {
        // result: Win(neto) | Loss(monto) | Equal(monto) | Pending
    }
}

get_operation_result(&id) lee la caché alimentada por esos eventos. Sin stream

activo una orden puede permanecer en Pending.

Venta anticipada

broker.sell_option(&id).await?;

El bróker la admite dentro de su ventana de venta; si ya no es vendible responde

con su mensaje de rechazo.

Historial

get_position_history(symbol, limit, offset) consulta profit_table paginado.

limit es el tamaño de página y offset el desplazamiento. El PnL se deriva de

los importes que publica el bróker y se conserva la diferencia entre observado y

derivado.

Reconciliación

Si el contrato cierra sin conexión, al volver se consulta su estado y, si ya no

está activo, el historial paginado. El cierre se publica una sola vez como

Event::OrderClosed. Ver docs/deriv/05_operativa/01_reconexion_reconciliacion.es.md.

Fuera de alcance

buy_blitz, buy_digital_spot, indicadores técnicos, perfil de activo, live

deals y comisiones no están soportados por Deriv y se rechazan de forma

explícita; no se simulan sobre rise/fall.

Reconexión y reconciliación

Reconexión y reconciliación

Qué ocurre cuando cae el socket

  1. Se emite Event::Disconnected con el motivo observado.
  2. La sesión pide un OTP nuevo por REST (el anterior es de un solo uso) y

vuelve a autenticarse.

  1. Restaura la sesión y el balance, y reproduce las suscripciones de velas y

ticks.

  1. Se emite Event::Reconnected { intentos, downtime_ms }.

Medición en una caída forzada: 1 intento y 2 396 ms sin conexión, con vela

recibida después de volver.

Peticiones durante la caída

Mientras no hay socket, buy_binary, sell_option y las suscripciones devuelven

BrokerError::NotConnected. No se encola nada: diferir una orden cambia el

mercado y el resultado. Las órdenes en vuelo se descartan con error y no se

reenvían.

Reconciliación de cierres

Una orden se abre y queda pendiente. Si su cierre ocurre durante la caída, el

evento nunca llega; al reconectar la sesión consulta el estado del contrato y,

si ya no está activo, el historial paginado:

devuelto.

Verificado con 72 s sin red: un solo OrderClosed Loss(1.0) y delta de

balance −1,00, sin reenviar la orden.

Límites

La reconciliación recorre páginas del historial y se detiene al encontrar los

cierres pendientes. Un cierre más antiguo que la ventana consultada exige leer

get_position_history explícitamente. Si el historial no responde, la

reconexión continúa y las órdenes afectadas quedan como estaban.

Límites y capacidades no soportadas

Límites y capacidades no soportadas

Cupos del bróker

GrupoPor minutoPor hora
proposal, proposal_open_contract, buy, sell36014 400
balance, statement1002 000
portfolio, profit_table301 500
Resto (contracts_for, velas, símbolos)22014 400

La API aplica el 80 % de cada cupo y espera en vez de fallar. Un RateLimit

del bróker nunca provoca el reenvío de una orden.

Capacidades no soportadas

CapacidadRespuesta
Blitz, digitales, multiplicadores, acumuladores, dígitos, barrerasUnsupported / rechazo explícito
Indicadores técnicosno ofrecidos por esta integración
Perfil de activono ofrecido
Live deals y comisionesno ofrecidos
Fachada sincrónica SyncBrokerexclusiva de IQ Option

SyncBroker no se extiende a Deriv: existe para consumidores heredados de IQ

Option y Deriv mantiene la API async. No es una limitación pendiente, es una

decisión de compatibilidad.

Identificadores

Datos medidos

La densidad de ticks se midió con el gateway público y ventana de 8 s. No se

extrapola a cuentas autenticadas ni a horario de mercado pleno; cuando se mida,

se documentará con la misma distinción entre observado y derivado.

Herramientas del proyecto

Herramientas del proyecto

Todo lo necesario para instalar, verificar y desarrollar está en tres lugares:

listos para usar. Los globales quedan en la raíz; los de cada bróker viven en

scripts/iqoption/ y scripts/deriv/.

Instalación guiada

.\installation\install.ps1

El instalador, pidiendo tu aprobación en cada paso:

  1. Verifica el entorno (check_env.ps1): Rust, cargo, git y .env.
  2. Si falta una herramienta, ofrece instalarla (rustup por winget o descarga

oficial) — solo si apruebas.

  1. Compila la librería en modo release, en sus dos variantes (async y blocking).
  2. Crea .env a partir de .env.example para tus credenciales.
  3. Genera la documentación navegable y, si lo apruebas, ejecuta

ejemplo_lectura para comprobar la conexión (solo lectura).

  1. Escribe docs/site/installed.js con el estado: el portal index.html

detecta la instalación por ese archivo.

Verificación sin instalar

.\installation\check_env.ps1

Compuerta de calidad

.\scripts\verify.ps1

Ejecuta cargo fmt --check, cargo clippy --all-targets -- -D warnings,

cargo test, el build de la variante blocking y la generación de la

documentación. Es el estándar mínimo antes de dar un cambio por bueno.

Regenerar la documentación navegable

.\scripts\build_docs.ps1 -Lang es

Convierte docs/**/*.es.md en un único HTML navegable en docs/site/es/. El

punto de entrada es index.html en la raíz del proyecto. El Markdown es la

fuente de verdad; el HTML es generado y nunca se edita a mano.

Para leerlo: en VS Code instala la extensión Live Server (Go Live) y pulsa

*Go Live* sobre el index.html; o abre el archivo con doble clic, porque

funciona también sin servidor (file://, navegación por hash y sin fetch).

Scripts listos para usar

Los scripts globales y los de cada bróker leen tus credenciales de .env y

operan en cuenta demo:

ScriptBrókerQué hace
scripts\verify.ps1—Compuerta: fmt, clippy, tests, blocking y documentación
scripts\build_docs.ps1—Genera el HTML navegable desde Markdown
scripts\verificar_todo.ps1AmbosEjecuta los dos verificadores en secuencia
scripts\iqoption\conectar.ps1IQ OptionSesión, balance, catálogo, velas y stream (solo lectura)
scripts\iqoption\balance.ps1IQ OptionBalance, tipo de cuenta y balance_id
scripts\iqoption\operar.ps1IQ OptionOrden de 1 USD en demo y cierre por evento (pide confirmación)
scripts\iqoption\verificar_iqoption.ps1IQ OptionValida sus capacidades y reporta [OK]/[FALLO]
scripts\deriv\verificar_deriv.ps1DerivPúblico, ticks, densidad, órdenes y caídas en demo
.\scripts\iqoption\verificar_iqoption.ps1            # IQ Option, incluye órdenes demo
.\scripts\iqoption\verificar_iqoption.ps1 -SoloLectura
.\scripts\deriv\verificar_deriv.ps1                  # Deriv, incluye órdenes y caídas
.\scripts\deriv\verificar_deriv.ps1 -SoloLectura     # solo mercado y ticks
.\scripts\verificar_todo.ps1                         # ambos

Cada carpeta de bróker incluye su cargador de .env (_env.ps1 en IQ Option,

_env_deriv.ps1 en Deriv). Son internos: no hace falta invocarlos a mano.

verificar_deriv.ps1 usa el modo público si no hay token; para operar exige

DERIV_TOKEN y DERIV_APPID en .env.

Probar contra el bróker

Los ejemplos leen las credenciales del entorno y operan en cuenta demo:

cargo run --example ejemplo_lectura     # IQ Option: sesión, catálogo, velas y stream
cargo run --example ejemplo_sincrono    # IQ Option: el mismo consumo, bloqueante
cargo run --example ejemplo_orden_demo  # IQ Option: compra demo y cierre
cargo run --example verificar_todo      # IQ Option: verificación integral

cargo run --example deriv_conectar      # Deriv: público o cuenta demo
cargo run --example deriv_ticks         # Deriv: ticks nativos y reconexión
cargo run --example deriv_densidad      # Deriv: densidad por activo
cargo run --example deriv_orden_demo    # Deriv: compra/venta demo
cargo run --example deriv_reconciliacion # Deriv: cierre ocurrido sin red

ejemplo_orden_demo mueve saldo de práctica: ejecútalo solo si eres el dueño de

la cuenta o tienes autorización explícita.

Agregar otro bróker

  1. Crear src/broker/<nombre>/ con su Config (añadir la variante a

BrokerParams).

  1. Implementar el trait Broker (async) y subscribe_ticks.
  2. Escribir el mapper dominio ↔ protocolo del bróker.
  3. Si hay capacidades exclusivas, exponerlas en un trait propio (como

IqOptionExtras) en vez de ampliar Broker.

  1. Registrar en BrokerRegistry y añadir su verificador en

scripts/<nombre>/.

No se modifica ni el dominio ni el transporte: los brókers nuevos se añaden

como adaptadores.

Garantía y descargo

La API expone el contrato listo para mostrar desde tu código:

use cripsy_binary_api::{mensaje_consumidor, revisar_config};

println!("{}", mensaje_consumidor());
let reporte = revisar_config(&tu_config);
for aviso in &reporte.advertencias {
    eprintln!("aviso de uso: {aviso}");
}

Si sigues el flujo documentado, lo documentado funciona. Cualquier otro uso

queda fuera de la garantía: ver la sección «Garantía y descargo» del README.md.

Sesión y cuentas

Sesión y cuentas

Conectar

La conexión combina un login HTTP y un WebSocket:

  1. POST https://auth.iqoption.com/api/v2/login con {identifier, password}.

La respuesta trae la cookie ssid (también en el cuerpo).

  1. Se abre wss://iqoption.com/echo/websocket y se envía

{"name":"ssid","msg":"<SSID>"} como primer mensaje.

  1. El bróker responde con profile, que incluye los balances y el

balance_id activo.

La sesión queda operativa cuando el catálogo de activos se ha recibido

(get-initialization-data v3.0).

Cuentas: demo y real

El perfil contiene varias cuentas. El tipo se identifica por balance.type:

typeCuenta
1Real
4Demo (practica)
otrostratados como real

Al conectar puedes elegir la cuenta con AccountSelection:

let config = IqOptionConfig {
    email: std::env::var("IQOPTION_EMAIL")?,
    password: std::env::var("IQOPTION_PASSWORD")?,
    account: AccountSelection::Practice,  // demo explícita
    ..IqOptionConfig::default()
};

let broker = IqOptionBroker::nuevo(BrokerParams::IqOption(config)).await?;

Consultas disponibles

Todas son async y devuelven Result<_, BrokerError>:

LlamadaQué devuelve
session().await?Copia de la sesión activa (balance_id, tipo de cuenta, offset de hora)
get_balance().await?Monto, moneda y tipo de la cuenta activa
get_account_type().await?Practice o Real
switch_account(kind).await?Cambia a demo/real (api_profile_changebalance)
list_assets().await?Todos los activos del catálogo
asset_status(symbol).await?Open / Closed / Suspended según el bróker

Nota sobre el catálogo: el bróker publica el mismo símbolo en hasta tres grupos

(binary, turbo y blitz) con metadatos distintos entre ellos. El catálogo

contiene una entrada por grupo; para operar blitz usa la de

AssetClass::Blitz (ver la sección 06).

Notas importantes

reloj local.

solo cuando la demo es la cuenta activa.

Eventos de comisiones y operaciones de terceros

Dos canales más, ambos con suscripción explícita (los eventos salen por

broker.events()):

// Comisiones por tipo de instrumento (binary-option, turbo-option, digital-option)
broker.subscribe_commission_changes().await?;
while let Some(ev) = broker.events().await?.next().await {
    if let Event::CommissionChanged(c) = ev {
        // c.symbol, c.instrument_type, c.commission_value
    }
}

// Operaciones de terceros (live-deal) para un activo concreto
broker.subscribe_live_deals("EURUSD-OTC").await?;
while let Some(ev) = broker.events().await?.next().await {
    if let Event::LiveDeal(deal) = ev {
        // deal.symbol, deal.direction, deal.amount, deal.created_at
    }
}

puntos (payout = 100 − comisión).

(operaciones de otros usuarios: señal de flujo del mercado).

no llegar nada (verificado en vivo: suscripción aceptada, 0 eventos en

ventana de fin de semana).

Históricos: límites verificados

Históricos: límites verificados

Los datos históricos se piden con get_candles(...). Los límites están

verificados en vivo contra el bróker (2026-10-27):

Tamaño de velaProfundidad máxima
1 segundo7 días exactos (a 14 días: 0 velas)
1 minutoentre 45 y 90 días
5 minutosentre 270 y 330 días
15 min, 1 h, 4 h, 1 díamás de 2 años

Reglas prácticas:

broker::historico::ultimo_cierre(ahora, intervalo), que resta un paso al

múltiplo del intervalo; con to dentro de la vela en curso la respuesta llega

vacía.

Tamaños disponibles: 1, 5, 15, 30, 60, 300, 900, 3600, 14400 y 86400 s.

Descargar toda la semana en velas de 1 s

Iterando end_time hacia atrás, count × interval segundos por petición:

let mut fin = None;
loop {
    let velas = broker.get_candles(CandleRequest {
        symbol: "USDZAR-OTC".into(),
        interval: 1,
        count: 1000,
        end_time: fin,
    }).await?;
    if velas.is_empty() { break; }
    fin = Some(velas.last().unwrap().from);
    // ~605 peticiones cubren los 7 días completos de este activo
}

El protocolo también permite paginar por id (to_id), pero nuestra API aún

no lo expone: la descarga se hace iterando end_time hacia atrás.

Nota sobre densidad en histórico

El histórico es de velas: no existe densidad de tick en el pasado. La

granularidad fina máxima es la vela de 1 segundo. Para densidad intrasegundo

hay que usar el stream en vivo (ver la próxima página).

Stream en vivo: velas multi-tamaño y ticks

Stream en vivo: velas multi-tamaño y ticks

Dos mecanismos nativos, sin polling:

1. Velas en vivo (subscribe_candles)

Una única suscripción entrega todos los tamaños de vela de un activo

(1 s, 5 s, 1 m, 5 m, ... hasta diario). El adaptador filtra por el tamaño

pedido: interval = 0 significa "todos los tamaños".

let mut stream = broker.subscribe_candles(CandleSubscribe {
    symbol: "USDZAR-OTC".into(),
    interval: 60,           // velas de 1 minuto
}).await?;

while let Some(vela) = stream.next().await {
    let vela = vela?;       // Candle { from, to, open, close, high, low, volume }
    // estrategia...
}

2. Ticks de precio (Event::PriceTick)

Cada mensaje del stream trae el precio spot (value, bid, ask) con marca

temporal en nanosegundos. La sesión lo emite como evento:

let mut eventos = broker.events().await?;
while let Some(ev) = eventos.next().await {
    if let Event::PriceTick { symbol, tick } = ev {
        // tick.price, tick.bid, tick.ask, tick.at_ms
    }
}

El bus de eventos tiene buffer acotado (1024 eventos). Si tu consumidor se

atrasa más que el buffer, se descartan los eventos intermedios y el stream

entrega Event::EventsLost { count } con la cuenta de los perdidos; el stream

sigue abierto. Consume sin bloqueos largos entre lectura y lectura.

Medido en vivo en IQ Option (2026-10-27, varios mercados OTC):

Activo (mercado)Mensajes/sCambios de precio/s
XAUUSD-OTC (materia prima)3.673.20
ETHUSD-OTC (cripto)3.402.80
EURUSD-OTC (forex)3.202.67

Hallazgos clave:

multi-tamaño o un tamaño específico: da igual.

midieron 61 mensajes/s (3.07 por activo).

  1. No se probó por encima de esa

cifra, así que no se documenta un techo.

ejemplos miden mercados OTC de fin de semana.

3. Densidad en Deriv

La densidad medida, la cadencia por producto y los detalles de ticks de Deriv

están en docs/deriv/03_mercado/01_catalogo_velas_ticks.es.md.

Sin sondeo

Cada mensaje del WebSocket se procesa al instante y se emite como evento: no

hay bucles de consulta ni latencia artificial añadida. La densidad que mides es

la que el bróker publica.

Fachada sincrónica e histórico

Fachada sincrónica e histórico

La API ofrece el mismo núcleo de dos formas. Si tu proyecto no es async, usa la

fachada bloqueante: no necesitas tokio ni await.

Fachada sincrona

use cripsy_binary_api::broker::config::{AccountSelection, BrokerParams, IqOptionConfig};
use cripsy_binary_api::broker::sync::SyncBroker;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cfg = IqOptionConfig {
        email: std::env::var("IQOPTION_EMAIL")?,
        password: std::env::var("IQOPTION_PASSWORD")?,
        account: AccountSelection::Practice,
        ..IqOptionConfig::default()
    };

    let mut broker = SyncBroker::connect(BrokerParams::IqOption(cfg))?;

    // Todo bloqueante, misma semántica que la versión async.
    let balance = broker.get_balance()?;
    println!("balance: {} {}", balance.amount, balance.currency);

    let activos = broker.list_assets()?;
    let abierto = activos
        .iter()
        .find(|a| a.symbol.ends_with("-OTC") && a.status == cripsy_binary_api::domain::MarketStatus::Open)
        .expect("OTC abierto");

    // Streams como iteradores bloqueantes.
    let mut velas = broker.subscribe_candles(cripsy_binary_api::domain::CandleSubscribe {
        symbol: abierto.symbol.clone(),
        interval: 60,
    })?;
    if let Some(v) = velas.next() {
        println!("vela en vivo: {:?}", v?);
    }

    let mut eventos = broker.events()?;
    for ev in eventos.take(5) {
        println!("evento: {ev:?}");
    }

    broker.disconnect()?;
    Ok(())
}

Reglas:

del llamador. En async, usa el trait Broker directamente.

iterador se cierra (vuelve a suscribirte si lo necesitas).

eventos, igual que en async.

Métodos disponibles (todos bloqueantes): session, is_connected,

disconnect, get_balance, get_account_type, switch_account,

list_assets, asset_status, get_candles, subscribe_candles,

get_position_history, get_payout, get_asset_profile,

get_technical_indicators, subscribe_live_deals,

subscribe_commission_changes, events, buy_binary,

buy_digital_spot, sell_option, get_operation_result.

Ayudante de histórico

cripsy_binary_api::broker::historico facilita descargar el histórico granular

(límites verificados: 1 s × 7 días, 1000 velas por página):

ElementoPara qué sirve
VELAS_POR_PAGINATamaño de página recomendado (1000)
PAGINAS_MAXIMASTecho de seguridad para no bucles infinitos (5000)
VentanaRango con count máximo ya contemplado
ultimo_cierre(ahora, intervalo)Último cierre de vela cerrada (multiplo del intervalo)
paginas_estimadas(intervalo, desde, hasta)Cuántas páginas pedirá la descarga
faltantes(velas, intervalo)Huecos detectados en una página
descargar(...)Descarga completa con paginación

Ejemplo:

use cripsy_binary_api::broker::historico::{descargar, paginas_estimadas};

// Antes de descargar, sabe cuánto costará:
let paginas = paginas_estimadas(1, desde_epoch, hasta_epoch);

// Descarga completa con paginación (devuelve una Ventana con las velas).
let ventana = descargar(
    &broker,               // &dyn Broker (async)
    "USDZAR-OTC",
    1,                     // intervalo: 1 segundo
    desde_epoch,           // epoch segundos
    hasta_epoch,           // epoch segundos
).await?;

println!("{} velas en {} páginas", ventana.velas.len(), ventana.paginas);

Con size=1 y el límite de 7 días del bróker, una semana completa de un activo

son ~605 páginas de 1000.

Opciones clásicas (turbo / binary)

Opciones clásicas (turbo / binary)

Las clásicas usan el mensaje binary-options.open-option v1.0. La

clasificación la hace la duración, igual que la plataforma:

La expiración se calcula con la tabla de minutos/cuartos de hora del bróker:

la API reproduce la lógica verificada (candidatos de minuto para turbo, de

cuarto de hora con 5 minutos de margen para binary) y elige el más cercano a

la duración pedida.

Llamada

let orden = broker.buy_binary(BuyBinaryRequest {
    symbol: "USDZAR-OTC".into(),
    amount: 1.0,
    direction: Direction::Put,
    expiration_minutes: 1,
    option_type: OptionType::Binary,
}).await?;

El bróker confirma con buyComplete; la orden queda identificada por

OrderId.

Ciclo de vida por eventos

El resultado llega por eventos, no por polling:

  1. option-opened — apertura tipada (option_type, option_type_id, montos).
  2. option-closed — resultado final con result (win/loose/equal) y montos.
  3. socket-option-closed — evento equivalente con el detalle micro-unitario.
let mut eventos = broker.events().await?;
while let Some(ev) = eventos.next().await {
    if let Event::OrderClosed { id, result } = ev {
        println!("orden {id}: {result:?}");
    }
}

get_operation_result(&id) consulta el cache alimentado por esos eventos

(siempre disponible, sin latencia de red).

Validaciones antes de enviar

publica; el máximo lo aplica el bróker (responde con su mensaje de rechazo).

grupo blitz (expiration_times ∪ rollovers).

Opciones digitales

Opciones digitales

Las digitales usan el protocolo v2: la compra se arma con el instrumento

que publica el stream de precios del bróker.

Flujo

  1. Suscribirse a price-splitter.client-price-generated (el adaptador lo hace

solo al comprar).

  1. Esperar el mensaje del periodo deseado y tomar la entrada spot

(strike == "SPT"): de ahí salen call.symbol o put.symbol (el

instrument_id) y el instrument_index.

  1. Enviar digital-options.place-digital-option v2.0 con:
{
  "user_balance_id": <id_de_tu_perfil>,
  "instrument_id": "do1380A20261027D002400T1MCSPT",
  "asset_id": 1380,
  "instrument_index": 4046465,
  "amount": "1.0"
}

Detalles que el bróker exige (verificados en vivo):

INVALID_SCHEMA.

instrumento: los índices rotan.

bad quote (status 4008).

Llamada

let orden = broker.buy_digital_spot(BuyDigitalRequest {
    symbol: "USDZAR-OTC".into(),
    amount: 1.0,
    direction: Direction::Call,
    duration_minutes: 1,
    strike: 0.0,   // lo elige el price-splitter
}).await?;

Resultado

Las digitales cierran por el canal de cartera position-changed, no por

option-closed como el resto. El adaptador correlaciona la orden por

instrument_id y emite Event::OrderClosed igual que las demás, así que el

consumidor no ve la diferencia:

if let Event::OrderClosed { id, result } = /* ... */ {
    // result: Win(neto) | Loss(monto) | Equal(monto) | Pending
}

El resultado también queda en el cache: get_operation_result(&id) devuelve

el mismo valor sin consultar al bróker (sin polling).

Semántica de montos

ganancia), no la ganancia.

(1 000 000 = 1 USD); sum es la inversión legible.

Opciones blitz

Opciones blitz

Blitz es el tipo más nuevo del protocolo (option_type_id 12, mensaje

binary-options.open-option v2.0) y tiene sus propias reglas. Los errores

de implementación típicos se documentan aquí porque el bróker los reporta con

mensajes engañosos.

Reglas verificadas

  1. El grupo blitz tiene metadatos propios. El mismo símbolo aparece en

binary, turbo y blitz con duraciones distintas (binary declara

[900]; blitz [30, 45, 60, 120, 180, 300], y los rollovers añaden

  1. Resuelve el activo contra el grupo blitz (AssetClass::Blitz),

nunca contra binary.

  1. expired debe ir alineado al múltiplo de la duración:

(ahora_servidor / duracion + 1) * duracion. Un expired desalineado

recibe active is suspended — que parece un estado del mercado pero es un

error de forma.

  1. profit_percent va como entero (el bróker rechaza "86.0").

Llamada

let orden = broker.buy_binary(BuyBinaryRequest {
    symbol: "USDZAR-OTC".into(),
    amount: 1.0,
    direction: Direction::Call,
    expiration_minutes: 30,        // para blitz: SEGUNDOS (ver nota)
    option_type: OptionType::Blitz,
}).await?;

Nota de nomenclatura: en BuyBinaryRequest, el campo expiration_minutes

transporta segundos cuando option_type es Blitz (las duraciones del

catálogo blitz están en segundos).

Rollovers

La respuesta de apertura del bróker trae rollover_params (deadtime,

limit, offset, offset_from_expiration, amount_multiplier): son los

parámetros de renovación automática que el bróker aplica a la orden. Hoy

buy_binary devuelve solo el OrderId; los parámetros de rollover viajan en

la respuesta del bróker pero no se exponen aún en la API pública.

Estado actual

Blitz está verificado de extremo a extremo en cuenta demo: apertura

(status 2000, type: "blitz", respuesta con rollover_params) y cierre por

evento con resultado y delta de balance coincidente.

El bróker puede reportar active is suspended / `asset is not available at the

moment` para activos concretos: es un estado por activo que el bróker

decide (OTC blitz opera 24/7, no es cierre de mercado). Si recibes ese error,

prueba otro activo o más tarde; el mensaje de error es literalmente el del

bróker.

Si una compra blitz se rechaza, revisa antes tu petición: las causas

confirmadas fueron duración no admitida por el grupo blitz y expired

desalineado (arriba), no el estado del mercado.

Indicadores técnicos del bróker

Indicadores técnicos del bróker

La respuesta corta

El bróker sí tiene un canal de indicadores técnicos, pero hoy rechaza todos

los activos. Nuestra API lo implementa igual: cuando el bróker lo habilite,

funciona sin cambios.

Qué se verificó

El canal existe y responde con mensajes tipados:

v1.0 y body {"id": <active_id>}.

del bróker) o msg.message de error.

Errores observados en la validación (2026-10-27):

PruebaRespuesta del bróker
Varias docenas de activos (OTC y no-OTC, abiertos y cerrados)Active is not supported: active id 'X' (status 4150)
id como textoINVALID_SCHEMA (debe ser entero)
versión 2.0sin respuesta

Es decir: el canal está vivo pero el servicio no entrega indicadores a esta

cuenta/estado actual. No es un problema de formato.

Cómo usarlo cuando esté disponible

let indicadores = broker.get_technical_indicators("EURUSD-OTC").await?;
// indicadores.indicators trae la forma libre del bróker

La API es de transporte: no calcula ni configura indicadores, entrega lo

que el bróker publique. Si el bróker no soporta el activo, recibes

BrokerError::Rejected con el mensaje textual del bróker.

Alternativa: calcular los tuyos

Si prefieres no depender del canal, puedes calcular indicadores a partir de:

Event::TopAssetUpdated vienen del bróker como señales adicionales.

Con velas de 1 segundo reconstruidas desde el histórico puedes alimentar

cualquier indicador (medias, RSI, bandas, pivotes) con resolución de un segundo.

Reconexión de sesión

Reconexión de sesión

Desde la versión 0.2.0 la sesión no se queda caída cuando el WebSocket se

interrumpe: una tarea supervisora la restablece y el consumidor recibe el aviso

por el mismo stream de eventos que ya usa.

Qué ocurre cuando cae la conexión

  1. El bucle de despacho termina y se descartan las peticiones en vuelo

(fail_all), de modo que ninguna espera queda colgada hasta su timeout.

  1. Se emite Event::Disconnected { motivo } con el motivo observado: error de

lectura, error de escritura o cierre por parte del bróker.

  1. La sesión vuelve a autenticarse con las credenciales de la configuración y

abre un WebSocket nuevo con reintentos y backoff exponencial

(backoff_base_ms … backoff_max_ms).

  1. Con el socket nuevo se rehace el handshake: ssid → perfil (sesión y

balances) y datos de inicialización (catálogo de activos).

  1. Se reproduce el registro de suscripciones completo.
  2. Se emite Event::Reconnected { intentos, downtime_ms } y el despacho

continúa.

Los streams de velas entregados antes de la caída siguen siendo válidos: no

se cierran y vuelven a recibir datos cuando la suscripción se reproduce.

Peticiones durante la caída

Mientras no hay socket, solicitar y las suscripciones devuelven

BrokerError::NotConnected de inmediato. No se encola nada a propósito: una

orden guardada para más tarde se ejecutaría contra un mercado distinto del que

motivó la decisión, que en opciones binarias con expiración corta cambia el

resultado por completo.

La cola de salida está acotada (TransportConfig::cola_salida, 256 por

defecto). Si el productor supera esa capacidad sin que el socket consuma, la

llamada espera en lugar de crecer en memoria sin límite.

Credenciales rechazadas

Un fallo de autenticación es terminal: la reconexión se abandona y la sesión

queda cerrada. Reintentar el login en bucle es la forma más rápida de que el

bróker bloquee la cuenta, así que el supervisor no lo hace. Los fallos de red o

de handshake sí se reintentan.

Personalización

use cripsy_binary_api::broker::config::{IqOptionConfig, TransportConfig};

let cfg = IqOptionConfig {
    transport: TransportConfig {
        backoff_base_ms: 250,   // primera espera
        backoff_max_ms: 8_000,  // techo
        cola_salida: 256,       // capacidad de la cola de salida
        ..TransportConfig::default()
    },
    ..IqOptionConfig::default()
};

Reconciliación de cierres

Una orden se abre y se registra como pendiente. Si su cierre ocurre durante la

caída, el evento nunca llega; al reconectar la sesión consulta el historial de

posiciones del balance activo y recupera esos cierres:

Un cierre ajeno no aparece en la caché del consumidor.

normal, así que el consumidor no necesita una ruta distinta.

devuelto, calculados desde el PnL de la posición.

La consulta es paginada (100 posiciones por página, hasta 10 páginas) y se

detiene en cuanto encuentra todos los cierres pendientes: una sesión caída

durante horas no bloquea el despacho recorriendo el historial completo.

Si el historial no responde, la reconexión continúa y se registra el aviso en

tracing; las órdenes afectadas quedan como estaban.

Qué no resuelve

aceptada por el bróker sí se reconcilia al volver.

por el stream; se recuperan con get_candles o la descarga paginada.

hasta 10 páginas de 100 posiciones y se detiene al encontrar lo que busca o

al recibir una página incompleta. Un cierre más antiguo exige consultar el

historial con get_position_history.

Observabilidad

Los avisos de reconexión se registran con tracing (warn al perder el

socket, info al restablecerlo, error si se abandona). El consumidor que

quiera métricas propias puede contar Disconnected frente a Reconnected y

usar downtime_ms para medir la indisponibilidad real.

Estado verificado

La suite viva fuerza la caída del socket y comprueba el ciclo completo:

Disconnected, reconexión, operativa posterior y replay de una suscripción.

Última ejecución: 1 intento de reconexión, 4.938 ms sin conexión y vela

recibida tras volver; 34 comprobaciones, 0 fallos.

El recorrido multi-página tiene prueba con historiales simulados: localiza

cierres en páginas posteriores, corta al encontrarlos y respeta el límite de

diez páginas informando lo que quedó pendiente.

Python

Python

Binding nativo del núcleo Rust: la misma sesión, catálogo, velas, ticks y

órdenes rise/fall, invocados desde Python.

Viabilidad y decisión

pip install no instala crates de Rust: el crate de crates.io es código fuente

para Cargo. Para Python hace falta un módulo de extensión nativo. La vía

estándar es PyO3 + maturin, que compila el núcleo Rust como cdylib, produce

wheels por plataforma y los publica en PyPI.

La integración se hizo como paquete independiente (python/), con su propio

Cargo.toml y pyproject.toml. El crate publicado en crates.io no cambia ni

gana dependencias: cargo add cripsy-binary-api sigue igual.

Estado de publicación

CanalEstado
crates.io (cripsy-binary-api 0.3.1)Publicado y verificado
GitHub Release v0.3.1Wheels Linux x64/arm64, Windows x64/arm64, macOS Intel/arm64 y sdist
PyPIPublicado y verificado: seis wheels y sdist

El wheel es abi3 para CPython 3.10 o superior. El paquete ya está en PyPI;

también puedes instalar el wheel del release o compilar desde el repositorio.

Instalación

Wheels del release

# Windows x64
pip install https://github.com/ionixcorp/cripsy_binary_API/releases/download/v0.3.1/cripsy_binary_api-0.3.1-cp310-abi3-win_amd64.whl
# Linux x86_64
pip install https://github.com/ionixcorp/cripsy_binary_API/releases/download/v0.3.1/cripsy_binary_api-0.3.1-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

# macOS arm64
pip install https://github.com/ionixcorp/cripsy_binary_API/releases/download/v0.3.1/cripsy_binary_api-0.3.1-cp310-abi3-macosx_11_0_arm64.whl

Desde el repositorio (cualquier plataforma con Rust 1.86+)

pip install "cripsy-binary-api @ git+https://github.com/ionixcorp/cripsy_binary_API.git@v0.3.1#subdirectory=python"

pip instala maturin como backend de build y compila el módulo. Requiere Rust y

un compilador C instalados.

Desde PyPI

pip install cripsy-binary-api==0.3.1

Uso

Deriv en modo público (sin credenciales)

from cripsy_binary_api import Client

cliente = Client.connect_deriv()
try:
    print(len(cliente.assets()), "activos")
    velas = cliente.candles("R_100", interval=60, count=5)
    print(velas[-1]["close"])
    print(cliente.payout("R_100", 60)["profit_percent"])
    print(len(cliente.ticks("R_100", seconds=5)))
finally:
    cliente.close()

Deriv con cuenta demo

import os
from cripsy_binary_api import Client

cliente = Client.connect_deriv(
    token=os.environ["DERIV_TOKEN"],
    app_id=os.environ["DERIV_APPID"],
    account_id=os.environ.get("DERIV_ACCOUNT_ID"),
)
try:
    print(cliente.session())
    print(cliente.balance())
finally:
    cliente.close()

IQ Option

import os
from cripsy_binary_api import Client

cliente = Client.connect_iqoption(
    os.environ["IQOPTION_EMAIL"],
    os.environ["IQOPTION_PASSWORD"],
    practice=True,
)
try:
    print(cliente.balance())
finally:
    cliente.close()

Superficie

MétodoDevuelveNotas
Client.connect_deriv(...)Clientsin token: público
Client.connect_iqoption(...)Clientpractice=True por defecto
name()striq_option o deriv
is_connected()boolestado del socket
assets()lista de dictscatálogo completo
candles(symbol, interval, count)lista de dictsinterval en segundos
asset_status(symbol)strOpen / Closed / Suspended
payout(symbol, seconds)dictpayout del catálogo
session() / balance()dictrequieren cuenta
history(limit, offset, symbol)dictposiciones cerradas
ticks(symbol, seconds)lista de dictsstream nativo, sin polling
buy(symbol, amount, direction, minutes)strcall / put; demo
buy_digital(symbol, amount, direction, minutes, strike)strsolo IQ Option
buy_blitz(symbol, amount, direction, seconds, profit_percent)strsolo IQ Option
indicators(symbol)dictsolo IQ Option
sell(order_id)Noneventa anticipada
result(order_id)Win/Loss/Equal/Pendinglee caché
wait_result(order_id, timeout_secs)igualespera el evento
close()Nonecierra el WebSocket

Los dicts conservan los nombres del dominio Rust (symbol, close,

profit_percent, account_type, ...). No se renombran ni se recalculan.

Límites

libera durante la espera. Para concurrencia, usa un Client por hilo.

Deriv los rechaza con CripsyError; no se simulan sobre rise/fall.

internamente.

mensaje original; los argumentos inválidos lanzan ValueError.

Compilar el wheel en local

python -m pip install "maturin>=1.14,<2"
maturin build --release --manifest-path python/Cargo.toml --out python/dist
python -m pip install --force-reinstall python/dist/*.whl
python python/smoke_deriv.py

El workflow .github/workflows/wheels.yml construye seis wheels (Linux x64 y

arm64, Windows x64 y arm64, macOS Intel y arm64) más el sdist, y adjunta los

siete archivos al release al empujar una etiqueta v*. La subida a PyPI de

0.3.1 se hizo con MATURIN_PYPI_TOKEN; el job automático sigue desactivado

hasta configurar PYPI_API_TOKEN como secreto del repositorio.