ASPIRA - Manual Completo de Arquitetura e Operações

01. O que é ASPIRA — Visão Geral do Sistema

Snapshot operacional de ASPIRA em 2026-03-06 13:10 UTC: 9 agentes online, 30+ skills, 6 crons ativos, memória v3 operando.

🫡 ASPIRA - Orquestrador Central

Parâmetro	Valor	Descrição
Status	✅ OPERACIONAL	100% funcional, todos componentes online
Agentes Online	9/9	DEV, NERD, DESIGNER, COPYWRITER, FRONTEND, ANALYTICS, TRADER, DEGEN, ASPIRA
Session Counter	#51	Auto-incrementing, rastreia sequência de execuções
Memory Threshold	40k tokens	Trigger para extraction-v3.sh automática
Crons Agendadas	6/6 Ativas	Pool 2x, Briefing, Health, Extraction, Security, Agenda
Skills Disponíveis	30+	Cripto (8), Research (5), Content (6), Dev (3), mais...

👤 Diego - Perfil & Horários

Essencial

Timezone: BRT (UTC-3) | Ativo: 07h-19h BRT | Pausa: 11h15-13h (família) | Limite Gasto: $100 USD (confirmar antes)

💾 Memória v3 - 5 Categorias Permanentes

Categoria	Arquivo	Propósito	Linhas
Decisões	memory/decisions.md	Escolhas estratégicas com contexto, rationale, impacto	63
Mudanças	memory/changes.md	Alterações de arquitetura, setup, configuração	72
Lições	memory/lessons.md	Aprendizados críticos, best practices, anti-patterns	105
Bloqueadores	memory/blockers.md	Problemas ativos, status, workarounds, ETA fix	131
Fatos-Chave	memory/facts.md	Estado operacional: wallets, posições, crons, counts	150

🔗 Como Tudo Se Conecta (Visão Inicial)

ARQUITETURA EM 3 CAMADAS

CAMADA 1: FUNDAÇÃO

SOUL.md (essência) → USER.md (Diego profile) → IDENTITY.md (Persona)

⬇️ Define atitude, valores, limites para TODO sistema

CAMADA 2: ATIVOS & OPERAÇÃO

AGENTS.md (9 especialistas) + TOOLS.md (30+ skills)

⬇️ ASPIRA orquestra agentes paralelo/sequencial conforme tarefa

CAMADA 3: MEMÓRIA & EXECUÇÃO

MEMORY.md (índice) + 5 categorias permanentes (521 linhas)

⬇️ Auto-consolidação via extraction-v3.sh (40k trigger)

03. Gateways & Canais de Comunicação

Como o sistema se comunica: WhatsApp (primary), Telegram (18 tópicos), Discord, Farcaster. Roteamento automático de mensagens.

📱 WhatsApp - Canal Direto (PRIMARY)

+555599096505

Status: ✅ ATIVO | Prioridade: MÁXIMA | Uso: Alertas críticos, approvals, briefing diário

Quando: Operações >$100, pool out-of-range, briefing 06:30, agenda 30min antes

📍 Telegram - 18 Tópicos Especializados

ID Tópico	Nome	Emoji	Propósito	Roteamento
450	TRADING	📈	Análises técnicas, setups, sinais, execução	TRADER + ANALYTICS output
1046	DeFi	🪙	Pools, liquidez, MICAM, rebalance proposals	DEGEN output (2x/dia: 07:15 + 16:15 BRT)
4	Infra do Aspira	⚙️	Sistema, config, gateway, deploys	ASPIRA + health-check.sh logs
51	Erros & Bugs	💥	Problemas, falhas, alertas críticos	Error handler + health check
685	Daily Briefing	☕	Market recap diário, narrativas, oportunidades	briefing-aggregator (06:30 BRT)
192	Agenda Pessoal	📅	Lembretes, reuniões, eventos, compromissos	google-agenda-v2 (30min antes evento)
178	Auditoria	🐾	Logs, trilha, compliance, histórico	Security audit (seg 07:00 BRT) + manual logs
28	Agentes	🤖	Squad status, orquestração, parallelism logs	ASPIRA + subagents monitoring
26	Orquestrador	🐉	Decisões estratégicas, planejamento, roadmap	ASPIRA decisions consolidation

19. Cripto & Trading — Operações, Setups & Execução

Como executa operações: 2 fluxos (manual + automático), 3 setups análise, 5 executores por exchange, approval >$100.

🧠 Fluxo 1: Manual (On-Demand)

1

Diego comanda análise via WhatsApp/Telegram

2

ASPIRA spawn TRADER (Sonnet 4) ou ANALYTICS (Sonnet 4)

3

Agente retorna: entry, SL, TP, confidence, R:R, timeframe

4

IF > $100: approval workflow (Telegram + WhatsApp)

5

Diego aprova: /approve-TRADE → DEGEN executa

6

DEGEN coloca ordem on-chain, reporta tx hash

🤖 Fluxo 2: Automação 24/7 (Heartbeat)

Como Funciona

A cada 2-5 min (horário ativo), ASPIRA executa ciclo:

1. Valida quiet hours (se 23h-07h, skip non-critical)
2. Spawn TRADER para análise de mercado
3. TRADER retorna sinal > setup threshold? SIM
4. DEGEN calcula size, fees, slippage
5. IF >$100: aguarda approval. IF <$100: executa direto
6. Coloca ordem com TP/SL linked
7. ANALYTICS monitora até close (TP ou SL)

📊 3 Setups de Análise Técnica

Setup	Indicadores	Quando Usar	Output
Divergence & Volume	RSI div + Volume + Fib + Patterns	Detectar reversão (bullish/bearish)	Tipo reversal, confidence %, entrada
MICAM (Multi-Indicator)	Bollinger + Fib + S/R + RSI + MACD + Vol	Propor novo range LP ou validar consolidação	Trend, reversal prob %, novo range
Trading Setups	EMA + RSI + MACD + Volume + Patterns	Scalp/swing multi-timeframe	Type, confidence, entry/SL/TP, R:R

🎯 5 Executores (por Exchange)

Exchange	Skill	Tipo Operação	SLA	Status
Uniswap v3	uniswapskill (ethers.js)	LP management, mint/burn/rebalance	5-15 min	✅ PRIMARY
Hyperliquid	hyperliquid skill	Perpetual futures, scalping, leverage 20x	1-2 min	✅ ATIVO
Kraken	kraken skill	Spot, futures, margin, staking	2-3 min	✅ ATIVO
NADO	nado skill	Solana perpetuals, grid trading	2-3 min	✅ ATIVO
Bankr	bankr skill	Multi-chain swaps, DeFi, leverage	2-3 min	✅ ATIVO

✅ Approval Workflow (>$100 USD)

OPERAÇÃO IDENTIFICADA > $100 USD

1. TRADER retorna spec (entry, SL, TP, size, total)
2. ASPIRA formata mensagem com:
   - Detalhes operação (preço, quantidade, fees estimadas)
   - 2-3 alternativas (diferentes sizes, ranges)
   - Riscos (breakout prob, IL, slippage)
3. Enviar DUPLO:
   - Telegram (tópico correto: 450 Trading ou 1046 DeFi)
   - WhatsApp (+555599096505)
4. Diego reage: /approve-TRADE ou /reject
5. ASPIRA detecta reação, processa:
   - /approve: DEGEN executa on-chain
   - /reject: Operação cancelada, log registrado
6. Resultado reportado: tx hash + fees + close time

Operações <$100: DEGEN executa direto (sem approval)
        

02. Arquitetura Completa — Pilares & Design

Design sistêmico: 3 pilares, 9 etapas operação, task decomposition, decisões de design.

🏗️ 3 Pilares da Arquitetura

SOUL.md

Essência: tom, valores, limites. Define atitude de todo sistema. Lido no boot.

AGENTS.md

9 especialistas: modelos, SLA, skills, quando spawnar. Matriz de decisão.

TOOLS.md

30+ skills categorizadas: crypto, research, content, dev. Verificação antes afirmar.

USER.md

Diego profile: timezone BRT, horários, preferências, $100 limit.

MEMORY.md

Índice central: 5 categorias permanentes (521 linhas), search BM25+Vector.

IDENTITY.md

Persona ASPIRA: Android vermelho, militar, profissional 🫡.

🔄 9 Etapas do Ciclo Operacional

1

DIEGO envia comando via WhatsApp/Telegram

2

ASPIRA recebe, valida quiet hours (23h-07h, pausa 11:15-13h = skip non-critical)

3

ASPIRA analisa tipo tarefa (pesquisa, design, código, trading, conteúdo, defi)

4

ASPIRA decompõe em subtarefas (Task Decomposition Matrix)

5

ASPIRA decide paralelo/sequencial (Parallelism Decision Tree)

6

Spawn agentes com credenciais via 1Password (op read "op://Aspira/...")

7

Agentes executam com timeouts, error handling, fallbacks

8

IF >$100: ASPIRA aguarda approval (DIEGO reage /approve ou /reject)

9

ASPIRA consolida resultado em MEMORY + entrega (Telegram + WhatsApp)

📊 Task Decomposition Matrix

Tipo Tarefa	Agentes	Paralelo?	SLA	Exemplo
Pesquisa Simples	NERD	N/A	1-2 min	"Qual é o preço do ETH?"
Análise Técnica	ANALYTICS + TRADER	SIM	3-5 min	"Analisa ETH/USDC 4h"
Conteúdo Visual	NERD + DESIGNER + TRADER + COPYWRITER	SIM (3 paralelo, 1 seq)	5-7 min	"Conteúdo pool com análise"
Pool Rebalance	DEGEN (approval)	NÃO	5-15 min	"Rebalancear pool"

🔀 Parallelism Decision Tree

Task tem múltiplas subtarefas?

SIM ➜ Subtarefas independentes?

↓

SIM ➜ Max(SLA) < Soma(SLAs)?

↓

SIM = PARALELO (40% faster)

NÃO = SEQUENCIAL

05. Mecanismos de Design & Funcionamento Interno

Como funcionam internamente: approval flow, heartbeat, credential flow, session counter.

✅ Approval Workflow >$100 - Passo a Passo

1

TRADER/ANALYTICS calcula operação, vê que >$100

2

Retorna spec (preço, quantidade, fees, slippage) SEM executar

3

ASPIRA formata mensagem: details + 2-3 alternativas + riscos

4

ASPIRA envia Telegram (tópico correto) + WhatsApp

5

Diego reage com /approve-TRADE, /approve-REBALANCE, ou /reject

6

ASPIRA detecta reação emoji, interpreta comando

7

IF /approve: DEGEN conecta on-chain, executa com spec exata

8

DEGEN retorna tx hash, fees gastas, confirmação de execução

❤️ Heartbeat Mechanism - Monitoramento 24/7

O Que É

Processo automático a cada 2-5 min que: valida saúde sistema, detecta problemas, dispara automações, respeita quiet hours.

Verificações Contínuas

✅ Context usage > 40k? → trigger extraction-v3.sh
✅ Gateway running? → restart if needed
✅ Crons executados 6/6? → alert if falha
✅ 1Password accessible? → fallback if down
✅ Disk space > 1GB? → cleanup if low
✅ MEMORY.md exists? → reconstruct if missing

Quiet Hours Behavior

23h-07h BRT: só alertas CRÍTICOS (>$100 pending, extraction urgent)
11:15-13h BRT: família time, skip non-critical alerts
Horário ativo (07h-23h): alerts normais

🔐 Credential Flow - 1Password Integration

Quando agente precisa de API key para executar:

ASPIRA: op read "op://Aspira/[skill]/[field]"
   Exemplo: op read "op://Aspira/hyperliquid/api_key"

1Password CLI retorna SECRET (in-memory, nunca log)

ASPIRA passa SECRET + task spec para agente

Agente executa API call com SECRET

Resultado retorna, SECRET descartado imediatamente

Zero hardcoding, 100% auditável, rotação centralizada

📊 Session Counter - Auto-Incrementing

Propósito

Rastrear sequência de execuções, audit trail, reproduzibilidade, lifecycle tracking.

Mecanismo

Atual: #51
Incrementa: Automático no extraction-v3.sh (quando contexto >40k)
Armazenamento: MEMORY.md (linha dedicada sempre presente)
Auditoria: memory/logs/extraction-*.log com timestamp

