Documentação Técnica Oficial: X-GO AGENTE 001 (v1.21.11)

01

Arquitetura self-hosted

Instalação local, dados operacionais e integrações configuradas pelo operador

Download comercial disponível: v1.21.11. Pacote com correções de inicialização, instalador e entrega de solicitações. Alterações ainda não lançadas no código de pesquisa dependem de uma nova versão empacotada e validada.

O X-GO AGENTE 001 (v1.21.11) é um software de análise, alertas e automação configurável para Binance Futures (USDT-M). Ele é instalado no computador ou na VPS do operador; dados e arquivos de configuração ficam nessa instalação. Integrações como Binance, Telegram e provedores opcionais de IA exigem conexão com seus serviços.

Armazenamento local

Banco de dados relacional SQLite (`agente001.db`) armazenado localmente em modo Write-Ahead Logging (WAL).

Controle local de dados

O agente armazena dados operacionais localmente e utiliza integrações configuradas pelo operador, como Binance e Telegram.

Controle de instância

O processo principal utiliza o arquivo `agente001.pid` para controlar a instância local.

Modos e perfis são controles diferentes

Sinais envia oportunidades sem executar; Supervisionado exige aprovação; Autônomo executa candidatos elegíveis dentro das travas; Grid trabalha faixas de preço com proteção de regime. Em qualquer modo, os perfis Conservador, Normal e Agressivo ajustam score mínimo, risco, cadência, timeframes e limites. Perfil agressivo não remove as travas de capital.

Predição nativa em observação

A v1.21.11 avalia candidatos do universo rotativo com probabilidades UP/DOWN/NEUTRAL. O usuário está observando os sinais em produção; ainda não há comprovação estatística de melhora. A previsão não remove reconciliação, capital confirmado, sizing, exposição, paper mode, circuit breakers ou kill-switches.

02

Motores Quantitativos & Estratégias

Motores de sinal, composição do score e critérios de seleção

1. TREND (Tendência Quantitativa) ADX > 25 / EMA / CVD

Avalia o alinhamento perfeito de EMAs (20/50/200), força de tendência via ADX > 25 e pressão de agressão institucional medida pelo Delta do Volume Cumulativo (CVD).

2. VDLS (Liquidity Sweep) Volume Spike

Rastreia a manipulação e captura de liquidez em topos/fundos relevantes com confirmação de volume Taker desproporcional antes da reversão.

3. FADE (Order Block Reversal) Smart Money

Identifica zonas institucionais de Order Block e Fair Value Gaps (FVG), efetuando entradas no reteste de desequilíbrios de liquidez.

4. RANGE (Consolidação em Canais) Keltner / BB

Opera a oscilação média em mercados de baixa volatilidade (Canais de Keltner + Bollinger Bands). Pausado por padrão via trava ADX < 20.

5. BREAKOUT (Rompimento Dinâmico) High Volatility

Captura expansões de volatilidade no rompimento de máximas/mínimas históricas de n-velas com confirmação de expansão do indicador ATR e RVOL > 2.0.

Score e ajustes de confirmação - atualização de 27/09/2026

Os pesos do score base foram revistos. Em Day/Swing: tendência 18%, volume 22%, momentum 12%, estrutura 15%, VWAP 8% e funding + open interest 25%. Em Scalp: 15%, 22%, 18%, 13%, 12% e 20%, respectivamente. Cada conjunto soma 100%.

O time-series momentum compara os fechamentos das 90 velas já encerradas fornecidas ao sinal e aplica um ajuste limitado de +6 ou -6 pontos quando o retorno excede 3% a favor ou contra a direção avaliada. O basis compara markPrice com indexPrice nos dados de Futures e pode aplicar confirmação ou penalidade moderada. Em dados históricos, o agente não usa o basis atual como se fosse passado; este recurso também não executa uma compra spot pareada.

Os valores brutos dos sete fatores, incluindo VWAP, passam a ser registrados no breakdown para análise futura. O ajuste final do roteador é sincronizado com score e breakdown. Os pesos permanecem fixos e ainda precisam de avaliação com resultados suficientes; esta atualização não comprova melhora de desempenho. Score indica confluência das regras, não probabilidade calibrada de lucro.

