Cartera y Cuenta CLI de OKX CEX
Saldo de cuenta, posiciones, P&L, facturas, comisiones y transferencias de fondos en el exchange OKX. Requiere credenciales API.
Prerrequisitos
- Instalar CLI
okx:npm install -g @okx_ai/okx-trade-cli - Configurar credenciales:
O establecer variables de entorno:okx config initexport OKX_API_KEY=tu_clave export OKX_SECRET_KEY=tu_secreto export OKX_PASSPHRASE=tu_frase - Probar con modo demo:
okx --profile demo account balance
Verificación de Credenciales y Perfil
Ejecuta esta verificación antes de cualquier comando autenticado.
Paso A — Verificar credenciales
okx config show # verificar estado de configuración (salida oculta)
- Si el comando devuelve un error o no muestra configuración: detener todas las operaciones, guiar al usuario para que ejecute
okx config init, y esperar a que la configuración se complete antes de reintentar. - Si las credenciales están configuradas: proceder al Paso B.
Paso B — Confirmar perfil (obligatorio)
--profile es obligatorio para todos los comandos autenticados. Nunca agregues un perfil implícitamente.
| Valor | Modo | Fondos |
|---|---|---|
live | Real | Fondos reales |
demo | Simulado | Fondos simulados |
Reglas de resolución:
- La intención del mensaje actual es clara (ej. "real" →
live; "test" / "simulado" →demo) → usarlo e informar al usuario:"Usando --profile live (Real)"o"Usando --profile demo (Simulado)" - El mensaje actual no tiene una declaración explícita → verificar el contexto de la conversación en busca de un perfil anterior:
- Encontrado → usarlo, informar al usuario:
"Continuando con --profile live (Real) de antes" - No encontrado → preguntar:
"¿Real o Simulado?"— esperar respuesta antes de proceder
- Encontrado → usarlo, informar al usuario:
Manejo de Errores de Autenticación 401
Si algún comando devuelve un error 401 / de autenticación:
- Detenerse inmediatamente — no reintentar el mismo comando
- Informar al usuario: "Falló la autenticación (401). Tus credenciales API pueden ser inválidas o haber expirado."
- Guiar al usuario para que actualice las credenciales editando el archivo directamente con su editor local:
Actualizar los campos~/.okx/config.tomlapi_key,secret_key,passphraseen el perfil correspondiente. NO pegar las nuevas credenciales en el chat. - Después de que el usuario confirme que el archivo está actualizado, ejecutar
okx config showpara verificar (salida oculta) - Solo entonces reintentar la operación original
Modo Demo vs Real
El perfil es el único control para cambiar entre real/simulado — exactamente dos opciones:
--profile | Modo | Fondos |
|---|---|---|
live | Real | Fondos reales |
demo | Simulado | Fondos simulados |
okx --profile live account balance # Real
okx --profile demo account balance # Simulado (saldo simulado)
Reglas:
- Comandos de lectura (balance, posiciones, facturas, etc.): siempre indicar qué perfil se usó
- Comandos de escritura (
transfer,set-position-mode): el perfil debe confirmarse antes de la ejecución (ver "Verificación de Credenciales y Perfil" Paso B); transferencia especialmente — perfil incorrecto significa cuenta incorrecta - Cada respuesta después de un comando debe añadir:
[perfil: live]o[perfil: demo] - No usar la bandera
--demo— usar--profileen su lugar
Enrutamiento de Habilidades
- Para datos de mercado (precios, gráficos, profundidad, tasas de financiación) → usar
okx-cex-market - Para saldo de cuenta, P&L, posiciones, comisiones, transferencias → usar
okx-cex-portfolio(esta habilidad) - Para órdenes regulares de spot/swap/futuros/algo → usar
okx-cex-trade - Para bots de trading de cuadrícula y DCA → usar
okx-cex-bot
Inicio Rápido
# Saldo de cuenta de trading (todas las divisas con saldo > 0)
okx account balance
# Consultar solo saldo de USDT
okx account balance USDT
# Saldo de cuenta de financiación
okx account asset-balance
# Todas las posiciones abiertas
okx account positions
# Historial de posiciones cerradas con PnL realizado
okx account positions-history
# Facturas recientes de la cuenta (últimas 100)
okx account bills
# Mi nivel de comisiones de trading
okx account fees --instType SPOT
# Transferir 100 USDT de financiación (18) a trading (6)
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
Índice de Comandos
Comandos de Lectura
| # | Comando | Tipo | Descripción |
|---|---|---|---|
| 1 | okx account balance [ccy] | LECTURA | Capital, disponible, congelado de cuenta de trading |
| 2 | okx account asset-balance [ccy] | LECTURA | Saldo de cuenta de financiación |
| 3 | okx account positions | LECTURA | Posiciones abiertas de contratos/swaps |
| 4 | okx account positions-history | LECTURA | Posiciones cerradas + PnL realizado |
| 5 | okx account bills | LECTURA | Libro mayor de cuenta (depósitos, retiros, trades) |
| 6 | okx account fees --instType <tipo> | LECTURA | Mi nivel de comisiones de trading (maker/taker) |
| 7 | okx account config | LECTURA | Nivel de cuenta, modo de posición, UID |
| 8 | okx account max-size --instId <id> --tdMode <modo> | LECTURA | Tamaño máximo de compra/venta al precio actual |
| 9 | okx account max-avail-size --instId <id> --tdMode <modo> | LECTURA | Tamaño disponible para la próxima orden |
| 10 | okx account max-withdrawal [ccy] | LECTURA | Máximo retirable por divisa |
Comandos de Escritura
| # | Comando | Tipo | Descripción |
|---|---|---|---|
| 11 | okx account set-position-mode <modo> | ESCRITURA | Cambiar modo de posición net/hedge |
| 12 | okx account transfer | ESCRITURA | Transferir fondos entre cuentas |
Flujos de Trabajo Multi-Habilidad
Verificación de saldo pre-trade
Usuario: "Quiero comprar 0.1 BTC — ¿tengo suficiente USDT?"
1. okx-cex-portfolio okx account balance USDT → verificar capital disponible
2. okx-cex-market okx market ticker BTC-USDT → verificar precio actual
↓ usuario aprueba
3. okx-cex-trade okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.1
Verificación de saldo pre-bot
Usuario: "Quiero iniciar un bot de cuadrícula BTC con 1000 USDT"
1. okx-cex-portfolio okx account balance USDT → confirmar fondos disponibles ≥ 1000
2. okx-cex-market okx market candles BTC-USDT --bar 4H --limit 50 → determinar rango de precios
↓ usuario aprueba
3. okx-cex-bot okx bot grid create --instId BTC-USDT --algoOrdType grid \
--minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
Revisar posiciones abiertas y P&L
Usuario: "Muéstrame mis posiciones actuales y cómo están funcionando"
1. okx-cex-portfolio okx account positions → posiciones abiertas con UPL
2. okx-cex-portfolio okx account positions-history → posiciones cerradas recientemente
3. okx-cex-market okx market ticker BTC-USDT-SWAP → verificar precio actual vs entrada
Transferir y hacer trade
Usuario: "Mueve 500 USDT de mi cuenta de financiación para comprar BTC"
1. okx-cex-portfolio okx account asset-balance USDT → confirmar saldo de financiación ≥ 500
↓ usuario aprueba
2. okx-cex-portfolio okx account transfer --ccy USDT --amt 500 --from 18 --to 6
3. okx-cex-portfolio okx account balance USDT → confirmar saldo de trading actualizado
↓ listo para hacer trade
4. okx-cex-trade okx spot place ...
Verificar tamaño máximo de posición antes de entrar
Usuario: "¿Cuánto BTC puedo comprar con margen cruzado?"
1. okx-cex-portfolio okx account balance → capital total
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → tamaño máximo de compra/venta
3. okx-cex-market okx market ticker BTC-USDT-SWAP → referencia de precio actual
Flujo de Operación
Paso 0 — Verificación de Credenciales y Perfil
Antes de cualquier comando autenticado:
Determinar perfil (obligatorio):
- Opciones:
live(Real) odemo(Simulado) — exactamente estos dos valores
- La intención del mensaje actual es clara (ej. "real" → live; "test"/"simulado" → demo) → usarlo, informar al usuario:
"Usando --profile live (Real)" - El mensaje actual no tiene una declaración explícita → verificar el contexto de la conversación para un perfil anterior:
- Encontrado → usarlo, informar al usuario:
"Continuando con --profile live (Real) de antes" - No encontrado → preguntar:
"¿Real o Simulado?"— esperar respuesta
- Encontrado → usarlo, informar al usuario:
Si no hay credenciales configuradas: guiar al usuario para que ejecute okx config init, detener todas las acciones de trading
Después de cada resultado de comando: añadir [perfil: live] o [perfil: demo] a la respuesta
Paso 1: Identificar acción de cuenta
- Verificar saldo →
okx account balance(trading) ookx account asset-balance(financiación) - Ver posiciones abiertas →
okx account positions - Ver posiciones cerradas + PnL →
okx account positions-history - Ver historial de transacciones →
okx account bills - Ver nivel de comisiones →
okx account fees - Ver configuraciones de cuenta →
okx account config - Calcular tamaño de orden →
okx account max-sizeookx account max-avail-size - Ver límite de retiro →
okx account max-withdrawal - Transferir fondos →
okx account transfer - Cambiar modo de posición →
okx account set-position-mode
Paso 2: Ejecutar comandos de lectura inmediatamente — confirmar perfil (Paso 0) luego escrituras
Comandos de lectura (1–10): ejecutar inmediatamente, no se necesita confirmación.
- Filtro
ccy: usar símbolo de divisa comoUSDT,BTC,ETH --instTypepara comisiones/posiciones:SPOT,SWAP,FUTURES,OPTION--archivepara facturas: acceder a registros más antiguos fuera de la ventana predeterminada--tdModepara max-size:cash(spot),cross, oisolated
Comandos de escritura (11–12): confirmar una vez antes de ejecutar.
set-position-mode: confirmar modo (net= unidireccional,long_short_mode= modo hedge); cambiar puede afectar posiciones abiertastransfer: confirmar--ccy,--amt,--from,--to(tipos de cuenta:6=trading,18=financiación); verificar saldo de origen primero
Paso 3: Verificar después de escrituras
- Después de
set-position-mode: ejecutarokx account configpara confirmar queposModese actualizó - Después de
transfer: ejecutarokx account balanceyokx account asset-balancepara confirmar que los saldos se actualizaron
Referencia de Comandos CLI
Saldo de Cuenta — Cuenta de Trading
okx account balance [ccy] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
ccy | No | - | Filtrar por una sola divisa (ej., USDT) |
Devuelve tabla: currency, equity, available, frozen. Solo muestra divisas con saldo > 0.
Saldo de Activos — Cuenta de Financiación
okx account asset-balance [ccy] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
ccy | No | - | Filtrar por una sola divisa |
Devuelve: ccy, bal, availBal, frozenBal. Solo muestra divisas con saldo > 0.
Posiciones — Posiciones Abiertas
okx account positions [--instType <tipo>] [--instId <id>] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
--instType | No | - | Filtro: SWAP, FUTURES, OPTION |
--instId | No | - | Filtrar por instrumento específico |
Devuelve: instId, instType, side (posSide), pos, avgPx, upl (PnL no realizado), lever. Solo muestra posiciones con tamaño ≠ 0.
Historial de Posiciones — Posiciones Cerradas
okx account positions-history [--instType <tipo>] [--instId <id>] [--limit <n>] [--json]
Devuelve: instId, direction, openAvgPx, closeAvgPx, realizedPnl, uTime.
Facturas — Libro Mayor de Cuenta
okx account bills [--archive] [--instType <tipo>] [--ccy <ccy>] [--limit <n>] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
--archive | No | false | Acceder a registros antiguos (endpoint de archivo) |
--instType | No | - | Filtrar por tipo de instrumento |
--ccy | No | - | Filtrar por divisa |
--limit | No | 100 | Número de registros |
Devuelve: billId, instId, type, ccy, balChg, bal, ts.
Comisiones — Nivel de Comisiones de Trading
okx account fees --instType <tipo> [--instId <id>] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
--instType | Sí | - | SPOT, SWAP, FUTURES, OPTION |
--instId | No | - | Instrumento específico (opcional) |
Devuelve: level, maker, taker, makerU, takerU, ts.
Config — Configuración de Cuenta
okx account config [--json]
Devuelve: uid, acctLv (nivel de cuenta), posMode (net/long_short_mode), autoLoan, greeksType, level, levelTmp.
Tamaño Máximo — Tamaño Máximo de Orden
okx account max-size --instId <id> --tdMode <modo> [--px <precio>] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
--instId | Sí | - | ID del instrumento |
--tdMode | Sí | - | cash (spot), cross, o isolated |
--px | No | - | Precio de referencia (usa precio de marca si se omite) |
Devuelve: instId, maxBuy, maxSell.
Tamaño Máximo Disponible
okx account max-avail-size --instId <id> --tdMode <modo> [--json]
Devuelve: instId, availBuy, availSell — el tamaño inmediatamente disponible para la próxima orden.
Retiro Máximo
okx account max-withdrawal [ccy] [--json]
Devuelve tabla: ccy, maxWd, maxWdEx (con préstamo). Muestra todas las divisas si no hay filtro.
Establecer Modo de Posición
okx account set-position-mode <net|long_short_mode> [--json]
| Valor | Comportamiento |
|---|---|
net | Unidireccional (predeterminado) — largo y corto se compensan |
long_short_mode | Modo Hedge — largo y corto pueden coexistir |
Advertencia: Cambiar de modo cuando hay posiciones abiertas puede causar comportamiento inesperado. Verificar
okx account positionsprimero.
Transferir Fondos
okx account transfer --ccy <ccy> --amt <n> --from <tipoCuenta> --to <tipoCuenta> \
[--transferType <tipo>] [--subAcct <nombre>] [--json]
| Parámetro | Obligatorio | Predeterminado | Descripción |
|---|---|---|---|
--ccy | Sí | - | Divisa a transferir (ej., USDT) |
--amt | Sí | - | Monto a transferir |
--from | Sí | - | Tipo de cuenta de origen: 6=trading, 18=financiación |
--to | Sí | - | Tipo de cuenta de destino: 6=trading, 18=financiación |
--transferType | No | 0 | 0=dentro de la cuenta, 1=a subcuenta, 2=desde subcuenta |
--subAcct | No | - | Nombre de la subcuenta (obligatorio para transferencias de subcuenta) |
Devuelve: transId, ccy, amt.
Referencia de Herramientas MCP
| Herramienta | Descripción |
|---|---|
account_get_balance | Saldo de cuenta de trading |
account_get_asset_balance | Saldo de cuenta de financiación |
account_get_positions | Posiciones abiertas |
account_get_positions_history | Historial de posiciones cerradas |
account_get_bills | Facturas de cuenta / libro mayor |
account_get_fees | Nivel de comisiones de trading |
account_get_config | Configuración de cuenta |
account_get_max_size | Tamaño máximo de orden |
account_get_max_avail_size | Tamaño máximo disponible |
account_get_max_withdrawal | Monto de retiro máximo |
account_set_position_mode | Cambiar modo de posición |
account_transfer | Transferir entre cuentas |