Pular para o conteúdo principal

Referência de endpoints

O que é esta página​

A Cognivo Developer API permite que o seu próprio código faça à Cognivo as mesmas perguntas que o app responde. Todos os endpoints ficam sob https://api.cognivolabs.io/v1/api.

Use quando quiser que uma verificação da Cognivo rode em outro lugar que não o app: dentro do seu próprio bot, de um painel, de uma rotina em planilha ou de um script noturno que observa uma lista de tokens.

Os endpoints de inteligência são POST com corpo JSON. Isso é proposital: uma prévia de link, um crawler ou um prefetch do navegador nunca conseguem disparar uma execução ao carregar uma URL. GET existe apenas para health, me e discover.

Onde encontrar isso no app​

Entre no app da Cognivo, abra Developers na barra lateral esquerda, em Conta, e selecione a aba Endpoints.

A aba Endpoints na página Developers, onde cada endpoint da Cognivo é listado com a permissão que ele exige e quanto custa.Ampliar imagem

A aba é uma referência, não um executor. Ela lista todos os endpoints live com um exemplo copiável, a permissão que a chave precisa e o preço em créditos. O card Permissões explicadas agrupa essas permissões em três: Intelligence (por que está caindo, carteiras do time, risco, PnL de carteira, movimentos exatos), Security (aprovações de tokens) e Liquidity (liquidez, locks e queimas). Dê a cada chave apenas as permissões de que ela precisa.

Prefere uma versão legível por máquina? A especificação OpenAPI completa cobre tudo o que está nesta página.

O envelope de resposta​

Todos os endpoints respondem com o mesmo envelope. Os ids e horários dos exemplos abaixo são valores de exemplo. Sucesso:

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 2,
    "generated_at": "2026-07-09T00:00:00.000Z"
  }
}
  • data é o resultado em si. O formato varia por endpoint.
  • meta.request_id é um id único desta chamada. Guarde, o suporte consegue rastrear uma chamada a partir dele.
  • meta.credits_charged é o que a chamada custou: o preço do endpoint em uma chamada paga bem-sucedida, e 0 para endpoints gratuitos e para qualquer resultado com falha ou honestamente vazio.
  • meta.generated_at é quando o resultado foi produzido.
  • meta.chain aparece em chamadas específicas de uma chain, e meta.sources aparece quando o resultado cita fontes.

Falha:

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error é um código estável e legível por máquina. message é uma dica opcional para humanos. A lista completa está em Limites de taxa e erros.

Campos comuns do corpo​

  • chain é um entre eth (Ethereum), base (Base) ou bsc (BNB Chain), e não diferencia maiúsculas de minúsculas.
  • address, wallet e token são endereços EVM 0x de 40 caracteres hexadecimais.

Todo exemplo usa o marcador YOUR_API_KEY. Em código real, carregue a chave de uma variável de ambiente ou de um gerenciador de segredos. Nunca a deixe fixa no código.

Quanto custa cada endpoint​

Chaves live são autoatendimento e pré-pagas. Uma nova chave live executa estes endpoints imediatamente, e cada chamada bem-sucedida é cobrada em créditos Cognivo do saldo da sua conta. Chamadas com falha nunca são cobradas, e uma chamada bem-sucedida é cobrada exatamente uma vez, então reenviar a mesma operação não gera cobrança em dobro.

Toda conta recebe 5 créditos grátis por dia, renovados à meia-noite UTC. Se o seu saldo não cobrir uma chamada, você recebe 402 payment_required e nada é cobrado. Faça uma recarga na página de Billing da sua conta e tente de novo. Chaves de sandbox (cogv_test_) não conseguem executar inteligência live. Veja Cobrança e Pacotes de Créditos.

EndpointCréditos por chamada bem-sucedida
POST intel/liquidity2
POST intel/risk2
POST wallet/approvals2
POST intel/why-down3
POST intel/team-wallets5
POST wallet/exact-movements5
POST wallet/pnl10
POST contract/analysisgrátis
GET health, GET megrátis
GET discovergrátis, com um limite de taxa apertado

Serviço​

GET /v1/api/health​

Verifica se a API da Cognivo está no ar. Não precisa de chave de API.

curl 'https://api.cognivolabs.io/v1/api/health'
const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

Resposta, que não segue o envelope padrão, por decisão de projeto:

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

Se a API pública estiver desligada, você também recebe 404 public_api_disabled aqui, então este endpoint serve igualmente como verificação de disponibilidade.

GET /v1/api/me​