🔄 Diagrama Visual — Ciclo Completo de uma Operação

📥 ENTRADA

Mensagem Diego
Cron automático
Heartbeat alert

🧠 ASPIRA

Analisa contexto
Quiet hours OK?
Decompõe tarefa

💰 VALOR > $100?

Sim → Approval
Não → Executa
direto

1. Agente(s) Spawnados

Paralelo se independentes

2. 1Password Read

op read vault "Aspira"

3. Execução + Retry

3x backoff se falha

4. Memory Update

5 categorias consolidadas

📤 OUTPUT → Telegram tópico certo + WhatsApp (se crítico) + MEMORY.md atualizado + Audit log

17. Automação & Crons — 7 Sistemas Automáticos

Automações agendadas, triggers, execução automática, interação com Diego quando necessário.

📅 Cronograma Completo (em BRT)

Cron Job	Horário BRT	Executor	Ação	Output
Pool Monitor #1	07:15 BRT	DEGEN (Opus 4.6)	Fetch on-chain, calc MICAM, propor rebalance	Telegram (1046) + WhatsApp
Pool Monitor #2	16:15 BRT	DEGEN (Opus 4.6)	Fetch on-chain, calc MICAM, propor rebalance	Telegram (1046) + WhatsApp
Briefing Diário	06:30 BRT	briefing-aggregator (Python)	Twitter + News + FRED + sentiment → resume	Telegram (685) + WhatsApp
Health Check	Every 30 min	health-check.sh (bash)	Gateway OK? Crons OK? Memory OK? Disk OK?	Silencioso se OK, Alert (51) se problema
Memory Extraction v3	On 40k trigger	extraction-v3.sh	5 etapas: detect, route, clean, index, update	memory/* atualizado, session counter ++
Security Audit	Seg 07:00 BRT	security-audit.sh	Zero hardcoding? Perms OK? Backups OK?	Telegram (178) se issue, silent se OK
Instagram Analytics	09:00 BRT	NERD + collector.js v3	Coleta posts + insights → gera dashboard → deploy CF Pages	instagram-analytics-8fl.pages.dev atualizado

1️⃣ Pool Monitoring (2x/dia)

Schedule: 07:15 BRT + 16:15 BRT

Executor: DEGEN (Claude Opus 4.6)
Conexão: ethers.js → Uniswap Position Manager
Posição: #4694494 (ETH/USDC Base)

Fluxo

1. Fetch saldos reais (token0 + token1)
2. Calcular: preço, IL, APY, status
3. IF IN-RANGE: "Status OK, APY 83.85%, continue"
4. IF OUT-OF-RANGE: Alerta + 3 alternativas
5. Diego: /approve-rebalance ou /reject
6. Reportado ao Telegram (1046) + WhatsApp

2️⃣ Briefing Diário (06:30 BRT)

Executor: briefing-aggregator (Python multi-source)

Fontes: Twitter (Bird CLI) + News APIs + FRED macroeconomic + Crypto sentiment (Perplexity)
Processamento: Remove spam → identifica narrativas-chave → resume oportunidades
Output: Market recap estruturado, 3-5 narrativas-chave, 2-3 oportunidades

3️⃣ Health Check (Every 30 min)

Executor: health-check.sh (bash lightweight)

Checks: Gateway running | Context <60% | Crons 6/6 | 1Password OK | Disk >1GB
Behavior: Silencioso se OK. Telegram (51) se problema.
Quiet Hours: Skip non-critical, só alertas CRÍTICOS.

4️⃣ Memory Extraction v3 (On 40k trigger)

Executor: extraction-v3.sh (200 linhas, automática)

ETAPA 1 - DETECT: AI analisa logs, identifica: decisões, mudanças, lições, bloqueios, fatos
ETAPA 2 - ROUTE: Cada item → categoria correta
ETAPA 3 - CLEAN: Delete daily notes >14 dias, keep 5 categorias FOREVER
ETAPA 4 - INDEX: Build BM25 search index
ETAPA 5 - UPDATE: memory/* files + session counter ++ + logs

5️⃣ Security Audit (Weekly, Seg 07:00 BRT)

Executor: security-audit.sh

Verifica: zero hardcoded credentials, arquivo permissions safe, backup integrity, vault access OK
Output: Telegram (178) se issue, silencioso se "zero issues"

6️⃣ Agenda Notifications (30min before event)

Executor: google-agenda-v2 skill (gogcli)

Google Calendar → detecta evento 30min antes → Telegram (192) + WhatsApp notificação

7️⃣ Instagram Analytics (09:00 BRT)

Executor: collector.js v3 (Node.js) + Cloudflare Pages Deploy

Fluxo: Coleta 90 posts recentes + insights via Graph API v22+ → salva SQLite → gera dashboard HTML → deploy Cloudflare Pages
Credenciais: Instagram token + CF API token via 1Password
Output: instagram-analytics-8fl.pages.dev atualizado diariamente
Job ID: 311f6904-7702-4e1c-92c9-f7f5c87162c5

08. Agentes & Especialistas — 9 Operadores

Arquitetura multi-agente: 9 especialistas, modelos otimizados, expertise mapeada.

🤖 9 Agentes - Modelos & Responsabilidades

Agente	Modelo LLM	Especialidade	SLA	Skills Principais
DEV	Claude Opus 4.6	Backend, Smart Contracts, Código Crítico	2-5 min	clanker, solana-dev, viem-integration
NERD	Claude Haiku 4.5	Pesquisa, Análise, Inteligência	1-2 min	perplexity, tavily_*, firecrawl, neynar
DESIGNER	Gemini 3.0 Flash	Visual, Criativo, Assets, Branding	2-3 min	nano-banana-pro, figma, video-frames
COPYWRITER	Claude Haiku 4.5	Conteúdo, Copy, Social Media	1-2 min	neynar, botchan, tts (PT-BR custom)
FRONTEND	Claude Sonnet 4	UI/UX, React, Next.js, Web Apps	3-5 min	modern-frontend-stack, onchainkit, accessibility-toolkit
ANALYTICS	Claude Sonnet 4	Métricas, BI, Dashboards, Análise Quant	2-3 min	divergence-and-volume, FRED API, bankr (portfolio view)
TRADER	Claude Sonnet 4	Trading, Análise Técnica, Sinais	2-3 min	divergence-and-volume, trading-setups, Kraken API
DEGEN ⭐	Claude Opus 4.6	DeFi On-Chain, Pool Management, Execução	1-2 min / Cron 2x/dia	uniswapskill (PRIMARY), bankr, hyperliquid, nado, kraken, veil
ASPIRA	Claude Haiku 4.5	Orquestração, Memória, Heartbeat	<500ms	sessions_spawn, MEMORY.md sync, health-check orchestration

🏗️ 3-Tier Agent Architecture

TIER 1: RESEARCH & ANALYSIS

NERD (pesquisa) + ANALYTICS (análise quant) + TRADER (sinais)

→ Gathering intelligence, technical analysis, market data

TIER 2: EXECUTION (3 Branches em Paralelo)

CODE: DEV + FRONTEND (smart contracts, UI)

CONTENT: DESIGNER + COPYWRITER (visual, text)

DeFi: DEGEN (on-chain operations)

→ Transform analysis into executable actions

TIER 3: ORCHESTRATION

ASPIRA (coordena Tier 1 + 2, monitora, consolida memória)

→ Central nervous system of entire system

10. Skills & API Mapping — Quem Usa O Quê

Inventário completo de 30+ skills categorizadas, qual agente acessa qual API, rate limits.

💰 Cripto & Trading (8 Skills)

Skill	Agentes	API/Protocol	Rate Limit	Status
bankr	DEGEN, TRADER, ANALYTICS	Bankr API (multi-chain DeFi)	100 req/min	✅ ATIVO
hyperliquid	TRADER, DEGEN	Hyperliquid DEX (perpetual futures)	50 req/min	✅ ATIVO
uniswapskill	DEGEN (PRIMARY)	Uniswap v3 PositionManager, ethers.js v6	RPC node limits	✅ PRIMARY
nado	TRADER, DEGEN	NADO Exchange (Solana perpetuals)	Wallet-based (unlimited)	✅ ATIVO
kraken	TRADER, ANALYTICS	Kraken REST API (spot, futures, margin)	15 req/s (public)	✅ ATIVO
clanker	DEV, DEGEN	Clanker SDK (ERC20 deployment)	50 deploys/day	✅ ATIVO
divergence-and-volume	TRADER, ANALYTICS	Technical analysis engine (local)	CPU-limited	✅ ATIVO
veil	DEGEN	Veil Cash (Base ZK privacy)	RPC limits	✅ ATIVO

🔍 Research & Intelligence (5 Skills)

Skill	Agentes	API/Tool	Rate Limit	Status
perplexity	NERD, ANALYTICS	Perplexity API (web search + citations)	20 req/min	✅ ATIVO
tavily_search	NERD, ANALYTICS	Tavily API (search, extract, crawl, map, research)	100 calls/day free	✅ ATIVO
firecrawl	NERD, DESIGNER	Firecrawl API (JS-heavy scraping)	500 free credits	✅ ATIVO
neynar	COPYWRITER, NERD	Neynar API (Farcaster feeds, posts)	100 req/min	✅ ATIVO
botchan	COPYWRITER	Net Protocol (onchain messaging Base)	RPC limits	✅ ATIVO

🎨 Content Creation (6 Skills)

Skill	Agentes	API/Tool	Rate Limit	Status
nano-banana-pro	DESIGNER	Google Imagen 3 (image gen/edit)	100 images/day	✅ ATIVO
video-frames	DESIGNER, COPYWRITER	ffmpeg (local, extract/create clips)	CPU-bound	✅ ATIVO
onchainkit	FRONTEND, DEV	Coinbase OnchainKit (React components)	N/A (npm package)	✅ ATIVO
modern-frontend-stack	FRONTEND	Next.js, React, Tailwind (local)	N/A (local)	✅ ATIVO
figma	DESIGNER, FRONTEND	Figma API (design tokens, exports)	100 files/min	✅ ATIVO
tts	COPYWRITER	Google Cloud TTS (PT-BR custom voice)	5M chars/month free	✅ ATIVO

11. Web Research & Scraping — Guia Completo

Comparativo técnico e didático de todas as ferramentas disponíveis para pesquisa, leitura e extração de dados da web. Inclui casos de uso reais, cenários de falha e pipelines complexos.

🗺️ Os 4 Níveis de Acesso à Web

NÍVEL 1 — Busca Indexada

Retorna lista de resultados (títulos + snippets). Não acessa páginas diretamente.
Ferramentas: web_search (Brave), tavily_search

NÍVEL 2 — Leitura Direta (HTTP)

Faz requisição HTTP e converte HTML em texto. Sem JavaScript.
Ferramentas: web_fetch, tavily_extract, scrapling Fetcher

NÍVEL 3 — Renderização (Browser Real)

Abre browser headless, executa JavaScript, vê o que o usuário veria.
Ferramentas: browser (nativo), firecrawl, scrapling PlayWright

NÍVEL 4 — IA sobre a Web

LLM busca, lê e sintetiza múltiplas fontes com citações. Não retorna dados brutos.
Ferramentas: perplexity, tavily_research

🛠️ Ferramentas em Detalhe

1. web_fetch — Leitura Direta Simples

Atributo	Valor
Tipo	Nativa
Custo	Grátis
Velocidade	⚡⚡⚡ (< 2s)
JS pesado	❌ Não suporta
Anti-bot bypass	❌
Interação	❌
Melhor para	Docs, blogs, sites estáticos
Falha em	React/Angular/SPA, Cloudflare, sites com login

Analogia: imprimir uma página no papel. Vê o HTML "morto", sem JS rodando.

2. Suite tavily_* — 5 Ferramentas em 1

Ferramenta	O que faz	Quando usar
tavily_search	Busca como Google, retorna snippets com relevância	"Quais pools têm maior APY hoje?"
tavily_extract	Extrai conteúdo completo de URLs específicas	"Leia o conteúdo desta URL"
tavily_crawl	Varre site inteiro seguindo links	"Leia toda a documentação deste projeto"
tavily_map	Mapeia estrutura de URLs de um domínio	"Quais páginas existem em clawhub.ai?"
tavily_research	Pesquisa profunda multi-etapas com relatório	"Análise profunda do mercado de L2s"

tavily_search = Google. tavily_extract = Reader Mode. tavily_crawl = robô que lê o site inteiro. tavily_research = analista contratado.

3. web_search (Brave) — Busca Indexada

Atributo	Valor
Tipo	Nativa
Custo	Grátis
Velocidade	⚡⚡⚡
Retorna	Lista de URLs + snippets (não o conteúdo completo)
Melhor para	Descobrir fontes, verificar se notícia circula, encontrar URLs
Falha em	Quando precisa do conteúdo completo da página

4. perplexity — IA com Acesso à Web

Modelo	Uso	Custo Aprox.
sonar	Busca rápida, uso geral	~$1/1k req
sonar-pro	Busca mais profunda	Maior
sonar-reasoning	Raciocínio complexo + web	Maior
sonar-research	Relatório exaustivo multi-fontes	~$0.05-0.10/req

✅ Usar quando: precisa de citações e fontes, síntese de múltiplas fontes, análise atual de mercado.
❌ Não usar quando: precisa de dados brutos estruturados (JSON/CSV), extração de tabelas precisas (pode alucinar números).

Analogia: pesquisador que lê 20 artigos e entrega resumo com referências. Você não lê os artigos — recebe a síntese.

5. firecrawl — Scraping com Chromium na Nuvem

Atributo	Valor
Tipo	Skill instalada
Custo	500 créditos/mês grátis (1 scrape ≈ 1 crédito)
Velocidade	⚡ (média)
JS pesado	✅ Excelente
Anti-bot bypass	⚠️ Cloudflare básico (IPs podem estar em blacklist)
API Key	1Password vault "Aspira" → op://Aspira/Firecrawl/api_key
Melhor para	Sites React/Angular, dashboards DeFi, conteúdo JS-renderizado
Falha em	Cloudflare Enterprise, quando créditos acabam

Analogia: abrir o Chrome, esperar carregar completamente, copiar o texto visível. Funciona em tudo que um browser normal abre.

6. browser (nativo) — Controle Total do Browser

Atributo	Valor
Tipo	Nativo
Custo	Grátis
Velocidade	🐢 Mais lento de todos (3-8s/página)
JS pesado	✅✅ Perfeito
Cloudflare	✅ IP local, não blacklisted
Capacidade única	Clicar, digitar, preencher forms, screenshots, login real
Melhor para	Login em sites, formulários, infinite scroll, análise visual
Falha em	Scraping em escala (muito lento), quando não há browser instalado

7. scrapling — Framework Profissional Local

Modo	O que faz	Quando usar
Fetcher	HTTP simples, rápido	APIs públicas JSON, sites sem proteção
StealthyFetcher	HTTP com fingerprint de browser real	Cloudflare básico/intermediário
PlayWright	Browser headless local completo	Sites que exigem renderização total
Spider	Crawl em escala paralela (Scrapy-like)	100-1000+ páginas com checkpoint

Analogia: suíte completa de ferramentas instalada no servidor. Controle total, sem pagar API, sem limite de créditos.

📊 Tabela Comparativa Geral

Ferramenta	Tipo	JS Pesado	Anti-bot	Interação	Custo	Velocidade	Escala
web_fetch	Nativa	❌	❌	❌	Grátis	⚡⚡⚡	⭐
web_search	Nativa	—	—	❌	Grátis	⚡⚡⚡	⭐⭐
tavily_extract	Nativa	⚠️ Parcial	❌	❌	Grátis*	⚡⚡	⭐⭐
tavily_research	Nativa	—	—	❌	Grátis*	⚡	⭐⭐⭐
perplexity	Skill	—	—	❌	API paga	⚡⚡	⭐⭐⭐
firecrawl	Skill	✅	⚠️ Básico	❌	500/mês	⚡	⭐⭐
browser	Nativo	✅	✅	✅	Grátis	🐢	⭐
scrapling	Skill	✅	✅✅	✅	Grátis	⚡⚡	⭐⭐⭐⭐

❌ Casos que Dão Errado (Falhas Documentadas)

web_fetch no app.uniswap.org

Retorna <div id="root"></div> vazio. React injeta conteúdo via JS depois do load.
Correto: scrapling (PlayWright) ou API direta do Uniswap SDK

firecrawl com Cloudflare Enterprise

IPs dos servidores Firecrawl já em blacklist. Retorna challenge infinito.
Correto: scrapling StealthyFetcher ou browser (IP local)

perplexity para extrair tabela CSV

LLM sintetiza texto, não extrai dados estruturados. Pode alucinar números ou omitir linhas.
Correto: scrapling + CSS selector na tabela

browser para 500 páginas

500 páginas × 5s = ~40 minutos. Sem checkpoint, recomeça do zero se falhar.
Correto: scrapling Spider (concurrent=20, pause & resume)

web_search para ler URL específica

web_search não acessa URLs, retorna lista do índice. Snippet de 200 chars, não conteúdo.
Correto: tavily_extract ou web_fetch na URL direta

tavily_extract em site com paywall

Sem cookies de sessão, redireciona para página de login (Bloomberg, FT).
Correto: browser (login real) ou perplexity (fontes abertas)

🔄 Pipelines Complexos (Cenários Reais)

Pipeline 1 — Briefing de Mercado Diário (Automático 7h BRT)

Etapa 1 → web_search: "crypto news last 24h" → 10 URLs relevantes
Etapa 2 → tavily_extract (paralelo): lê as 10 URLs simultaneamente
Etapa 3 → scrapling Fetcher: CoinGecko API (preços) + DeFiLlama (TVL/APYs) + Fear&Greed
Etapa 4 → perplexity sonar: sintetiza tudo em briefing estruturado com contexto
Etapa 5 → message: envia para Telegram tópico correto
Total: ~3 minutos | Custo: ~$0.05-0.15/dia | Agentes: NERD + perplexity

Pipeline 2 — Monitor de Pool Fora do Range

Etapa 1 → scrapling Fetcher: RPC Base via ethers.js → tick atual, tickLower, tickUpper
Etapa 2 → lógica Python local: calcular se está dentro do range, IL estimado
SE DENTRO: message simples "✅ Pool OK" (custo: $0)
SE FORA: Etapa 3 → perplexity: tendência ETH próximas 24h + análise rebalancear/aguardar
→ Etapa 4 → message com MICAM completo + 3 alternativas
Total: 6s (dentro) / 40s (fora) | Custo: $0 normal / ~$0.05 quando fora

Pipeline 3 — Arbitragem em Tempo Real (<1s)

Abordagem errada: browser (3-8s/página), perplexity (sem dados tick-a-tick), tavily_search (delay de indexação)
Correto: scrapling async paralelo — 3 APIs (Binance + Kraken + Coinbase) em paralelo = ~800ms
→ Se spread > 0.5%: alerta de arbitragem disparado
Custo: $0 (APIs públicas, scrapling local)

Pipeline 4 — Content Intelligence para Posts

Etapa 1 → perplexity sonar: "crypto trending topics today twitter" → narrativas quentes
Etapa 2 → web_search Brave: volume de buscas de cada tema → qual está em alta
Etapa 3 → tavily_extract: lê 3-5 artigos sobre tema escolhido → dados verificáveis
Etapa 4 → scrapling: CoinGecko (preço/variação) + DeFiLlama (TVL se DeFi)
Etapa 5 → COPYWRITER agente: gancho + desenvolvimento + CTA → formatado por plataforma
Variantes: Thread Twitter (mais citações perplexity) | Carrossel (menos dados) | YouTube (mais tavily_extract)

🗺️ Guia de Decisão Rápida

Situação	Ferramenta Certa
Pesquisar um assunto	web_search ou perplexity
Ler página simples (docs, blog)	web_fetch ou tavily_extract
Ler página React/JS	firecrawl ou scrapling
Análise com citações e fontes	perplexity
Clicar, digitar, interagir	browser (único)
Passar Cloudflare pesado	scrapling StealthyFetcher
Coletar 100+ páginas	scrapling Spider
Rodar 24/7 sem custo	scrapling local (cron)
Relatório com múltiplas fontes	tavily_research ou perplexity sonar-research
Extração de tabela estruturada	scrapling + CSS selector
Dados em tempo real (<1s)	scrapling async paralelo (APIs diretas)
Site com paywall	browser (login real) ou perplexity (fontes abertas)

04. Memória v3 — Sistema de Consolidação

Como funciona: 5 categorias permanentes, 40k threshold, BM25+Vector search, extraction-v3.sh automática.

📊 5 Categorias Permanentes (521 linhas total)

Categoria	Arquivo	Linhas	Propósito	Retention
Decisões	memory/decisions.md	63	Escolhas com contexto, motivo, impacto	FOREVER
Mudanças	memory/changes.md	72	Alterações de setup, config, arquitetura	FOREVER
Lições	memory/lessons.md	105	Aprendizados críticos, anti-patterns, rules	FOREVER
Bloqueadores	memory/blockers.md	131	Problemas ativos, status, workarounds	FOREVER (until fixed)
Fatos-Chave	memory/facts.md	150	Estado operacional atual (dinâmico)	FOREVER (updated)

⚙️ 5 Etapas de Extraction v3 (Auto-trigger 40k)

TRIGGER: context_usage > 40k tokens

ETAPA 1: DETECT
  AI analisa logs da sessão
  Identifica: decisões, mudanças, lições, bloqueios, fatos

ETAPA 2: ROUTE
  Route cada item → categoria correta
  "Decidimos usar 40k" → DECISIONS
  "Uniswap v3 problema" → CHANGES ou BLOCKERS

ETAPA 3: CLEAN
  Delete daily notes > 14 dias
  Keep 5 categorias FOREVER
  Archive logs > 30 dias

ETAPA 4: INDEX
  Build BM25 exact keyword index
  Prepare para Vector embeddings (future)

ETAPA 5: UPDATE
  memory/decisions.md
  memory/changes.md
  memory/lessons.md
  memory/blockers.md
  memory/facts.md
  MEMORY.md (índice) sincronizado
  Session counter: #N → #N+1
  Log: memory/logs/extraction-{timestamp}.log
        

🔍 Search - BM25+Vector Híbrido

Método	Tipo Query	Accuracy	Tempo	Quando Usar
BM25 (50%)	Exact keyword matching	95%+ known terms	O(1) rápido	"Em janeiro", "Uniswap", "$100", "Position"
Vector (50%)	Semantic similarity	70% context-aware	O(n) lento	"Qual foi a lição?", "Por que bloqueamos?"
COMBINED	BM25 + semantic	85%+ melhor dos dois	~2sec	Busca geral, queries complexas

12. Fluxos Operacionais — 5 Cenários Reais

Exemplos práticos: Diego comanda → sistema executa → resultado entregue (com timing real).

🔹 Cenário 1: Pesquisa Simples (1-2 min)

1

Diego: "Qual é o preço do ETH agora?"

2

ASPIRA recebe, valida quiet hours

3

Spawn NERD (Haiku 4.5)

4

NERD: Perplexity API → preço atual

5

Resultado: "ETH = $1.847,58 (Coinbase) | +3.2% 24h"

6

Entregue: Telegram + WhatsApp

🔹 Cenário 2: Trade >$100 (Approval Workflow, 5-15 min)

1

Diego: "Analisa ETH/USDC e propõe ordem"

2

ASPIRA spawn ANALYTICS + TRADER (paralelo) = 2-3 min

3

TRADER retorna: 10 ETH @ 1.850 | SL 1.700 | TP 2.100 | Total ~$18.500 (>$100)

4

ASPIRA detecta >$100 → Approval Workflow

5

Telegram (450) + WhatsApp: "Trade proposto: [spec] | Aprova?"

6

Diego: /approve-TRADE ou /reject

7

DEGEN executa on-chain, coloca ordem com SL/TP

8

Result: "Ordem #12345 colocada! Monitorando até TP/SL"

🔹 Cenário 3: Pool Monitoring (Automático, 2x/dia)

Cron: 07:15 BRT + 16:15 BRT (DEGEN Opus 4.6)

Fluxo:
1. DEGEN conecta on-chain, fetch position #4694494
2. Calcular MICAM (preço, IL, APY)
3. IF IN-RANGE: "Status OK, APY 83.85%, continue"
4. IF OUT-OF-RANGE: Alerta + 3 alternativas
5. Diego reage: /approve-rebalance ou /reject
6. Telegram (1046) + WhatsApp reportam resultado

🔹 Cenário 4: Conteúdo Visual (5-7 min paralelo)

Diego: "Crie conteúdo de pool com análise e visuais"

PARALELO: NERD (pesquisa) + DESIGNER (visual) + TRADER (análise técnica) = 3-5 min
SEQUENCIAL: COPYWRITER aguarda saída de 1-3, integra tudo = 2 min adicional
Total: 5-7 min (vs 12-15 sequencial = 40% ganho)
Output: Post formatado + 3 assets visuais + análise técnica, pronto publicar

🔹 Cenário 5: Smart Contract Deploy (7-10 min)

Diego: "Crie token ERC20 + landing page"

PARALELO: DEV (smart contract) + DESIGNER (visual landing) = 4-6 min
SEQUENCIAL: FRONTEND integra interface = 3-4 min adicional
Total: 7-10 min (vs 15-20 sequencial = 40% ganho)
Output: GitHub link + smart contract deployed on Base + landing pronta

15. Erro Handling & Recovery — Resiliência do Sistema

Como o sistema lida com falhas, recuperação, fallbacks, e graceful degradation.

🚨 Tipos de Erro & Respostas

Tipo Erro	Gravidade	Detecção	Ação	Notificação
API Rate Limit	MÉDIA	429 HTTP status	Retry com backoff exponencial, fallback skill	Silent (aguarda 60s)
Gateway Down	CRÍTICA	Health check 30min	Restart OpenClaw, purge stale sessions	Telegram (51) + WhatsApp se 5+ min down
1Password Vault Access	CRÍTICA	op read timeout	Cache último secret conhecido (1h max)	Telegram (4) + WhatsApp se vault down >5min
Memory Extraction Fails	ALTA	extraction-v3.sh exit code != 0	Retry 3x, log error, manual review flag	Telegram (4) - "Memory consolidation FAILED"
Agent Timeout	MÉDIA	SLA exceeded	Kill process, fallback agent ou sequencial	Telegram (28) - "TRADER timeout, trying ANALYTICS"
On-Chain TX Fail	CRÍTICA	Revert, insufficient gas, nonce conflict	DEGEN retries 3x, propõe manualmente se falha	Telegram (51) + WhatsApp - "TX FAILED: [reason]"

🔄 Graceful Degradation Strategy

Skill Unavailable

perplexity down? → Switch tavily_search. Figma down? → Use nano-banana-pro. Uniswap v3? → Fallback Bankr swap.

Agent Overloaded

TRADER busy (>3 spawns)? → Queue ou spawn ANALYTICS. DEV busy? → Fallback FRONTEND (simpler tasks).

Network Issues

RPC node latency >5s? → Try fallback RPC. API down? → Cache last known state. Approval delayed? → Auto-timeout após 30min, abandon operação.

📋 Manual Recovery Checklist

IF system behaving weird:

Kill stale sessions: kill $(pgrep -f 'node.*openclaw')
Restart gateway: openclaw gateway restart
Force memory rebuild: rm /tmp/aspira-* && mkdir -p /home/molt/.openclaw/workspace/memory/backups
Check 1Password: op account list
Validate crons: crontab -l | grep aspira
Clear credential cache: unset ASPIRA_TOPICS_CONTEXT
Manual consolidation: bash /home/molt/.openclaw/workspace/scripts/extraction-v3.sh force
Restart heartbeat: trigger via cron wake event

Diego: Check Telegram (51 Bugs) for any alerts
        

22. Performance & Benchmarks — Velocidade Real

Dados de velocidade real, comparativos paralelo vs sequencial, eficiência de memória.

⚡ Timing Real - Execução Paralelo vs Sequencial

Tarefa	Agentes	Sequencial	Paralelo	Ganho	SLA Target
Pesquisa Simples	NERD	1-2 min	N/A	N/A	1-2 min ✅
Análise Técnica	NERD + TRADER	4-5 min	2-3 min	40-50% faster	2-3 min ✅
Conteúdo Visual	NERD + DESIGNER + TRADER + COPYWRITER	12-15 min	5-7 min	35-40% faster	5-7 min ✅
Trade Approval	ANALYTICS + TRADER + DEGEN	8-10 min	5-7 min	25-30% faster	5-7 min ✅
Smart Contract	DEV + DESIGNER + FRONTEND	15-20 min	7-10 min	40-50% faster	7-10 min ✅

💾 Memory Efficiency - v2 vs v3

Métrica	v2 (160k)	v3 (40k)	Melhoria
Threshold Flush	160k tokens	40k tokens	4x mais ágil
Token Cost/Cycle	~160k per flush	~40k per flush	~50% economia
Context Retained	Perda 70%+	521 permanente	∞ FOREVER
Search Accuracy	Vector 70%	BM25+Vector 85%	2x melhoria

⚙️ Heartbeat Optimization

Cenário	Interval Antes	Interval Agora	Economia API Calls
Horário ativo SEM multi-agentes	1 min	3-5 min	-67% API calls
Horário ativo COM multi-agentes	1 min	2 min	-50% API calls
Quiet hours (23h-07h)	1 min	10 min	-90% API calls
Alertas críticos	1 min	1 min (imediato)	0% delay

06. Operacional — Timezone, Horários & Regras

Regras de operação, horários BRT, quiet hours, padrões de comunicação.

🕐 Timezone & Horário - BRT OBRIGATÓRIO

Regra Permanente (Lição #2026-02-27)

✅ SEMPRE português claro (NUNCA inglês, code-switching bloqueado)
✅ SEMPRE horário Brasília (BRT = UTC-3, BRST = UTC-2)
✅ Nunca "18:47 UTC" para Diego. Cite "15:47 BRT" ou "16:47 BRST"
✅ Conversão automática: APIs retornam UTC → converte para BRT

📅 Diego Working Hours

Período	Horário BRT	Status	Notificações	Comportamento Heartbeat
Quiet Hours (noite)	23:00-07:00	⚠️ SLEEPING	ZERO (except crítico)	Skip checks não-críticos, só >$100 pending + extraction urgent
Horário Ativo	07:00-11:15	✅ ONLINE	Alerts normais	Heartbeat 2-5 min, all checks OK
Pausa Família	11:15-13:00	⚠️ FAMILY TIME	ZERO (except crítico)	Skip checks não-críticos, silencioso
Horário Ativo	13:00-19:00	✅ ONLINE	Alerts normais	Heartbeat 2-5 min, all checks OK
Encerramento	19:00-23:00	✅ ONLINE (diminuindo)	Alerts sutil	Heartbeat 5 min, reduz volume

📱 Canais - Hierarquia & Latência

Prioridade	Canal	Uso	Latência	Quiet Hours
PRIMARY	WhatsApp (+555599096505)	Alertas críticos, approvals, briefing, agenda	<10s	CRÍTICOS APENAS
SECONDARY	Telegram (18 tópicos)	Detalhes, análises, documentação, logs	<5s	CRÍTICOS APENAS
SOCIAL	Discord + Farcaster	Community, broadcasts, social content	<30s	SKIP quiet hours
ASYNC	Telegram archives (tópicos)	Logs, auditoria, referência, trilha	Async	Always recorded

📖 Documentação Obrigatória (Sempre Carregada)

Arquivo	Conteúdo Principal	Carregamento	Função Crítica
SOUL.md	Essência, tom, valores, limites	Boot (automático)	Define atitude de TODO sistema
USER.md	Diego: timezone, horários, preferências, $100 limit	Boot + Daily	Implementado por HEARTBEAT
AGENTS.md	9 agentes: modelos, especialidades, autonomia, SLA, skills	Boot + On-demand	Matriz de decisão
TOOLS.md	30+ skills por domínio (crypto, research, content, dev)	Boot + On-demand	NUNCA invento skills, sempre verifico
MEMORY.md	Índice: 5 categorias permanentes, session counter, lastupdate	Boot + Auto-sync 24/7	Sincronização através sessões
HEARTBEAT.md	Monitoramento contínuo, quiet hours, checks, automações	Boot + On-demand	Guia de execução de health checks

🗓️ Calendário Visual — Rotina Diária ASPIRA (BRT)

00-07h

06-07h

07-11h

11-13h

13-16h

16-19h

19-23h

Heartbeat

😴 10min

⚡ Briefing

✅ 2-3min

👨‍👩‍👧 5min

✅ 2-3min

✅ 3-5min

Alertas

Só crítico

Briefing

Tudo

Suave

Tudo

Reduz

Crons

—

☀️ 06:30

🏊 07:15

—

🏊 16:15

—

Diego

😴 Dormindo

🌄 Boot

💻 Trabalho

🍽️ Família

💻 Trabalho

🏠 Off

☀️ Briefing Diário | 🏊 Pool Monitor | ✅ Ativo | 👨‍👩‍👧 Família (sem interrupção) | 😴 Quiet Hours

✅ Pré-Flight Checklist (Diário)

ANTES de qualquer operação crítica, verificar:

✅ OpenClaw gateway running? → openclaw status
✅ 9/9 agentes online? → check subagents list
✅ 1Password vault "Aspira" accessible? → op read "op://Aspira/test"
✅ Telegram bot conectado? → verify last message <5 min
✅ WhatsApp conectado? → +555599096505 (allowlist)
✅ MEMORY.md sincronizado? → session counter presente
✅ 6/6 crons agendadas? → crontab -l | grep aspira
✅ Memory backups > 24h? → ls -lt /home/molt/.openclaw/workspace/memory/backups/
✅ Disk space > 1GB? → df -h /home/molt
✅ Logs limpos (>30 dias deletados)? → find /home/molt/.openclaw/workspace/memory/logs -mtime +30

Diego: Tudo ✅? Pronto para operar.
        

18. Implementação & Setup — Como Foi Montado

Stack técnico, dependências, arquivos de configuração, scripts, e como manter funcionando.

🛠️ Stack Técnico Completo

Camada	Tecnologia	Versão	Propósito
Runtime	Node.js	v22.22.0	OpenClaw, subagents, scripts automation
Gateway	OpenClaw (WebSocket)	Latest	Central messaging hub para todos canais
Credential Store	1Password CLI (op)	Latest	Zero-hardcoding credential management
Memory Backend	Markdown files (flat-file)	N/A	5 categorias permanentes, versionable
Automation	Bash + crontab	Standard	6 crons agendadas, triggers
Search	BM25 (local) + Vector (future)	v3	Memory indexing, hybrid search
LLM Backbone	Claude (Anthropic) + Gemini (Google)	Multiple versions	9 agentes com modelos otimizados

📁 Estrutura de Diretórios

/home/molt/.openclaw/workspace/
├── SOUL.md                              ← Essência
├── USER.md                              ← Diego profile
├── AGENTS.md                            ← 9 agentes
├── TOOLS.md                             ← 30+ skills
├── MEMORY.md                            ← Índice memória
├── HEARTBEAT.md                         ← Health checks
├── IDENTITY.md                          ← Persona
├── ASPIRA-SYSTEM-MANUAL.html            ← THIS FILE (autoridade central)
├── memory/
│   ├── decisions.md                     ← Decisões (63 linhas)
│   ├── changes.md                       ← Mudanças (72 linhas)
│   ├── lessons.md                       ← Lições (105 linhas)
│   ├── blockers.md                      ← Bloqueadores (131 linhas)
│   ├── facts.md                         ← Fatos-chave (150 linhas)
│   ├── YYYY-MM-DD.md                    ← Daily notes (14 dias, auto-delete)
│   ├── logs/
│   │   ├── extraction-*.log             ← Consolidação logs
│   │   ├── health-check-*.log           ← Health check logs
│   │   └── pool-monitor-*.log           ← Pool monitoring logs
│   └── backups/
│       └── *.md                         ← Auto-backups (7d retention)
├── scripts/
│   ├── extraction-v3.sh                 ← Memory consolidation (AUTO)
│   ├── health-check.sh                  ← 30min heartbeat (CRON)
│   ├── pool-monitoring-degen.sh         ← Pool monitor (2x/dia CRON)
│   ├── security-audit.sh                ← Weekly audit (CRON)
│   └── briefing-aggregator/             ← Daily briefing (Python)
└── docs/
    └── (referências OpenClaw)
        

⚡ Scripts Críticos & Como Rodam

Script	Linguagem	Trigger	SLA	Crítico
extraction-v3.sh	Bash (200 linhas)	On 40k context trigger	3 min	✅ SIM (memory consolidation)
health-check.sh	Bash (150 linhas)	Every 30 min (cron)	2 min	✅ SIM (system health)
pool-monitoring-degen.sh	Bash (wrapper)	07:15 + 16:15 BRT (cron)	5 min	✅ SIM (operations)
security-audit.sh	Bash (100 linhas)	Mon 07:00 BRT (cron)	5 min	✅ SIM (compliance)
briefing-aggregator	Python (300+ linhas)	Daily 06:30 BRT (cron)	10 min	✅ SIM (intelligence)

🔧 Manutenção & Troubleshooting

Problema: Memory extraction não rodando

Verificar: context > 40k? → logs /home/molt/.openclaw/workspace/memory/logs/extraction-*.log
Solução: bash /home/molt/.openclaw/workspace/scripts/extraction-v3.sh force

Problema: Gateway desconectado

Verificar: openclaw status
Solução: openclaw gateway restart

Problema: 1Password timeout

Verificar: op account list
Solução: op signin diegospanevello.1password.com

Problema: Cron não executou

Verificar: crontab -l | grep aspira
Solução: systemctl restart cron (ou manual run)

20. Pool Management Protocol v1.0

Especificação técnica completa: Uniswap V3 Position Manager, ethers.js, MICAM cálculos, verificações on-chain.

📍 Uniswap V3 Position Manager - Addresses & Config

Rede	Position Manager	Router	Factory
Base (PRIMARY)	0xC36442b4a4522E871399CD717aBD90CA34d7c6f7	0x4648a43b2C14Da09FdF82B161150d3F634f40491	0x33128a8fC17869897dcFf533033346eb7E2b80f2
Ethereum	0xC36442b4a4522E871399CD717aBD90CA34d7c6f7	0xE592427A0AEce92De3Edee1F18E0157C05861564	0x1F98431c8aD98523631AE4a59f267346ea31F984
Arbitrum	0xC36442b4a4522E871399CD717aBD90CA34d7c6f7	0xE592427A0AEce92De3Edee1F18E0157C05861564	0x1F98431c8aD98523631AE4a59f267346ea31F984

🔧 Core Methods (ethers.js v6)

// Position Manager ABI - Métodos principais

1. MINT - Criar nova posição
   Params: {
     token0: string,
     token1: string,
     fee: 500 | 3000 | 10000,  // 0.05%, 0.3%, 1%
     tickLower: number,          // Range inferior
     tickUpper: number,          // Range superior
     amount0Desired: BigInt,     // Amount token0
     amount1Desired: BigInt,     // Amount token1
     amount0Min: BigInt,         // Slippage protection token0
     amount1Min: BigInt,         // Slippage protection token1
     recipient: address,
     deadline: number
   }
   Returns: tokenId, liquidity, amount0, amount1

2. INCREASE_LIQUIDITY - Adicionar mais liquidez
   Params: {
     tokenId: number,
     amount0Desired: BigInt,
     amount1Desired: BigInt,
     amount0Min: BigInt,
     amount1Min: BigInt,
     deadline: number
   }
   Returns: liquidity, amount0, amount1

3. DECREASE_LIQUIDITY - Remover liquidez
   Params: {
     tokenId: number,
     liquidity: BigInt,
     amount0Min: BigInt,
     amount1Min: BigInt,
     deadline: number
   }
   Returns: amount0, amount1

4. COLLECT - Coletar fees acumuladas
   Params: {
     tokenId: number,
     recipient: address,
     amount0Max: BigInt,  // type(uint128).max
     amount1Max: BigInt
   }
   Returns: amount0, amount1

5. BURN - Deletar posição vazia
   Params: {
     tokenId: number
   }
        

📊 MICAM - Multi-Indicator Analysis Calculation

Indicador	Fórmula	Uso	Valor Alvo
Impermanent Loss (IL)	IL% = (2 * √(Preço Inicial / Preço Atual) - 1 - Preço Inicial / Preço Atual) * 100	Quantificar risco de preço	<15% ideal
APY Effective	APY = (Fees Anuais / Capital Invested) * 100	Yield de fees	>50% attractive
Bollinger Bands	Middle = SMA(20). Upper = Middle + 2σ. Lower = Middle - 2σ	Detectar volatilidade	Preço fora bands = alerta
RSI (Relative Strength Index)	RSI = 100 - (100 / (1 + RS)), RS = AvgGain / AvgLoss	Detectar reversal	RSI >70 = overbought, <30 = oversold
Range Status	Preço >= tickLower && Preço <= tickUpper	Verificar se em range	IN-RANGE = operativo

🎯 Out-of-Range Detection & Alert

VERIFICAÇÃO A CADA 6 HORAS (pool monitor):

const position = await positionManager.positions(tokenId);
const { tickLower, tickUpper, liquidity } = position;

// Get current price
const slot0 = await pool.slot0();
const currentTick = slot0.tick;
const currentPrice = currentTick * priceMultiplier;

// Check range
if (currentTick < tickLower || currentTick > tickUpper) {
    STATUS = "OUT-OF-RANGE"
    SEVERITY = "HIGH"
    ACTION = "Enviar alerta + 3 alternativas"
} else {
    STATUS = "IN-RANGE"
    ACTION = "Continue operando"
}

// Calculate IL
const initialPrice = /* initial price when minted */
const IL = (2 * sqrt(initialPrice / currentPrice) - 1 - initialPrice / currentPrice) * 100;

