xtokenhub

# XTokenHub XTokenHub é um gateway de agregação auto-hospedado para APIs de provedores de LLM. Ele reúne as chaves de API que você já possui em diferentes provedores em um único painel baseado em canais, expõe endpoints de protocolo padronizados para seus clientes e relata em tempo real o uso de tokens e a taxa de acerto de cache. O princípio de design declarado é encaminhar o tráfego usando o protocolo nativo do provedor sempre que possível, tratando a conversão como recurso de fallback. ## Core capabilities - **Gerenciamento de chaves baseado em canal** — uma entrada por endpoint de provedor, com sondagem de disponibilidade, alternância habilitar/desabilitar e consultas de saldo onde o provedor as expõe. - **Agrupamento e roteamento de modelos** — cada canal possui sua própria lista de modelos (obtida do upstream sob demanda), e todos os upstreams são mesclados em um único endpoint de listagem de modelos. O roteamento usa prioridade mais seleção aleatória ponderada, com failover automático entre canais que servem o mesmo modelo. - **Visão de uso** — um painel relata contagem de requisições, uso de tokens, taxa de acerto de cache e latência média, agregados por modelo, canal ou chave do chamador, com um heatmap de atividade ao estilo GitHub e gráficos de tendência diária enviados via WebSocket. - **Conversão de protocolo** — o gateway expõe simultaneamente endpoints de chat e respostas no estilo OpenAI e um endpoint de mensagens no estilo Anthropic. As requisições são convertidas apenas quando os protocolos de entrada e upstream diferem; protocolos correspondentes são encaminhados sem reescrita, o que o projeto afirma preservar chamadas de ferramentas e cargas multimodais. - **Chaves de gateway e estatísticas por chamador** — chaves voltadas ao cliente são emitidas para diferentes chamadores, e os totais de requisições/tokens são agregados por chave. - **Auto-hospedagem em binário único** — o frontend está embutido no binário Go, de modo que a compilação produz um único artefato estático (sem CGO) que pode ser copiado para uma máquina Linux ou macOS. ## How routing and metering work O README descreve um fluxo de quatro etapas: 1. Crie um canal com a URL base do provedor, chave de API e lista de modelos. O estilo de API (Bearer para compatibilidade OpenAI, x-api-key para compatibilidade Anthropic) é detectado automaticamente a partir da URL base e pode ser sobrescrito. Várias formas de montagem de URL base são suportadas, incluindo domínios simples, sufixos /v1, montagens de subcaminho como /anthropic e montagens versionadas. 2. Uma sondagem de protocolo nativo envia uma requisição mínima a cada endpoint de protocolo; uma resposta 2xx marca esse protocolo como nativo ao canal, podendo também ser corrigido manualmente. 3. As requisições recebidas são filtradas para canais habilitados que servem o modelo, canais nativos são preferidos, e canais convertidos são usados apenas como fallback. A seleção é ascendente por prioridade com aleatoriedade ponderada, e falhas como erros de rede, 401/403/408/429 ou 5xx acionam failover. 4. O uso é extraído da resposta do upstream quando reportado (com opções de uso em streaming adicionadas automaticamente); quando o upstream não informa nada, uma estimativa heurística local é usada. A taxa de acerto de cache vem dos campos cached-token do provedor, e cada requisição é gravada em uma tabela de log e enviada à UI. ## Dashboard and API surface A API de administração cobre canais, chaves de gateway, logs de requisições com limpeza de retenção, e um conjunto de endpoints de estatísticas (resumo, tendência diária, por modelo, por canal, por chave, totais de vida útil e tendência por modelo), além de um endpoint de saúde e um endpoint WebSocket para eventos ao vivo. Os endpoints do gateway incluem uma lista de modelos mesclada e as rotas de chat, respostas e mensagens. A autenticação do chamador aceita tanto um token Bearer quanto um cabeçalho x-api-key e pode ser desativada por configuração. ## Configuration and operations A precedência de configuração é variáveis de ambiente, depois um arquivo YAML, e por fim os padrões incorporados. Os dados são armazenados em SQLite no modo WAL com uma única conexão de escrita. Os logs de requisições crescem indefinidamente por padrão, portanto um job de retenção exclui linhas mais antigas que um número configurável de dias, com configurações para intervalo de ciclo, tamanho de lote e um VACUUM opcional. O projeto observa que o arquivo SQLite não encolhe automaticamente após a exclusão. ## Testing Os testes unitários estão em um layout de pacote de teste externo espelhado e cobrem carregamento de configuração, repositórios SQLite em memória, o barramento de eventos, comportamento do WebSocket, sondagem de provedores e conversão via upstreams falsos, seleção do gateway e persistência de estatísticas, e caminhos de handler/router de ponta a ponta. O README relata uma execução completa de testes com detecção de race e cobertura de 87,6% de declarações, além de testes de frontend para reconexão de WebSocket e transformações de dados. ## Known limitations stated by the project - O caminho de conversão lida apenas com chat de texto; chamadas de ferramentas, payloads multimodais e de controle de cache precisam de canais de passagem nativa. - As consultas de saldo atualmente cobrem apenas o DeepSeek, pois as APIs de saldo de outros provedores não são documentadas, exigem autenticação por cookie expirável ou não são públicas. - A estimativa local de tokens é heurística e usada apenas como fallback. - A API de administração não possui autenticação de login e destina‑se ao uso intranet auto‑hospedado com isolamento de rede externa; as chaves são armazenadas em texto plano. - A taxa de acerto de cache e a agregação por chave dependem de snapshots dos logs de requisição, de modo que o uso histórico de uma chave excluída permanece sob seu nome. ## Companion app and license Um aplicativo separado em SwiftUI para a barra de menus consome a mesma API de administração e WebSocket sem exigir alterações no backend. XTokenHub é distribuído sob a Licença MIT.