No perfil Normal, o score mínimo passou de 72 para 65 e o risco/retorno mínimo de 2,0 para 1,7. Isso permite avaliar mais candidatos, sem afirmar maior taxa de acerto ou rentabilidade. Os limites dos perfis Conservador e Agressivo permanecem 74/2,5 e 62/1,7.

# agente001/engines/strategy_interface.py
from abc import ABC, abstractmethod
from typing import Optional, Dict, Any
import pandas as pd

class IStrategy(ABC):
    @abstractmethod
    def generate_entry(self, candles: pd.DataFrame, market_ctx: Dict[str, Any]) -> Optional[SignalResult]:
        """
        Avalia o histórico de candles e a telemetria do livro para gerar um sinal quantitativo.
        Retorna SignalResult com direção, Stop Loss calculado e Take Profit dinâmico.
        """
        pass

    @abstractmethod
    def describe_decision(self, signal: SignalResult) -> str:
        """Retorna a telemetria em texto legível para auditoria dos logs operacionais."""
        pass

03

Cérebro de IA & Regime de Mercado

Ensemble Machine Learning, detecção de fases de mercado e integração LLM

O módulo ml_engine.py treina modelos XGBoost Classifier e RandomForest Classifier. O bônus de score só influencia entradas reais quando há amostras e qualidade de validação suficientes. Sem isso, o agente continua usando os filtros técnicos e de risco configurados.

Vetor de 11 características:

Score técnico, risco/retorno, direção, componentes de tendência, volume, momentum, estrutura, funding e open interest, hora, dia da semana e indicador de operação em papel.

Nota de Corte de Confluência:

Score mínimo: 74 no Conservador, 65 no Normal e 62 no Agressivo. Risco/retorno mínimo: 2,5 no Conservador e 1,7 nos demais. Score mede confluência e não representa probabilidade calibrada de lucro.

04

Módulo de Backtesting AI (`agente001/backtesting/`)

Simulação estritamente causal event-driven e validação Out-of-Sample

O backtest simula entradas na abertura do candle seguinte ao sinal e evita usar candles futuros. Quando um fator depende de contexto ao vivo sem histórico equivalente confiável, ele é neutralizado ou omitido na simulação. Essa regra reduz um tipo de viés, mas não prova causalidade de mercado nem equivalência entre backtest e execução ao vivo.

# Inicie o agente e abra o painel local de backtesting:
http://127.0.0.1:8000/backtesting

# A API também fornece o catálogo e os limites da simulação:
GET /api/backtesting/catalog
GET /api/backtesting/config

05

Gestão de Risco Paramétrica & Capital Guard

Filtro de custo, trailing progressivo e limites de exposição

Fórmula da Trava Econômica (`target_covers_cost`):

O motor compara o alvo potencial com os custos estimados de ida e volta. Taxas, spread e slippage dependem do mercado e da configuração; o filtro pode rejeitar uma operação cujo alvo não compense esses custos.

06

Guia Completo de Instalação & Deploy

Procedimentos para Windows, Linux Server e Docker Compose 24/7

# 1. Extraia e acesse a pasta do projeto
cd xgo-agente001

# 2. Crie o ambiente virtual
python -m venv venv
# No Windows PowerShell:
.\venv\Scripts\Activate.ps1
# No Linux/macOS:
source venv/bin/activate

# 3. Instale as dependências
pip install -r requirements.txt

# 4. Inicie o agente
python main.py

# Sobe o container em segundo plano com reinício automático
docker-compose up -d --build

# Acompanhe a telemetria em tempo real
docker-compose logs -f --tail=100

07

Chaves API & Segredos do Ambiente

Protocolo de segurança de credenciais e modelo do arquivo .env

1. Permissões Obrigatórias: Habilite exclusivamente "Enable Reading" e "Enable Futures".

2. Restrição Absoluta de Saques: Mantenha a opção "Enable Withdrawals" RIGOROSAMENTE DESABILITADA.

# Credenciais Binance Futures API
BINANCE_API_KEY=sua_api_key_binance_aqui
BINANCE_SECRET_KEY=sua_secret_key_binance_aqui
FORCE_PAPER_TRADING=true       # true para simulação, false para mercado real