// Alert threshold
IF IL > 30% → "IL CRESCENTE, considere rebalancear"
        

💰 Fee Collection Flow

1

Cron: pool-monitoring-degen.sh roda 2x/dia

2

DEGEN conecta on-chain, fetch position #4694494

3

Calcula fees acumuladas: amount0 + amount1

4

IF fees > $50: Call COLLECT method

5

Fees vão direto pro wallet, logged no Telegram

6

ANALYTICS consolida: fees ganhhos no mês

21. Multi-Wallet Discovery Protocol v1.0

Como encontrar TODAS as posições de uma wallet em Uniswap V3, DeFi Llama, DexScreener.

🔍 Fluxo de Descoberta (Passo a Passo)

1

NERD recebe: "Audita wallet 0xabc123..."

2

NERD chama Position Manager: ownerOf(tokenId) loop

3

Identifica todos tokenIds da wallet

4

Para cada tokenId, fetch: token0, token1, fee, tickLower, tickUpper, liquidity

5

DexScreener API: get pool prices, volumes, APY

6

DefiLlama API: get TVL, yield histórico

7

Consolidate: portfolio snapshot com todos positions

8

Enviar relatório Telegram: positions + saldos + IL + APY

🔗 APIs Utilizadas

API	Endpoint	Propósito	Rate Limit
Uniswap V3 Subgraph	https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v3	Query positions by owner, pool data	1000 req/min
DexScreener	https://api.dexscreener.com/latest/dex/pairs/base/:pair	Pool prices, volumes, 24h stats	Free unlimited
DefiLlama	https://yields.llama.fi/pools	Yield farming data, APY historical	Free unlimited
Ethers.js RPC	http://localhost:8545 or Infura/Alchemy	On-chain position data (PositionManager)	1000 req/min (Infura free)