Mostra detalhes sobre a chave que está chamando: nível, permissões e limite de taxa. Funciona com qualquer chave ativa e é gratuito. Para chaves live de autoatendimento, também mostra o credits_balance da conta dona e orientações de top_up, além do access_mode da chave.

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'
const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();
{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitações: ele mostra apenas a chave mascarada, nunca o material completo da chave. credits_balance pode voltar como null, o que significa que a Cognivo não conseguiu ler o saldo naquele momento, não que o saldo seja zero.

Todos os demais endpoints seguem o mesmo formato de chamada dos exemplos abaixo. Troque o caminho e os campos do corpo.

Inteligência de tokens​

POST /v1/api/intel/why-down, permissão Intelligence (intel:read)​

Uma leitura em linguagem simples sobre por que o preço de um token está caindo, construída a partir da atividade on-chain recente: venda pesada, liquidez sendo retirada, carteiras do dono ou do time se movimentando.

Preço de tabela: 3 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/why-down' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT"}'
const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

Resposta: o envelope padrão. data traz o fator dominante e as observações on-chain por trás dele, com meta.chain preenchido.

Limitações: a leitura precisa de atividade recente para dizer algo útil, então um token com pouquíssimo histórico de negociação gera uma resposta rasa. Estes são sinais, não aconselhamento financeiro.

POST /v1/api/intel/team-wallets, permissão Intelligence (intel:read)​

Revela carteiras ligadas ao time ou à tesouraria de um token: carteiras de deployer, dono e controlador, além do que elas vêm fazendo recentemente.

Preço de tabela: 5 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/team-wallets' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

Resposta: o envelope padrão. data lista as carteiras identificadas e o comportamento recente delas, muitas vezes com meta.sources.

Limitações: as carteiras são identificadas a partir de relações on-chain como implantação, propriedade e controle. A Cognivo não enxerga a estrutura do time fora da chain, então uma lista vazia significa que nada pôde ser vinculado on-chain, não que o token não tem time.

POST /v1/api/intel/liquidity, permissão Liquidity (liquidity:read)​

Verifica a liquidez, os locks e as queimas de um token com evidências on-chain: contexto da pool, quem detém os tokens de LP e o contexto de lock ou queima.

Preço de tabela: 2 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

Os booleanos opcionais metadata, locks e full adicionam metadados da pool, prova de lock com prazo e a leitura mais completa disponível.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/liquidity' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT","locks":true}'

Resposta: o envelope padrão. data traz a identidade do token, um retrato de mercado e a custódia de LP com contexto de lock ou queima.

Limitações: a proveniência histórica profunda de queimas não é exposta na v1. O contexto de lock cobre padrões de locker reconhecidos, então um locker customizado incomum pode ser lido como custódia simples em vez de lock. Leia isso como "não verificado", e não como "sem lock".

POST /v1/api/intel/risk, permissão Intelligence (intel:read)​

Sinais de Risco da Cognivo para um contrato de token, com consciência de chain, e uma leitura de red flags como alternativa.

Preço de tabela: 2 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"bsc","address":"0xTOKEN_CONTRACT"}'

Resposta: o envelope padrão. data traz os sinais e alertas encontrados para o token.

Limitações: um resultado limpo não significa que o token é seguro. Significa que nenhum red flag conhecido foi encontrado no momento da leitura.

POST /v1/api/contract/analysis, permissão Contract (contract:read)​

Evidências de contrato e de controle para um endereço de contrato: ele existe, quem é o dono, a propriedade foi renunciada, é um proxy e quem o administra, quem fez a implantação, quais carteiras podem ser atribuídas como controladoras ou do time, e o código-fonte está verificado.

Custo: 0 créditos. Este endpoint é gratuito por decisão, em todos os planos. Nada é descontado.

curl -X POST 'https://api.cognivolabs.io/v1/api/contract/analysis' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xTOKEN_CONTRACT"}'

Resposta: o envelope padrão. data traz contract, ownership, proxy, deployer, controllers, source_verification, limitations e unavailable.

Cada campo informa de onde veio. meta.provenance mapeia cada campo para exatamente um destes:

RótuloO que significa
verified_onchainLido de um nó daquela rede no momento da sua requisição. Um fato.
augmentedCognivo Augmented Intelligence: fornecido por uma fonte externa, checado de forma cruzada mas não comprovado pela Cognivo.
interpretationA leitura que a Cognivo faz dos fatos. Um julgamento, não um fato.
unavailableA Cognivo não conseguiu obter isso. O motivo está em data.unavailable.

Nada é chutado, preenchido com padrão ou retornado como zero para tapar uma lacuna.

