Referência de endpoints

Todos os endpoints vivem sob https://api.cognivolabs.io/v1/api. Os endpoints de inteligência são POST com um corpo JSON (isso impede que pré-visualizações de links, crawlers e prefetchers disparem uma execução). GET existe apenas para health, me e discover.

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

O envelope de resposta

Todos os endpoints respondem com o mesmo envelope. Sucesso:

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 0,
    "generated_at": "2026-07-09T00:00:00.000Z"
  }
}

data - o resultado de inteligência em si; o formato varia por endpoint
meta.request_id - id único desta chamada; guarde-o, o suporte pode rastrear uma chamada a partir dele
meta.credits_charged - os créditos que esta chamada custou: 0 para endpoints gratuitos, cotas de demo sandbox ou de trial, e qualquer resultado com falha ou vazio; o preço em créditos do endpoint no uso pago
meta.generated_at - quando o resultado foi produzido
meta.chain aparece em chamadas específicas de chain, e meta.sources (um array de rótulos de fontes) 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 legível por máquina (veja Limites de taxa e erros); message é uma dica opcional para humanos.

Campos comuns do corpo

chain - um de eth, base, bsc (sem diferenciar maiúsculas)
address / wallet / token - um endereço EVM 0x… (40 caracteres hexadecimais)

Todos os exemplos abaixo usam o placeholder YOUR_API_KEY; em código real, carregue a chave de uma variável de ambiente ou de um gerenciador de segredos, nunca a codifique diretamente.

Acesso e custos em créditos

Os endpoints de inteligência executáveis exigem acesso trial, partner, pago ou enterprise. Sem acesso eles não executam de graça: você recebe um erro 403 claro como access_required (veja Limites de taxa e erros). O uso pago é cobrado em créditos Cognivo por chamada bem-sucedida; chamadas com falha não são cobradas. Custos por endpoint (aplicam-se ao uso pago; exibidos por transparência):

Endpoint	Créditos por chamada bem-sucedida
`POST intel/liquidity`	2
`POST intel/risk`	2
`POST wallet/approvals`	2
`POST intel/why-down`	3
`POST intel/team-wallets`	5
`POST wallet/exact-movements`	5
`POST wallet/pnl`	10
`GET health`, `GET me`	gratuito
`GET discover`	gratuito, com um teto de taxa rígido

Serviço

GET /v1/api/health

Sonda de disponibilidade (liveness). Não requer 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 (não é o envelope padrão, de propósito):

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

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

GET /v1/api/me

Faz a introspecção da chave que está chamando. Escopo: qualquer chave válida. Gratuito. Para chaves live de autoatendimento, também mostra o credits_balance da conta proprietária (null se temporariamente indisponível) e a orientação 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();

Resposta:

{
  "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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitações: mostra apenas a chave mascarada, nunca o material completo da chave. credits_balance é o saldo de créditos Cognivo da conta proprietária e pode ser null se estiver temporariamente indisponível.

Inteligência de tokens

POST /v1/api/intel/why-down - escopo `intel:read`

Por que este token está caindo: uma leitura verificada da atividade on-chain recente em busca do fator dominante (vendas, retiradas de LP, movimentos do dono).

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 3 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição:

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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 contém a análise da queda (fator dominante, observações on-chain de apoio) com meta.chain preenchido.

Limitações: precisa de atividade recente para dizer algo útil; para um token com muito pouco histórico de trading, a leitura pode ser rasa. Sinais, não aconselhamento financeiro.

POST /v1/api/intel/team-wallets - escopo `intel:read`

Varredura das carteiras do time e de controle de um token: carteiras do deployer, do dono e dos controladores, além do comportamento recente delas.

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 5 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição:

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/team-wallets", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

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

Limitações: identifica carteiras a partir de relações on-chain (deploy, propriedade, controle); não consegue ver a estrutura do time fora da chain.

POST /v1/api/intel/liquidity - escopo `liquidity:read`

Status de pool/LP de um token: contexto do pool, custódia do LP e contexto de lock/queima.

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 2 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição (os booleanos opcionais metadata, locks e full adicionam metadados verificados do pool, prova de lock temporizado e a leitura mais completa disponível):

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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}'

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

Resposta: o envelope padrão; data contém a identidade do token, um snapshot de mercado e a custódia do LP mais o contexto de lock/queima.

Limitações: a proveniência histórica profunda das queimas não é exposta na v1; o contexto de locks cobre padrões de lockers reconhecidos, e um locker customizado não reconhecido pode aparecer como custódia sem lock.