📋 Exemplo: Query Position Manager

// Get all tokenIds para uma wallet
const multicall3 = new ethers.Contract(MULTICALL3_ADDRESS, MULTICALL3_ABI, provider);

// PositionManager: balanceOf(owner) + tokenOfOwnerByIndex(owner, index)
const balance = await positionManager.balanceOf(walletAddress);
const tokenIds = [];
for (let i = 0; i < balance; i++) {
    const tokenId = await positionManager.tokenOfOwnerByIndex(walletAddress, i);
    tokenIds.push(tokenId);
}

// Fetch cada position
for (const tokenId of tokenIds) {
    const position = await positionManager.positions(tokenId);
    const { token0, token1, fee, tickLower, tickUpper, liquidity, feeGrowthInside0LastX128, feeGrowthInside1LastX128 } = position;
    
    // Get current prices
    const pool = new ethers.Contract(poolAddress, POOL_ABI, provider);
    const slot0 = await pool.slot0();
    const currentTick = slot0.tick;
    
    // Calculate MICAM
    const IL = calculateIL(tickLower, tickUpper, currentTick);
    const APY = calculateAPY(liquidity, fees24h);
    
    console.log(`TokenId ${tokenId}: Token0=${token0}, Token1=${token1}, IL=${IL}%, APY=${APY}%`);
}
        