meta.chain_data_source.cognivo_grounded diz se a Cognivo opera a infraestrutura de onde veio a leitura. A Cognivo roda o próprio nó Ethereum, então leituras da Ethereum são true. Leituras de Base e BNB Chain vêm de infraestrutura de RPC externa, então são false. Essas leituras são precisas, mas não são servidas por hardware que a Cognivo controla, e a Cognivo diz isso em vez de deixar você supor o contrário.

Limitações na Base, também retornadas em data.limitations:

  • O grafo profundo de controladores é exclusivo da Ethereum. Na Base, a atribuição de controlador e de time vem de uma leitura mais estreita de papéis de carteira.
  • A evidência de deployer na Base vem de uma fonte externa, não de uma leitura de arquivo da Cognivo. Trate como uma pista forte, não como um fato comprovado.
  • Cronogramas de lock de liquidez não são decodificados na Base. Use POST /v1/api/intel/liquidity para custódia de LP e evidência de queima, e não leia um lock ausente como ausência de lock.

Este endpoint informa apenas evidências de controle do contrato. Ele não diz nada sobre liquidez, e um resultado limpo nunca significa que o contrato é seguro.

Somente leitura: nada é assinado, nenhuma transação é montada, nada é transmitido e nenhuma carteira é delegada.

Inteligência de carteiras​

POST /v1/api/wallet/pnl, permissão Intelligence (intel:read)​

Lucro e prejuízo de uma carteira em um token, calculado a partir de swaps on-chain fundamentados. Tanto wallet quanto token são obrigatórios.

Preço de tabela: 10 créditos por chamada bem-sucedida. Chamadas com falha, e resultados 422 sem dados, nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

Resposta: o envelope padrão. data traz o valor realizado e um valor não realizado para a posição ainda mantida, quando existe uma base de custo defensável.

Limitações: quando nenhuma base de custo defensável pode ser estabelecida, o valor não realizado volta como null em vez de um número inventado. Quando a carteira não tem nenhuma negociação precificada naquele token, a chamada retorna 422 (por exemplo insufficient_data), o que significa que a Cognivo não conseguiu calcular um número justo, não que o lucro foi zero. Um 422 nunca é cobrado. Swaps que a Cognivo não conseguiu precificar são exibidos como não precificados em vez de descartados.

POST /v1/api/wallet/approvals, permissão Security (security:read)​

Lista as aprovações de gasto de tokens que uma carteira concedeu, e sinaliza permissões ilimitadas.

Preço de tabela: 2 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

Os opcionais limit e offset paginam conjuntos grandes de aprovações.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/approvals' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xWALLET"}'

Resposta: o envelope padrão. data traz a lista de aprovações com o gastador, o token e o contexto de permissão.

Limitações: isto é somente leitura. A Cognivo nunca move fundos e não pode revogar uma aprovação por você. A revogação é sempre feita a partir da sua própria carteira. Uma lista vazia é uma resposta válida e bem-sucedida, e não é cobrada.

POST /v1/api/wallet/exact-movements, permissão Intelligence (intel:read)​

Lista os movimentos exatos de tokens de uma carteira: compras, vendas e transferências. token é opcional e restringe a leitura a um único token.

Preço de tabela: 5 créditos por chamada bem-sucedida. Chamadas com falha nunca são cobradas. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

Resposta: o envelope padrão. data traz a lista de movimentos com as contagens.

Limitações: a chamada retorna os movimentos mais recentes, até 25 por chamada. Uma carteira sem movimentos correspondentes retorna 422 em vez de um histórico inventado.

Discover​

GET /v1/api/discover​

O feed público do Discover: cards recentes e anonimizados de inteligência on-chain, cada um com a identidade do token, um gancho e tópicos. Funciona com qualquer chave ativa. Gratuito, sob um limite diário apertado.

Parâmetros de consulta: limit (1 a 50, padrão 20) e o opcional chain (eth, base, bsc).

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'
{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitações: valores de limit fora de 1 a 50 são ajustados para dentro do intervalo. O feed contém apenas a inteligência que os usuários escolheram publicar, então é uma amostra, não cobertura total.

Ainda não disponível​

Estes estão listados por transparência e hoje não retornam nada:

  • Rastreamento profundo de carteira pela API (wallet/trace). O fluxo de job assíncrono é, por ora, exclusivo do chat e do app.
  • Busca de relatório por id (reports/:id).
  • Webhooks.
  • Endpoints de Solana.

Próximos passos​

Faça a sua primeira chamada com o Início rápido, crie e defina o escopo de uma chave em Autenticação e chaves, e leia Limites de taxa e erros antes de colocar qualquer coisa em uma rotina agendada.