POST /v1/api/intel/risk - escopo `intel:read`

Sinais de risco da Cognivo cientes da chain para um token (leitura de red flags como fallback).

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 2 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição:

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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"}'

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

Resposta: o envelope padrão; data contém os sinais de risco e as flags encontradas para o token.

Limitações: um resultado limpo nunca significa "seguro"; significa que nenhuma red flag conhecida foi encontrada no momento da leitura.

Inteligência de carteiras

POST /v1/api/wallet/pnl - escopo `intel:read`

PnL realizado de uma carteira em um token, a partir de atividade de carteira verificada. Tanto wallet quanto token são obrigatórios.

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 10 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/pnl", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET", token: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

Resposta: o envelope padrão; data contém o cálculo do PnL realizado para aquele par carteira/token.

Limitações: retorna 422 (por exemplo insufficient_data) quando a carteira não tem trades precificados naquele token, de modo que um número justo não pode ser calculado. A Cognivo nunca inventa um número, e um 422 nunca é cobrado. Apenas PnL realizado; posições não realizadas (ainda em carteira) não são avaliadas aqui.

POST /v1/api/wallet/approvals - escopo `security:read`

Aprovações de tokens vigentes contra uma carteira, sinalizando allowances ilimitadas. Somente leitura: a Cognivo nunca move fundos e não pode revogar por você.

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 2 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição (limit e offset opcionalmente paginam conjuntos grandes de aprovações):

{ "chain": "eth", "address": "0xWALLET" }

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"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/approvals", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xWALLET" }),
});
const json = await res.json();

Resposta: o envelope padrão; data contém a lista de aprovações com contexto de spender, token e allowance.

Limitações: um resultado vazio (nenhuma aprovação encontrada) é uma resposta válida e bem-sucedida e não é cobrado.

POST /v1/api/wallet/exact-movements - escopo `intel:read`

Movimentos recentes exatos de uma carteira (leitura no estilo dono/deployer). token é opcional e restringe a leitura a um único token.

Acesso e custo: exige acesso ao vivo (trial, partner, pago ou enterprise); 5 créditos por chamada bem-sucedida no uso pago.

Corpo da requisição:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/exact-movements", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET" }),
});
const json = await res.json();

Resposta: o envelope padrão; data contém a lista de movimentos com contagens.

Limitações: 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 Discover: cards de inteligência pública recentes e de alta qualidade (identidade do token, gancho, tópicos). Escopo: qualquer chave válida. Gratuito, com um teto de taxa rígido.

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

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

Resposta:

{
  "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-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 uma cobertura completa.

Planejado (ainda não disponível)

Estes itens estão documentados por transparência do roadmap e hoje não retornam nada:

Rastreamento profundo de carteira via API (wallet/trace) - o fluxo de jobs assíncronos é, por enquanto, exclusivo do chat/dApp
Busca de relatórios por id (reports/:id)
Webhooks
Endpoints de Solana

O envelope de resposta​

Campos comuns do corpo​

Acesso e custos em créditos​

Serviço​

GET /v1/api/health​

GET /v1/api/me​

Inteligência de tokens​

POST /v1/api/intel/why-down - escopo intel:read​

POST /v1/api/intel/team-wallets - escopo intel:read​

POST /v1/api/intel/liquidity - escopo liquidity:read​

POST /v1/api/intel/risk - escopo intel:read​

Inteligência de carteiras​

POST /v1/api/wallet/pnl - escopo intel:read​

POST /v1/api/wallet/approvals - escopo security:read​

POST /v1/api/wallet/exact-movements - escopo intel:read​

Discover​

GET /v1/api/discover​

Planejado (ainda não disponível)​

O envelope de resposta

Campos comuns do corpo

Acesso e custos em créditos

Serviço

GET /v1/api/health

GET /v1/api/me

Inteligência de tokens

POST /v1/api/intel/why-down - escopo `intel:read`

POST /v1/api/intel/team-wallets - escopo `intel:read`

POST /v1/api/intel/liquidity - escopo `liquidity:read`

POST /v1/api/intel/risk - escopo `intel:read`

Inteligência de carteiras

POST /v1/api/wallet/pnl - escopo `intel:read`

POST /v1/api/wallet/approvals - escopo `security:read`

POST /v1/api/wallet/exact-movements - escopo `intel:read`

Discover

GET /v1/api/discover

Planejado (ainda não disponível)