14. Approval System — Webhook & Controle $100+

Como reações do Diego (via Telegram emoji/comando) voltam pro sistema e disparam execução.

🔄 Sequence Diagram: Diego → Approval → Execution

1

TRADER calcula operação >$100 USD

2

ASPIRA formata: "ETH/USDC | 10 @ 1850 | SL 1700 | TP 2100 | Total: $18,500"

3

ASPIRA envia DUPLO: • Telegram tópico 450 (TRADING) • WhatsApp +555599096505
Mensagem inclui: [Approve Button] / [Reject Button]

4

Diego reage no Telegram: /approve-TRADE ou /reject

5

Telegram Bot detecta reação: • Message ID: {messageId} • Reaction: /approve-TRADE • Sender: {userId} = 1166784883 (Diego)

6

OpenClaw Message Router processa: • Parse command: APPROVE-TRADE • Lookup operação pendente em memory • Validate: assinante é Diego? SIM • Status: APPROVED

7

ASPIRA detecta aprovação: • Spawn DEGEN (Opus 4.6) • Pass credential: op read "op://Aspira/hyperliquid/api_key" • Pass spec: {"symbol": "ETH/USDC", "size": 10, "entry": 1850, "SL": 1700, "TP": 2100}

8

DEGEN executa on-chain: • Connect Hyperliquid API • POST /orders: {"symbol": "ETH/USDC", "size": 10, "limit_px": 1850, ...} • Recebe: orderId, tx_hash • Set SL/TP linked

9

DEGEN reporta: • Ordem #12345 colocada ✅ • TX: 0xabc123... • Entry: $1850 • Size: 10 ETH • Risk: $1,500 (SL) • Reward: $2,500 (TP) • R:R = 1:1.67

10

ANALYTICS monitora: • Query order status a cada 10s • IF preço toca TP: close profit • IF preço toca SL: close loss • Log resultado em MEMORY

⏰ Timing & Latências

Etapa	Tempo	Componente	Crítico
1-2: Cálculo	10-30s	TRADER	SIM
3: Envio mensagem	<2s	OpenClaw	SIM
4: Diego reage	1-600s	Humano	NÃO
5-6: Bot detecta	1-5s	Telegram Bot	SIM
7: Spawn DEGEN	5-15s	OpenClaw Sessions	SIM
8: Executa on-chain	2-5s	API call + network	SIM
Total (sem Diego): 18-57s

🔐 Security: Approval Validation

BEFORE executing operação aprovada:

1. Verify sender:
   IF message.sender_id != "1166784883" (Diego)
   THEN reject, log suspicious activity

2. Verify operation exists:
   IF operation_id not in pending_approvals
   THEN reject, "operação não encontrada"

3. Verify amount matches:
   IF operation.amount != approval_message.amount
   THEN reject, "amount changed - reapprove"

4. Verify age < 30 min:
   IF now() - approval_time > 1800s
   THEN reject, "approval expirada"

5. Execute with atomic transaction:
   TRY: place order on exchange
   ON_SUCCESS: mark operation as executed, log tx_hash
   ON_FAILURE: revert approval, alert Diego

6. Log everything:
   - Timestamp
   - Operação spec
   - Aprovador (Diego)
   - TX hash
   - Result
   → Telegram (178 - Auditoria)
        

16. Error Codes — Referência Técnica Completa

Todos os erros possíveis (E001-E050), causas, e ações de recuperação automática.

🔴 Erro Codes Mapeado Completo