# Notificações e Comandos (Telegram Bot)
TELEGRAM_BOT_TOKEN=789101112:AAFg...
TELEGRAM_CHAT_ID=123456789

# Dashboard Web Admin
PORT=8000  # exemplo; ajuste conforme a configuracao local
DASHBOARD_PASSWORD=sua_senha_forte_aqui

08

Comandos de Controle & Telemetria

Comandos de bot para Telegram/WhatsApp e Painel Web Admin (porta definida em PORT (exemplo: 8000))

Comando	Ação Executada pelo Agente	Canais de Controle
/status	Retorna a saúde do processo, conexões de API e modo ativo.	Telegram / WhatsApp / CLI
/trades	Lista trades abertos com PnL; use /posicao BTCUSDT para detalhar um ativo.	Telegram
/pnl	Exibe o relatório consolidado de rendimento do dia, semana e mês.	Telegram / WhatsApp
/paper on	Ativa a negociação em papel sem encerrar o processo; /stop apenas orienta a encerrar o serviço.	Telegram
/menu	Abre o painel de controle com modos, perfis, pausa e retomada.	Telegram

09

Requisitos do Sistema & Latência

Especificações de hardware para ambientes local e servidor VPS

Requisitos Mínimos (Local / Windows):

• Sistema Operacional: Windows 10/11, Ubuntu 20.04+ ou macOS
• Processador: Dual-Core 2.0 GHz
• Memória RAM: 2 GB RAM livres
• Armazenamento: 5 GB em disco SSD
• Python: Versão 3.12 ou superior

FAQ & Solução de Erros Operacionais

Dicionário de códigos de erro de API e manutenção

Erro -2015 ("API-key format invalid" / IP Whitelist)

Sua chave foi copiada incorretamente ou a restrição de IP na Binance está bloqueando o servidor. Verifique se copiou a chave sem espaços adicionais.

Erro -1021 ("Timestamp outside recvWindow")

O relógio do seu computador/VPS está desalinhado com os servidores NTP da Binance. No Linux execute sudo ntpdate pool.ntp.org. No Windows force a sincronização em Data e Hora.

Procedimento de Atualização sem Perda de Dados

Antes de atualizar, faça cópia do arquivo .env e do banco de dados. Consulte as instruções e scripts incluídos na versão entregue, pare o agente e valide as configurações após a atualização.

Arquitetura self-hosted

Protocolo Não-Custodial Estrito:

Motores Quantitativos & Estratégias

Score e ajustes de confirmação - atualização de 27/09/2026

Cérebro de IA & Regime de Mercado

Módulo de Backtesting AI (`agente001/backtesting/`)

Gestão de Risco Paramétrica & Capital Guard

Fórmula da Trava Econômica (`target_covers_cost`):

Guia Completo de Instalação & Deploy

Chaves API & Segredos do Ambiente

Comandos de Controle & Telemetria

Requisitos do Sistema & Latência

Requisitos Mínimos (Local / Windows):

Recomendado para VPS 24/7:

FAQ & Solução de Erros Operacionais

Erro -2015 ("API-key format invalid" / IP Whitelist)

Erro -1021 ("Timestamp outside recvWindow")

Procedimento de Atualização sem Perda de Dados

Pronto para Operar com o Agente 001 v1.21.11?

Arquitetura self-hosted

Protocolo Não-Custodial Estrito:

Motores Quantitativos & Estratégias

Score e ajustes de confirmação - atualização de 27/09/2026

Cérebro de IA & Regime de Mercado

Módulo de Backtesting AI (`agente001/backtesting/`)

Gestão de Risco Paramétrica & Capital Guard

Fórmula da Trava Econômica (`target_covers_cost`):

Guia Completo de Instalação & Deploy

Chaves API & Segredos do Ambiente

Comandos de Controle & Telemetria

Requisitos do Sistema & Latência

Requisitos Mínimos (Local / Windows):

Recomendado para VPS 24/7:

FAQ & Solução de Erros Operacionais

Erro -2015 ("API-key format invalid" / IP Whitelist)

Erro -1021 ("Timestamp outside recvWindow")

Procedimento de Atualização sem Perda de Dados

Pronto para Operar com o Agente 001 v1.21.11?

Ativação da Licença Oficial