Portfólio e Conta OKX CEX CLI
Saldo da conta, posições, P&L, faturas, taxas e transferências de fundos na exchange OKX. Requer credenciais de API.
Pré-requisitos
- Instalar a CLI
okx:npm install -g @okx_ai/okx-trade-cli - Configurar as credenciais:
Ou definir variáveis de ambiente:okx config initexport OKX_API_KEY=sua_chave export OKX_SECRET_KEY=seu_segredo export OKX_PASSPHRASE=sua_frase_secreta - Testar com modo de demonstração:
okx --profile demo account balance
Verificação de Credenciais e Perfil
Execute esta verificação antes de qualquer comando autenticado.
Etapa A — Verificar credenciais
okx config show # verificar status da configuração (a saída é mascarada)
- Se o comando retornar um erro ou mostrar que não há configuração: pare todas as operações, oriente o usuário a executar
okx config inite aguarde a conclusão da configuração antes de tentar novamente. - Se as credenciais estiverem configuradas: prossiga para a Etapa B.
Etapa B — Confirmar perfil (obrigatório)
--profile é obrigatório para todos os comandos autenticados. Nunca adicione um perfil implicitamente.
| Valor | Modo | Fundos |
|---|---|---|
live | Real | Fundos reais |
demo | Simulado | Fundos simulados |
Regras de resolução:
- A intenção da mensagem atual está clara (ex.: "real" / "ao vivo" / "live" →
live; "teste" / "simulado" / "demo" →demo) → use-a e informe o usuário:"Usando --profile live (Real)"ou"Usando --profile demo (Simulado)" - A mensagem atual não tem declaração explícita → verifique o contexto da conversa para um perfil anterior:
- Encontrado → use-o, informe o usuário:
"Continuando com --profile live (Real) de antes" - Não encontrado → pergunte:
"Real (ao vivo) ou Simulado (demo)?"— aguarde a resposta antes de prosseguir
- Encontrado → use-o, informe o usuário:
Tratamento de Erros de Autenticação 401
Se algum comando retornar um erro 401 / de autenticação:
- Pare imediatamente — não repita o mesmo comando
- Informe o usuário: "Falha na autenticação (401). Suas credenciais de API podem ser inválidas ou expiradas."
- Oriente o usuário a atualizar as credenciais editando o arquivo diretamente com seu editor local:
Atualize os campos~/.okx/config.tomlapi_key,secret_key,passphraseno perfil relevante. NÃO cole as novas credenciais no chat. - Após o usuário confirmar que o arquivo foi atualizado, execute
okx config showpara verificar (a saída é mascarada) - Só então repita a operação original
Modo Simulado vs Real
O perfil é o único controle para alternar entre Real/Simulado — exatamente duas opções:
--profile | Modo | Fundos |
|---|---|---|
live | Real | Fundos reais |
demo | Simulado | Fundos simulados |
okx --profile live account balance # Real
okx --profile demo account balance # Simulado (saldo simulado)
Regras:
- Comandos de leitura (saldo, posições, faturas, etc.): sempre indique qual perfil foi usado
- Comandos de escrita (
transfer,set-position-mode): o perfil deve ser confirmado antes da execução (veja "Verificação de Credenciais e Perfil" Etapa B); transferência especialmente — perfil errado significa conta errada - Toda resposta após um comando deve acrescentar:
[perfil: live]ou[perfil: demo] - Não use a flag
--demo— use--profile
Roteamento de Skills
- Para dados de mercado (preços, gráficos, profundidade, taxas de funding) → use
okx-cex-market - Para saldo da conta, P&L, posições, taxas, transferências → use
okx-cex-portfolio(esta skill) - Para ordens regulares spot/swap/futuros/algo → use
okx-cex-trade - Para bots de grid e DCA → use
okx-cex-bot
Guia Rápido
# Saldo da conta de negociação (todas as moedas com saldo > 0)
okx account balance
# Verificar apenas saldo USDT
okx account balance USDT
# Saldo da conta de funding
okx account asset-balance
# Todas as posições abertas
okx account positions
# Histórico de posições fechadas com P&L realizado
okx account positions-history
# Faturas recentes da conta (últimas 100)
okx account bills
# Nível de taxa de negociação
okx account fees --instType SPOT
# Transferir 100 USDT de funding (18) para negociação (6)
okx account transfer --ccy USDT --amt 100 --from 18 --to 6
Índice de Comandos
Comandos de Leitura
| # | Comando | Tipo | Descrição |
|---|---|---|---|
| 1 | okx account balance [ccy] | LEITURA | Patrimônio líquido, disponível, congelado da conta de negociação |
| 2 | okx account asset-balance [ccy] | LEITURA | Saldo da conta de funding |
| 3 | okx account positions | LEITURA | Posições abertas de contratos/swaps |
| 4 | okx account positions-history | LEITURA | Posições fechadas + P&L realizado |
| 5 | okx account bills | LEITURA | Razão da conta (depósitos, saques, negociações) |
| 6 | okx account fees --instType <tipo> | LEITURA | Nível de taxa de negociação (maker/taker) |
| 7 | okx account config | LEITURA | Nível da conta, modo de posição, UID |
| 8 | okx account max-size --instId <id> --tdMode <modo> | LEITURA | Tamanho máximo de compra/venda ao preço atual |
| 9 | okx account max-avail-size --instId <id> --tdMode <modo> | LEITURA | Tamanho disponível para a próxima ordem |
| 10 | okx account max-withdrawal [ccy] | LEITURA | Saque máximo por moeda |
Comandos de Escrita
| # | Comando | Tipo | Descrição |
|---|---|---|---|
| 11 | okx account set-position-mode <modo> | ESCRITA | Alternar modo de posição net/hedge |
| 12 | okx account transfer | ESCRITA | Transferir fundos entre contas |
Fluxos de Trabalho Entre Skills
Verificação de saldo pré-negociação
Usuário: "Quero comprar 0.1 BTC — tenho USDT suficiente?"
1. okx-cex-portfolio okx account balance USDT → verificar patrimônio líquido disponível
2. okx-cex-market okx market ticker BTC-USDT → verificar preço atual
↓ usuário aprova
3. okx-cex-trade okx spot place --instId BTC-USDT --side buy --ordType market --sz 0.1
Verificação de saldo pré-bot
Usuário: "Quero iniciar um bot de grid BTC com 1000 USDT"
1. okx-cex-portfolio okx account balance USDT → confirmar fundos disponíveis ≥ 1000
2. okx-cex-market okx market candles BTC-USDT --bar 4H --limit 50 → determinar faixa de preço
↓ usuário aprova
3. okx-cex-bot okx bot grid create --instId BTC-USDT --algoOrdType grid \
--minPx 90000 --maxPx 100000 --gridNum 10 --quoteSz 1000
Revisar posições abertas e P&L
Usuário: "Mostre minhas posições atuais e como estão performando"
1. okx-cex-portfolio okx account positions → posições abertas com P&L não realizado
2. okx-cex-portfolio okx account positions-history → posições fechadas recentemente
3. okx-cex-market okx market ticker BTC-USDT-SWAP → verificar preço atual vs. entrada
Transferir e negociar
Usuário: "Mova 500 USDT da minha conta de funding para negociar BTC"
1. okx-cex-portfolio okx account asset-balance USDT → confirmar saldo de funding ≥ 500
↓ usuário aprova
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 negociação atualizado
↓ pronto para negociar
4. okx-cex-trade okx spot place ...
Verificar tamanho máximo de posição antes de entrar
Usuário: "Quanto BTC posso comprar com margem cruzada?"
1. okx-cex-portfolio okx account balance → patrimônio líquido total
2. okx-cex-portfolio okx account max-size --instId BTC-USDT-SWAP --tdMode cross → tamanho máximo de compra/venda
3. okx-cex-market okx market ticker BTC-USDT-SWAP → referência de preço atual
Fluxo de Operação
Etapa 0 — Verificação de Credenciais e Perfil
Antes de qualquer comando autenticado:
Determinar perfil (obrigatório):
- Opções:
live(Real) oudemo(Simulado) — exatamente esses dois valores
- Intenção da mensagem atual clara (ex.: "real"/"ao vivo"/"live" → live; "teste"/"simulado"/"demo" → demo) → use-a, informe o usuário:
"Usando --profile live (Real)" - Mensagem atual sem declaração explícita → verifique contexto da conversa para perfil anterior:
- Encontrado → use-o, informe o usuário:
"Continuando com --profile live (Real) de antes" - Não encontrado → pergunte:
"Real (ao vivo) ou Simulado (demo)?"— aguarde resposta
- Encontrado → use-o, informe o usuário:
Se nenhuma credencial configurada: oriente o usuário a executar okx config init, pare todas as ações de negociação
Após cada resultado de comando: acrescente [perfil: live] ou [perfil: demo] à resposta
Etapa 1: Identificar ação da conta
- Verificar saldo →
okx account balance(negociação) ouokx account asset-balance(funding) - Visualizar posições abertas →
okx account positions - Visualizar posições fechadas + P&L →
okx account positions-history - Visualizar histórico de transações →
okx account bills - Verificar nível de taxa →
okx account fees - Verificar configurações da conta →
okx account config - Calcular tamanho da ordem →
okx account max-sizeouokx account max-avail-size - Verificar limite de saque →
okx account max-withdrawal - Transferir fundos →
okx account transfer - Alterar modo de posição →
okx account set-position-mode
Etapa 2: Executar comandos de leitura imediatamente — confirmar perfil (Etapa 0) depois comandos de escrita
Comandos de leitura (1–10): execute imediatamente, nenhuma confirmação necessária.
- Filtro
ccy: use símbolo da moeda comoUSDT,BTC,ETH --instTypepara taxas/posições:SPOT,SWAP,FUTURES,OPTION--archivepara faturas: acessar registros mais antigos além da janela padrão--tdModepara max-size:cash(spot),cross, ouisolated
Comandos de escrita (11–12): confirme uma vez antes de executar.
set-position-mode: confirme o modo (net= unidirecional,long_short_mode= modo hedge); alternar pode afetar posições abertastransfer: confirme--ccy,--amt,--from,--to(tipos de conta:6=negociação,18=funding); verifique saldo de origem primeiro
Etapa 3: Verificar após escritas
- Após
set-position-mode: executeokx account configpara confirmarposModeatualizado - Após
transfer: executeokx account balanceeokx account asset-balancepara confirmar saldos atualizados
Referência de Comandos CLI
Saldo da Conta — Conta de Negociação
okx account balance [ccy] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
ccy | Não | - | Filtrar para uma única moeda (ex.: USDT) |
Retorna tabela: currency, equity, available, frozen. Mostra apenas moedas com saldo > 0.
Saldo de Ativos — Conta de Funding
okx account asset-balance [ccy] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
ccy | Não | - | Filtrar para uma única moeda |
Retorna: ccy, bal, availBal, frozenBal. Mostra apenas moedas com saldo > 0.
Posições — Posições Abertas
okx account positions [--instType <tipo>] [--instId <id>] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
--instType | Não | - | Filtrar: SWAP, FUTURES, OPTION |
--instId | Não | - | Filtrar para instrumento específico |
Retorna: instId, instType, side (posSide), pos, avgPx, upl (P&L não realizado), lever. Mostra apenas posições com tamanho ≠ 0.
Histórico de Posições — Posições Fechadas
okx account positions-history [--instType <tipo>] [--instId <id>] [--limit <n>] [--json]
Retorna: instId, direction, openAvgPx, closeAvgPx, realizedPnl, uTime.
Faturas — Razão da Conta
okx account bills [--archive] [--instType <tipo>] [--ccy <ccy>] [--limit <n>] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
--archive | Não | false | Acessar registros mais antigos (endpoint de arquivo) |
--instType | Não | - | Filtrar por tipo de instrumento |
--ccy | Não | - | Filtrar por moeda |
--limit | Não | 100 | Número de registros |
Retorna: billId, instId, type, ccy, balChg, bal, ts.
Taxas — Nível de Taxa de Negociação
okx account fees --instType <tipo> [--instId <id>] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
--instType | Sim | - | SPOT, SWAP, FUTURES, OPTION |
--instId | Não | - | Instrumento específico (opcional) |
Retorna: level, maker, taker, makerU, takerU, ts.
Config — Configuração da Conta
okx account config [--json]
Retorna: uid, acctLv (nível da conta), posMode (net/long_short_mode), autoLoan, greeksType, level, levelTmp.
Tamanho Máximo — Tamanho Máximo da Ordem
okx account max-size --instId <id> --tdMode <modo> [--px <preço>] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
--instId | Sim | - | ID do instrumento |
--tdMode | Sim | - | cash (spot), cross, ou isolated |
--px | Não | - | Preço de referência (usa preço de marcação se omitido) |
Retorna: instId, maxBuy, maxSell.
Tamanho Disponível Máximo
okx account max-avail-size --instId <id> --tdMode <modo> [--json]
Retorna: instId, availBuy, availSell — o tamanho imediatamente disponível para a próxima ordem.
Saque Máximo
okx account max-withdrawal [ccy] [--json]
Retorna tabela: ccy, maxWd, maxWdEx (com empréstimo). Mostra todas as moedas se nenhum filtro.
Definir Modo de Posição
okx account set-position-mode <net|long_short_mode> [--json]
| Valor | Comportamento |
|---|---|
net | Unidirecional (padrão) — longo e curto são compensados |
long_short_mode | Modo hedge — longo e curto podem coexistir |
Aviso: Alternar modos com posições abertas pode causar comportamento inesperado. Verifique
okx account positionsprimeiro.
Transferir Fundos
okx account transfer --ccy <ccy> --amt <n> --from <tipoConta> --to <tipoConta> \
[--transferType <tipo>] [--subAcct <nome>] [--json]
| Parâmetro | Obrigatório | Padrão | Descrição |
|---|---|---|---|
--ccy | Sim | - | Moeda a transferir (ex.: USDT) |
--amt | Sim | - | Quantidade a transferir |
--from | Sim | - | Tipo de conta de origem: 6=negociação, 18=funding |
--to | Sim | - | Tipo de conta de destino: 6=negociação, 18=funding |
--transferType | Não | 0 | 0=dentro da conta, 1=para sub-conta, 2=da sub-conta |
--subAcct | Não | - | Nome da sub-conta (obrigatório para transferências de sub-conta) |
Retorna: transId, ccy, amt.
Referência de Ferramentas MCP
| Ferramenta | Descrição |
|---|---|
account_get_balance | Saldo da conta de negociação |
account_get_asset_balance | Saldo da conta de funding |
account_get_positions | Posições abertas |
account_get_positions_history | Histórico de posições fechadas |
account_get_bills | Faturas da conta |
account_get_fees | Taxas de negociação |
account_get_config | Configuração da conta |
account_get_max_size | Tamanho máximo da ordem |
account_get_max_avail_size | Tamanho disponível máximo |
account_get_max_withdrawal | Limite de saque |
account_set_position_mode | Definir modo de posição |
account_transfer | Transferir fundos |