Código	Erro	Causa	Severity	Recovery Automático	Alert
E001	API Rate Limit	429 HTTP status	MÉDIA	Retry com backoff exponencial (60s)	Silent
E002	Gateway Down	WebSocket closed	CRÍTICA	openclaw gateway restart	Telegram (51) + WhatsApp
E003	1Password Vault Access Denied	Auth token expired	CRÍTICA	op signin diegospanevello.1password.com	Telegram (4) + WhatsApp
E004	Insufficient Gas	TX reverted (gas estimation wrong)	ALTA	DEGEN recalcula, retry com +20% gas	Telegram (51)
E005	Nonce Conflict	Pending TX in mempool	ALTA	Bump gas +50%, new nonce, retry	Telegram (51)
E006	Slippage Exceeded	Price moved >2% from estimation	MÉDIA	Abandon, propose new price, manual approval	Telegram (450) + WhatsApp
E007	Position Out of Range	Price moved outside LP bounds	ALTA	Alert, propose 3 rebalance options	Telegram (1046) + WhatsApp
E008	Agent Timeout	SLA exceeded (5+ min)	MÉDIA	Kill process, fallback agent, try sequencial	Telegram (28)
E009	Memory Extraction Fails	Script exit code != 0	ALTA	Retry 3x, log error, flag para review manual	Telegram (4) + WhatsApp
E010	RPC Node Latency >5s	Network issue or node overloaded	MÉDIA	Switch fallback RPC, retry	Silent (auto-handled)
E011	Approval Timeout (>30 min)	Diego não reagiu ao approval	BAIXA	Auto-cancel, abandon operação	Telegram (450)
E012	Disk Space < 500MB	Storage critical	ALTA	Delete logs >60 dias, archive backups	Telegram (4)

🔧 Recovery Playbooks

E001: API Rate Limit

Symptom: 429 status code
Auto-Action: Esperar 60s, retry com exponencial backoff
If Still Fails: Switch para fallback API/skill
Diego Alert: Não (transparente)

E002: Gateway Down

Symptom: WebSocket connection refused
Auto-Action: openclaw gateway restart
Max Retries: 3 vezes
If Still Fails: Alert Diego, parar automações
Diego Alert: Telegram (51) + WhatsApp (CRÍTICO)

E004: Insufficient Gas

Symptom: TX reverted "out of gas"
Auto-Action: Recalculate gas, retry com +20% estimate
If Still Fails: Abandon, propose manualmente com novo gas estimate
Diego Alert: Telegram (51) com novo spec

23. Cost Tracking & Budget — Controle de Gastos

Quanto custa tudo: tokens LLM, APIs, on-chain gas, budget alerts.

💸 Cost per Operation (Estimado)

Operação	Agent + Modelo	Custo Tokens	API Calls	Custo Total
Pesquisa Simples	NERD (Haiku 4.5)	~500 tokens	1x Perplexity	~$0.05
Análise Técnica	TRADER (Sonnet 4) + ANALYTICS (Sonnet 4)	~2,000 tokens	2x Tavily + 1x divergence-volume	~$0.15
Conteúdo Visual	NERD + DESIGNER + TRADER + COPYWRITER	~5,000 tokens	1x nano-banana-pro + 1x figma export	~$0.40
Smart Contract Deploy	DEV (Opus 4.6) + FRONTEND (Sonnet 4)	~8,000 tokens	1x clanker deployment	~$0.80 + gas
Pool Monitor (1x)	DEGEN (Opus 4.6)	~1,000 tokens	1x RPC call + DexScreener	~$0.10 + gas (~$2)
Briefing Diário (1x)	briefing-aggregator (Python)	~3,000 tokens	3x API (Twitter, News, FRED)	~$0.30

📊 Monthly Cost Breakdown

Categoria	Frequency	Custo/Unidade	Custo Mensal	% do Budget
LLM Tokens (Claude + Gemini)	Contínuo	~$0.15-0.80/op	~$150-200	50%
APIs (Perplexity, Tavily, etc)	Contínuo	~$0.01-0.10/call	~$50-80	20%
On-Chain Gas (Base, Ethereum)	Per TX	~$2-50/tx	~$100-200	25%
Infrastructure (1Password, OpenClaw)	Fixed	$0 (free tier)	$0	0%
TOTAL			~$300-480	100%

🚨 Budget Alerts & Thresholds

Threshold	Trigger	Ação	Alert Destination
$50 (operação)	Single TX > $50	Require approval /approve-TRADE	Telegram + WhatsApp
$100 (daily)	Daily total > $100	Resume, alert Diego	Telegram (36 - Custos) + WhatsApp
$300 (monthly)	Monthly burn > $300	Reduce operations, optimize	Telegram (36) + ASPIRA log
API Quota	Tavily 100 calls/day esgotadas	Switch fallback API	Telegram (6 - Skills)

13. Data Flow — Arquitetura em Movimento

Como dados fluem pelo sistema: entrada → processamento → decisão → execução → saída → memória.

🔄 Complete Data Flow

┌─────────────────────────────────────────────────────────────────────────────────┐
│                                INPUT LAYER                                       │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  Diego (WhatsApp)  →  Message Gateway  →  ASPIRA (orchestrator)                │
│                                             │                                     │
│  Telegram Webhook  →  Message Handler  →   ├→ Validate quiet hours             │
│  (approval reactions)                       │   ├→ Check USER.md context       │
│                                             │   ├→ Parse command type          │
│  Scheduled Crons   →  Cron Executor    →   └→ Route to handler                │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           DECISION & ROUTING LAYER                               │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  ASPIRA Decision Tree:                                                           │
│  ├─ Type: RESEARCH?        → Spawn NERD (Haiku)                                │
│  ├─ Type: DESIGN?          → Spawn DESIGNER (Flash3)                           │
│  ├─ Type: TRADING?         → Spawn ANALYTICS + TRADER (paralelo)               │
│  ├─ Type: DEFI?            → Spawn DEGEN (Opus 4.6)                           │
│  └─ Type: CONTENT?         → Spawn NERD + DESIGNER + TRADER + COPYWRITER      │
│                                                                                   │
│  Parallelism Check:                                                              │
│  ├─ Multiple subtasks? YES                                                       │
│  ├─ Independent? YES                                                             │
│  ├─ Max(SLA) < Sum(SLAs)? YES → PARALLEL                                       │
│  └─ Otherwise → SEQUENTIAL                                                       │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                            EXECUTION LAYER (Multi-Agent)                         │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  AGENT 1          AGENT 2          AGENT 3          AGENT 4                     │
│  ────────         ────────         ────────         ────────                     │
│  ↓ Init           ↓ Init           ↓ Init           ↓ Init                       │
│  Load TOOLS.md    Load TOOLS.md    Load TOOLS.md    Load TOOLS.md               │
│  Get Credentials  Get Credentials  Get Credentials  Get Credentials             │
│  (op read 1Pass)  (op read 1Pass)  (op read 1Pass)  (op read 1Pass)            │
│  ↓ Execute        ↓ Execute        ↓ Execute        ↓ Execute                   │
│  Call APIs        Call APIs        Call APIs        Call APIs                   │
│  Process Data     Process Data     Process Data     Process Data               │
│  ↓ Return         ↓ Return         ↓ Return         ↓ Return                    │
│  Output #1       Output #2        Output #3        Output #4                   │
│                                                                                   │
│  [All run in parallel, max time = max(SLA1, SLA2, SLA3, SLA4)]                 │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                         APPROVAL & DECISION LAYER                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  Cost Check:                                                                     │
│  ├─ Estimated Cost > $100?                                                       │
│  │  ├─ YES: CREATE approval message                                             │
│  │  │   ├─ Telegram tópico correto (450, 1046, etc)                           │
│  │  │   ├─ WhatsApp +555599096505                                              │
│  │  │   └─ WAIT for Diego reaction: /approve or /reject (30 min timeout)       │
│  │  └─ NO: Continue to execution                                               │
│  │                                                                                │
│  Approval Handler (on Diego reaction):                                           │
│  ├─ Parse: sender_id == Diego?  YES                                            │
│  ├─ Parse: command == /approve? YES                                            │
│  ├─ Lookup: operation still pending? YES                                        │
│  └─ APPROVE: continue to execution                                              │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                      ON-CHAIN / EXTERNAL EXECUTION                               │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  DEGEN / EXECUTOR Agent:                                                         │
│  ├─ IF type == TRADE:                                                            │
│  │  └─ Connect Hyperliquid/Kraken/NADO                                         │
│  │     ├─ Place order (spec exact)                                              │
│  │     └─ Get orderId, tx_hash                                                  │
│  ├─ IF type == POOL:                                                             │
│  │  └─ Connect Uniswap V3 on-chain                                             │
│  │     ├─ Call PositionManager methods                                          │
│  │     └─ Get tx_hash, status                                                   │
│  └─ IF type == SMART CONTRACT:                                                  │
│     └─ Deploy via clanker / DEV                                                │
│        ├─ Get contract address                                                  │
│        └─ Get verification link                                                 │
│                                                                                   │
│  Return: {tx_hash, orderId, confirmation, result}                              │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                        CONSOLIDATION & MONITORING LAYER                          │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  ASPIRA Consolidates:                                                            │
│  ├─ Merge all agent outputs                                                      │
│  ├─ Calculate final result                                                       │
│  ├─ IF Trade: ANALYTICS monitors until TP/SL                                    │
│  ├─ IF Pool: DEGEN continues monitoring 2x/day                                  │
│  ├─ IF Content: Deliver to channels                                             │
│  └─ Timestamp result, add to MEMORY.md                                          │
│                                                                                   │
│  Store in Memory Categories:                                                     │
│  ├─ decisions.md (if strategic choice)                                          │
│  ├─ changes.md (if system altered)                                              │
│  ├─ facts.md (current state update)                                             │
│  └─ YYYY-MM-DD.md (daily notes, auto-delete 14 days)                           │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        ↓
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           OUTPUT & DELIVERY LAYER                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                   │
│  Primary (WhatsApp):                                                             │
│  └─ Send to +555599096505 (critical alerts + approvals)                        │
│                                                                                   │
│  Secondary (Telegram 18 Topics):                                                │
│  ├─ Topic 450 (TRADING) ← Trade results                                        │
│  ├─ Topic 1046 (DeFi) ← Pool monitoring                                        │
│  ├─ Topic 685 (Briefing) ← Daily intelligence                                  │
│  ├─ Topic 51 (Errors) ← Alerts & failures                                      │
│  ├─ Topic 178 (Auditoria) ← Logs & audit trail                                │
│  └─ Topic 4 (Infra) ← System updates                                           │
│                                                                                   │
│  Tertiary (Social):                                                              │
│  └─ Discord, Farcaster, Twitter (async, automated posting)                    │
│                                                                                   │
└─────────────────────────────────────────────────────────────────────────────────┘

⏰ Latency Breakdown (Total Flow)

Stage	Latency	Variability	Bottleneck
Input → Decision (stages 1-2)	100-500ms	Low (OpenClaw internal)	None
Agent Execution (stage 3)	1-5 min (paralelo) / 5-15 min (seq)	High (API network, LLM speed)	API calls + LLM inference
Approval (stage 4)	1-600s (depends on Diego)	Very high (human)	Diego reaction time
On-Chain Execution (stage 5)	2-5s (order placement) / 12-60s (TX confirm)	High (blockchain network)	Network latency + gas price
Consolidation (stage 6)	1-3s	Low	None
Delivery (stage 7)	<2s (Telegram) / <5s (WhatsApp)	Medium (network)	Message provider network
Total (without approval)	5-25 min
Total (with approval)	6-625 min (!)		Diego reaction

09. Decision Tree — Como Escolher o Agente Certo

Quando usar qual agente? Matriz decisória completa com critérios.

🌳 Decision Tree: Como ASPIRA Escolhe Agente

IF command contains: ["preço", "pesquisar", "informação", "dado", "notícia"]
  → SPAWN NERD (Haiku 4.5)
     └─ SLA: 1-2 min
     └─ Skills: perplexity, tavily, firecrawl, neynar

ELSE IF command contains: ["design", "visual", "imagem", "logo", "branding", "asset"]
  → SPAWN DESIGNER (Flash3)
     └─ SLA: 2-3 min
     └─ Skills: nano-banana-pro, figma, video-frames

ELSE IF command contains: ["código", "contrato", "deploy", "smart contract", "token", "erc20"]
  → SPAWN DEV (Opus 4.6)
     └─ SLA: 2-5 min
     └─ Skills: solana-dev, clanker, viem-integration

ELSE IF command contains: ["trade", "vender", "comprar", "ordem", "futures", "alavanca"]
  → SPAWN ANALYTICS + TRADER (paralelo)
     ├─ ANALYTICS (Sonnet 4)
     │  └─ SLA: 2-3 min
     │  └─ Skills: divergence-volume, FRED, kraken
     └─ TRADER (Sonnet 4)
        └─ SLA: 2-3 min
        └─ Skills: divergence-volume, trading-setups

ELSE IF command contains: ["pool", "liquidez", "yield", "APY", "LP", "rebalance"]
  → SPAWN DEGEN (Opus 4.6)
     └─ SLA: 1-2 min / Cron 2x/dia
     └─ Skills: uniswapskill, bankr, hyperliquid, nado, kraken, veil

ELSE IF command contains: ["conteúdo", "post", "copy", "caption", "thread", "newsletter"]
  → SPAWN NERD + DESIGNER + TRADER + COPYWRITER (4 paralelo)
     ├─ NERD (1 min)         → Research, facts
     ├─ DESIGNER (2 min)     → Visual assets
     ├─ TRADER (2 min)       → Market analysis
     └─ COPYWRITER (2 min)   → Write copy
     └─ CONSOLIDATE (1 min)  → Final content
     └─ Total SLA: ~5-7 min (vs 10-15 seq)

ELSE IF command contains: ["interface", "app", "website", "ui/ux", "react", "next.js"]
  → SPAWN FRONTEND (Sonnet 4)
     └─ SLA: 3-5 min
     └─ Skills: modern-frontend-stack, onchainkit, accessibility-toolkit

ELSE
  → SPAWN NERD (fallback Haiku 4.5)
     └─ "Not sure, searching for info..."
        

📊 Agent Selection Matrix

Scenario	Agent(s)	Paralelo?	SLA	Cost	Primary Skills
"ETH price?"	NERD	N/A	1-2 min	$0.05	perplexity
"Analyze ETH/USD"	ANALYTICS + TRADER	YES	2-3 min	$0.15	divergence-volume, tavily
"Make pool logo"	DESIGNER	N/A	2-3 min	$0.10	nano-banana-pro, figma
"Create post + visuals"	NERD + DESIGNER + TRADER + COPYWRITER	YES	5-7 min	$0.40	All content skills
"Deploy token"	DEV + FRONTEND	YES	5-8 min	$0.80 + gas	clanker, onchainkit
"Monitor pools"	DEGEN (cron 2x/dia)	N/A	5 min	$0.10 + gas	uniswapskill, DexScreener
"Trade ETH"	ANALYTICS + TRADER → DEGEN	YES	5-15 min (+ approval)	$0.20 + fees	hyperliquid, bankr

🎯 Criteria for Parallelism Decision

Question	Answer	Next
Task has multiple subtasks?	NO	→ Sequential (1 agent)
Subtasks are independent?	NO	→ Sequential (dependency order)
Agent 1 needs Agent 2 output?	YES	→ Sequential (Agent 2 AFTER Agent 1)
Max(SLA) < Sum(SLAs) / N?	YES	→ PARALLEL (40% faster)
Resource contention possible?	YES	→ Sequential (avoid competition)
Cost > $100?	YES	→ Require approval before executing

07. Segurança & Credenciais — 1Password

Todos os secrets: APIs, wallets, keys. Paths estruturados, sem hardcoding, auditável.

🔐 1Password Vault Structure: "Aspira"

Path	Tipo	Agente(s) Acesso	Usar com	Rotation
op://Aspira/hyperliquid/api_key	API Key	TRADER, DEGEN	hyperliquid skill	Monthly
op://Aspira/hyperliquid/private_key	Private Key	DEGEN	Signing TXs	Never
op://Aspira/kraken/api_key	API Key	TRADER, ANALYTICS	kraken skill	Monthly
op://Aspira/kraken/private_key	API Secret	TRADER, ANALYTICS	kraken skill	Monthly
op://Aspira/nado/wallet_key	Seed Phrase	TRADER, DEGEN	nado skill (Solana wallet)	Never
op://Aspira/bankr/api_key	API Key	DEGEN, ANALYTICS	bankr skill (DeFi)	Monthly
op://Aspira/perplexity/api_key	API Key	NERD, ANALYTICS	perplexity skill	Quarterly
op://Aspira/tavily/api_key	API Key	NERD, ANALYTICS	tavily_search skill	Quarterly
op://Aspira/firecrawl/api_key	API Key	NERD, DESIGNER	firecrawl skill	Quarterly
op://Aspira/neynar/api_key	API Key	COPYWRITER, NERD	neynar skill (Farcaster)	Quarterly
op://Aspira/groq/api_key	API Key	DEV, NERD (fallback LLM)	Groq API alternative	Quarterly
op://Aspira/wallet/privy_key	Private Key	DEGEN (Bankr)	Privy wallet (custody limits)	Never
op://Aspira/google/service_account	JSON Key	ANALYTICS (Google Calendar)	google-agenda-v2 skill	Quarterly
op://Aspira/figma/personal_token	API Token	DESIGNER, FRONTEND	figma skill	Quarterly

🔧 Como Usar (Padrão)

# Sempre usar esse padrão em todos agentes:

CREDENTIAL="op read \"op://Aspira/[skill]/[field]\""
API_KEY=$(eval $CREDENTIAL)

# Exemplo 1: Hyperliquid
HYPER_KEY=$(op read "op://Aspira/hyperliquid/api_key")
HYPER_SECRET=$(op read "op://Aspira/hyperliquid/private_key")

# Exemplo 2: Kraken
KRAKEN_KEY=$(op read "op://Aspira/kraken/api_key")
KRAKEN_SECRET=$(op read "op://Aspira/kraken/private_key")

# Dentro do agente (Node.js):
const apiKey = execSync('op read "op://Aspira/[skill]/[field]"').toString().trim();

# NUNCA fazer isso:
❌ const API_KEY = "sk_abc123..."  // HARDCODED - PROIBIDO
✅ const API_KEY = execSync('op read "op://Aspira/skill/api_key"').toString().trim();
        

🔄 Credential Rotation Schedule

Frequency	Credenciais	Ação	Responsável
Monthly	API Keys (Hyperliquid, Kraken, Bankr, etc)	Regenerate no exchange, update 1Password	Diego (manual)
Quarterly	API Keys (Perplexity, Tavily, Neynar, Google, Figma)	Regenerate, update 1Password	Diego (manual)
Never	Private Keys (Wallets), Seed Phrases	Keep in vault, NEVER share	ASPIRA (protect)
On Expiry	Google Service Account (expires 1 year)	Regenerate JSON, update 1Password	Diego (calendar reminder)

🚨 Security Best Practices

✅ Fazer:

✓ Use op read SEMPRE
✓ Store credentials in 1Password vault
✓ Rotate API keys monthly
✓ Log all credential access (op logs)
✓ Use IP whitelisting when available
✓ Enable MFA na conta 1Password

❌ NÃO Fazer:

✗ Hardcode API keys em código
✗ Commit .env files ao git
✗ Share credentials via email/Slack
✗ Use same key para múltiplas services
✗ Leave credentials na browser console
✗ Forget to rotate keys

🔐 Audit Trail:

1Password logs TODAS as reads:
→ Menu 1Password CLI: `op item list --vault Aspira`
→ Cada acesso timestamped e rastreável
→ Diego pode auditar: "Quem acessou qual key?"

24. Fluxos Visuais & Casos de Uso — Visão Completa

Arquitetura em movimento: diagramas visuais completos de todos os fluxos principais, mais casos de uso além do perfil Diego — criadores de conteúdo, investidores, comunidades, empresas.

🧠 Fluxo 1 — Orquestração Central (Visão Completa)

Como um comando vira resultado — da mensagem ao Telegram

📱 WhatsApp

💬 Telegram

🕐 Cron Job

💓 Heartbeat

↓

🫡 ASPIRA — Orquestrador Central

Analisa → Decompõe → Decide paralelo/sequencial → Spawna agentes → Consolida

Quiet Hours Check $100 Approval Memory Sync Error Recovery

↓

RESEARCH

🔍 NERD
📊 ANALYTICS
📈 TRADER

EXECUTION

💻 DEV
🎨 DESIGNER
✍️ COPYWRITER
🖥️ FRONTEND

ON-CHAIN

🦊 DEGEN
Uniswap v3/v4
Hyperliquid
Base + ETH

↓

📱 WhatsApp

💬 Telegram (tópico certo)

💾 MEMORY.md

⛓️ On-Chain TX

💾 Fluxo 2 — Ciclo de Vida da Memória v3

📥

ENTRADA

Conversa, comando, decisão, erro, fato novo

→

🔄

TRIGGER 40k

extraction-v3.sh detecta contexto crítico

→

🗂️

CLASSIFY

AI roteia para 1 das 5 categorias

📌

decisions.md

Escolhas estratégicas permanentes

📝

changes.md

Alterações de setup e config

💡

lessons.md

Aprendizados e best practices

⚠️

blockers.md

Problemas ativos + workarounds

📊

facts.md

Estado atual: wallets, pools, crons

↓ BM25 + Vector Search Index reconstruído automaticamente ↓
Session counter incrementa → MEMORY.md atualizado → Nova sessão herda tudo

🏊 Fluxo 3 — Pool Monitoring Automático (2x/dia)

07:15 BRT

Cron dispara
DEGEN spawn
(Opus 4.6)

→

ON-CHAIN

ethers.js → Base RPC
Position #4694494
tick + balances

→

MICAM

Bollinger + Fib
RSI + MACD + Vol
Preço + IL + APY

→

IN-RANGE?

Tick entre
tickLower e
tickUpper?

✅ SIM — Dentro do Range

→ "Pool OK"
→ APY atual + IL estimado
→ Fees acumuladas
→ Telegram (1046): status simples
→ Custo: $0

⚠️ NÃO — Fora do Range

→ perplexity: tendência ETH 24h
→ 3 alternativas de range
→ MICAM score por alternativa
→ Telegram (1046) + WhatsApp
→ Diego: /approve-rebalance ou /reject

🎬 Fluxo 4 — Criação de Conteúdo Paralelo (5-7 min)

Exemplo: "Crie post sobre ETH atingindo ATH com análise técnica e visual"

ASPIRA recebe demanda

Decompõe em 4 subtarefas independentes → PARALELO

↓ spawn paralelo

🔍

NERD

Dados: preço histórico, volume, on-chain metrics, narrativas

~90s

📈

TRADER

Análise técnica: suportes, resistências, targets, RSI, MACD

~120s

🎨

DESIGNER

3 assets: cover, infográfico técnico, carrossel slide 1

~180s

📊

ANALYTICS

Comparativo: ETH vs BTC vs SOL, dominância, correlação

~90s

↓ ASPIRA consolida (~180s = max dos paralelos)

✍️ COPYWRITER (sequencial — usa outputs anteriores)

Gancho viral + storytelling técnico + CTA → formatado por plataforma

+120s

↓ Total: ~5 minutos (vs 15 sequencial)

📸

Instagram

Carrossel 5-8 slides + legenda gancho

🐦

Twitter/X

Thread 8-12 tweets + chart

▶️

YouTube

Roteiro estruturado + thumbnail

💬

Discord

Post educativo + poll

⛓️ Fluxo 5 — Deploy Smart Contract + Frontend (7-10 min)

Exemplo: "Crie token ERC20 com landing page + deploy na Base"

T=0

ASPIRA decompõe: DEV (contrato) + DESIGNER (visual) → PARALELO

T+2min

DEV: Solidity ERC20 pronto (clanker ou raw) | DESIGNER: logo + banner prontos

T+4min

DEGEN: deploy on-chain Base via Factory → recebe contract address → manda para FRONTEND

T+6min

FRONTEND: Next.js landing com OnchainKit (buy button + wallet connect) usando assets do DESIGNER

T+8min

✅ Entregue: contract address + GitHub repo + landing URL + COPYWRITER faz post de lançamento

☀️ Fluxo 6 — Briefing Diário Automático (06:30 BRT)

🐦

Twitter/X

Bird CLI: trending crypto, narrativas, KOLs

📰

News APIs

CoinDesk, CoinTelegraph, Decrypt, Reuters

🏦

FRED API

DXY, juros, inflação, liquidez macro

🧠

Perplexity

Sentiment AI + análise cross-fonte

↓ briefing-aggregator.py processa tudo

🔥 3-5 Narrativas-Chave

O que está dominando o mercado hoje, quais teses estão em alta

💰 2-3 Oportunidades

Setups técnicos, eventos catalyst, arbitragem possível

⚠️ Riscos do Dia

Macro eventos, FUD relevante, liquidações, regulação

→ Telegram (685 Daily Briefing) + WhatsApp pessoal

🚀 Casos de Uso Além do Diego — Para Quem Mais Serve

👥 Perfil 1 — Criador de Conteúdo Cripto (Creator Economy)

Necessidade	Agentes	Output	Tempo
Post diário sobre token em alta	NERD + TRADER + DESIGNER + COPYWRITER	Carrossel pronto + caption + análise técnica	5-7 min
Thread explicando DeFi para iniciantes	NERD (pesquisa) + COPYWRITER (didática)	Thread 10 tweets, linguagem acessível	3-4 min
Roteiro vídeo YouTube sobre L2s	NERD + ANALYTICS + COPYWRITER	Roteiro estruturado com dados verificáveis	5-8 min
Newsletter semanal	NERD + ANALYTICS + COPYWRITER	Email formatado com seções e dados	8-12 min
Thumbnail para vídeo viral	DESIGNER (nano-banana-pro)	3 opções de thumbnail em estilos diferentes	2-3 min

💼 Perfil 2 — Investidor DeFi (Yield Farming + Pools)

Necessidade	Agentes	Output	Tempo
Monitorar pools 2x/dia automaticamente	DEGEN (cron)	Status + MICAM + proposta rebalance se necessário	Automático
Encontrar melhor pool para depositar $500	NERD + ANALYTICS + DEGEN	Top 5 pools por APY/risco, com análise IL	3-5 min
Coletar fees acumuladas	DEGEN (ethers.js)	Fees em USD por posição + sugestão coletar/reinvestir	1-2 min
Análise de impermanent loss histórica	ANALYTICS + NERD	IL calculado por período, comparativo com hold	2-3 min
Rebalancear portfolio DeFi	DEGEN + TRADER + ANALYTICS	Proposta de rebalance + execução pós-approval	5-15 min

📊 Perfil 3 — Trader Técnico (Swing + Scalp)

Necessidade	Agentes	Output	Tempo
Setup de entrada com múltiplos indicadores	TRADER + ANALYTICS	Entry, SL, TP, R:R, confidence %, timeframe	2-3 min
Monitorar 5 pares simultaneamente	5x NERD em paralelo	Alertas quando qualquer par atinge nível	Automático
Backtesting de estratégia	ANALYTICS + DEV	Script Python + resultados históricos	5-10 min
Executar ordem em Hyperliquid	TRADER (análise) + DEGEN (exec)	Ordem colocada com SL/TP linked	2-4 min
Relatório de performance mensal	ANALYTICS	P&L, win rate, drawdown, melhores setups	3-5 min

🏢 Perfil 4 — Comunidade Cripto / DAO

Necessidade	Agentes	Output	Tempo
Briefing automático para membros	NERD + COPYWRITER (cron)	Resumo diário entregue ao Discord/Telegram da comunidade	Automático
Responder dúvidas técnicas de membros	NERD + COPYWRITER	Resposta didática com fontes	1-2 min
Criar proposta de governança	NERD + ANALYTICS + COPYWRITER	Documento formatado com dados e justificativas	5-8 min
Monitorar saúde do treasury	DEGEN + ANALYTICS	Dashboard: saldos, APY, exposição, riscos	2-3 min
Deploy de NFT collection	DEV + DESIGNER + COPYWRITER	Contrato + assets + mint page + anúncio	15-25 min

🛠️ Perfil 5 — Desenvolvedor Web3

Necessidade	Agentes	Output	Tempo
Criar dApp completo	DEV + FRONTEND + DESIGNER	Solidity + Next.js + OnchainKit + deploy	20-40 min
Auditoria de segurança de contrato	DEV (v4-security-foundations skill)	Relatório com vulnerabilidades e fixes	5-10 min
Integrar Uniswap swap em app	DEV (swap-integration skill)	Código TypeScript pronto + documentação	5-8 min
Criar hook Uniswap v4	DEV (v4-security-foundations)	Hook testado com Hardhat/Foundry	10-20 min
Deploy multi-chain automatizado	DEV + DEGEN	Script deployment em Base, ETH, Arbitrum	10-15 min

🔮 Possibilidades Futuras — O Que Ainda Não Fazemos (Mas Podemos)

🤖 Agente de Atendimento para Comunidade

Responder dúvidas de membros do Discord/Telegram automaticamente com base em FAQ + contexto de mercado. COPYWRITER + NERD treinados na voz da comunidade.

📱 App Mobile de Controle

Interface React Native com OnchainKit: ver posições, aprovar trades, receber alertas, spawnar agentes — tudo no celular via voz ou texto.

📡 Signal Channel Automatizado

Canal de sinais cripto com análise TRADER + ANALYTICS publicando automaticamente em Telegram/Discord quando detecta setup de alta probabilidade.

🏦 Gestão de Portfolio Multi-Carteira

DEGEN monitora N wallets simultaneamente, consolida P&L total, alerta sobre pools fora de range em qualquer carteira, propõe rebalances cross-wallet.

🎓 Plataforma de Cursos IA-Gerados

NERD pesquisa tema, COPYWRITER estrutura módulos, DESIGNER cria slides, FRONTEND monta plataforma — curso completo em horas, não semanas.

🔔 Monitor de Regulação Global

NERD monitora SEC, CVM, BaFin, MAS automaticamente. Detecta novas regulações e impacto esperado. Alerta Diego 30 min antes de qualquer anúncio crítico.

🗺️ Mapa Completo de Capacidades — O Que ASPIRA Pode Fazer Agora

Domínio	Capacidade	Agente	Automático?
💰 DeFi	Monitor de pools Uniswap v3 on-chain	DEGEN	✅ 2x/dia
	Proposta e execução de rebalance	DEGEN + approval	⚠️ Com approval
	Análise MICAM de posição	TRADER + ANALYTICS	On-demand
	Coleta de fees on-chain	DEGEN	On-demand
📈 Trading	Análise técnica multi-timeframe	TRADER + ANALYTICS	On-demand
	Execução Hyperliquid/Kraken/NADO	DEGEN	⚠️ >$100 approval
	Setups divergence & volume	TRADER	On-demand
	Relatório performance	ANALYTICS	On-demand
🎨 Conteúdo	Posts Instagram/Twitter/YouTube	NERD+DESIGNER+COPYWRITER	On-demand
	Briefing diário	Python + NERD	✅ 06:30 BRT
	Thumbnails e assets visuais	DESIGNER	On-demand
	Scripts e roteiros	COPYWRITER	On-demand
🛠️ Dev	Smart contracts ERC20/NFT	DEV	On-demand
	Deploy em Base/ETH/Arbitrum	DEV + DEGEN	On-demand
	Frontend React/Next.js	FRONTEND	On-demand
	Auditoria de segurança Solidity	DEV	On-demand
🔍 Research	Pesquisa de mercado profunda	NERD + perplexity	On-demand
	Monitor SEC/regulação	NERD (scrapling)	On-demand
	Análise competitiva de projetos	NERD + ANALYTICS	On-demand
	Dados macroeconômicos FRED	NERD	✅ No briefing
🤖 Sistema	Memória automática (extraction-v3)	ASPIRA	✅ On 40k
	Health check infraestrutura	health-check.sh	✅ 30min
	Security audit semanal	security-audit.sh	✅ Seg 07:00

25. Instagram Analytics — Sistema de Métricas

Sistema completo de coleta e visualização de métricas do perfil Instagram de Diego (IntusCripto). Online desde 2026-03-09.

🌐 Acesso & Status

Campo	Valor
URL Pública	instagram-analytics-8fl.pages.dev
Projeto CF Pages	instagram-analytics
CF Account ID	a95eb5c050d25d79f60c43f303ba1dd5
Cron Diário	09:00 BRT (job 311f6904-7702-4e1c-92c9-f7f5c87162c5)
Status	✅ ONLINE
Posts históricos	1.152 posts coletados
Collector Versão	v3 (reescrito 2026-03-09)

📁 Estrutura de Arquivos

Arquivo	Função
skills/instagram-analytics/scripts/collector.js	Coleta 90 posts + insights (v3)
skills/instagram-analytics/scripts/generate-dashboard.js	Gera HTML do dashboard
skills/instagram-analytics/scripts/deploy.sh	Lê CF token do 1Password → deploy
skills/instagram-analytics/scripts/backfill-history.js	Backfill histórico completo
skills/instagram-analytics/data/analytics.db	SQLite DB (posts + snapshots)

🔑 Credenciais (1Password)

Serviço	1Password Path
Cloudflare API Token	op://Aspira/Cloudflare API Token/api_token
Instagram Access Token	op://Aspira/Instagram Graph API/access_token

📊 Métricas Coletadas (API v22+)

Métrica	Nível	Status
views	Post + User	✅ (metric_type=total_value obrigatório para user-level)
reach	Post + User	✅
likes, comments, saved, shares	Post	✅
total_interactions	Post + User	✅
ig_reels_avg_watch_time	Post (Reels)	✅
profile_links_taps	User	✅ (substituiu profile_views)
follower_demographics	User	✅ (funciona para Creator)
follows_and_unfollows	User	⚠️ Formato inconsistente na API
engaged_audience_demographics	User	⚠️ Volume insuficiente (~50K+)

⚠️ Regras Críticas — Instagram Graph API v22+

metric_type=total_value OBRIGATÓRIO para ALL user-level metrics (sem isso retorna data:[])
impressions DEPRECADA → usar views
profile_views/website_clicks DEPRECADAS → usar profile_links_taps
follows NÃO funciona para Reels — erro silencioso que zera toda a resposta
follower_demographics funciona para Creator (não precisa de Business)

📊 DB Schema (post_snapshots)

Campo	Tipo	Obs
views	INTEGER	Adicionado 2026-03-09
total_interactions	INTEGER	Adicionado 2026-03-09
profile_visits_from_post	INTEGER	Adicionado 2026-03-09
reach	INTEGER	Fix 2026-03-09 (era 0 para Reels)

26. Intus-Personas — Bot WhatsApp IntusCripto

Projeto de bot inteligente para os grupos WhatsApp do IntusCripto Club. Status atual: Fase A (silenciosa) — mapeamento completo, aguardando ativação.

📊 Grupos Mapeados (2026-03-10)

Grupo	JID	Função
Avisos	120363136035311553@g.us	📢 Broadcast da comunidade
Novos Membros Club	120363048351878310@g.us	👋 Onboarding
IntusCripto Club #1	120363363148603683@g.us	💬 Chat principal
Testes (antigo)	120363421571898067@g.us	🧪 Testes fev/26

⚙️ Config Atual

Parâmetro	Valor
groupPolicy	allowlist
groups	{} (silencioso total)
Bot número	+5511936208775 (Aspira)
Fase atual	A — silenciosa (só ouvindo)
Persona arquivo	projects/intus-personas/whatsapp/PERSONA-WHATSAPP.md

🗺️ Roadmap de Ativação

Fase	O que	Status
A — Silenciosa	Bot nos grupos, JIDs mapeados, zero interação	✅ CONCLUÍDA
B — Knowledge Base	FAQ seed, Notion workspace, produtos/preços	⏳ PENDENTE
C — Segurança	Prompt injection protection, rate limiting	⏳ PENDENTE
D — Ativação por Grupo	Avisos=leitura, Novos Membros=onboarding, Club=suporte	⏳ PENDENTE

🔒 Decisão de Como Descobrimos os JIDs

Adicionamos grupos com requireMention: true temporariamente
Diego mandou 👀 nos 3 grupos
Capturamos JIDs nos logs do gateway
Cruzamos com screenshot da ordem de envio
Revertemos para groups: {} imediatamente