Pular para o conteúdo principal

Início rápido

Sua primeira chamada à API da Cognivo​

A Cognivo Developer API permite que o seu próprio código faça as mesmas perguntas on-chain que você faz no dApp e no Cognivo Chat. Esta página percorre o caminho mais curto: criar um projeto, criar uma chave, executar uma chamada real e ler a resposta.

Quando usar​

Use a API quando quiser verificações de tokens, carteiras ou liquidez dentro de algo que você está construindo, como um bot de trading, um painel interno, uma rotina de alertas ou um serviço de backend, em vez de clicar pelo dApp a cada vez. Se você só quer executar verificações manualmente, o dApp e o Chat já fazem isso e você não precisa de uma chave.

Onde encontrar​

Entre no dApp, abra Conta na barra lateral e selecione Developers. Visitantes deslogados veem apenas uma tela de apresentação, então faça login primeiro. Tudo o que esta página descreve acontece nessa única tela.

Crie um projeto e depois uma chave​

Um projeto agrupa as suas chaves de API e o uso delas, então comece por aí.

  1. Selecione Novo projeto para abrir o formulário curto abaixo do seletor de projeto.
  2. Digite um nome em Nome do projeto para conseguir diferenciar seus projetos depois.
  3. Selecione Criar para adicionar o projeto, ou Cancelar para fechar o formulário sem salvar.
  4. Selecione Criar chave ao vivo para gerar uma chave do projeto e depois envie-a com suas requisições a partir do seu próprio código.
Os controles de projeto na página Desenvolvedores, onde você cria um projeto antes de gerar uma chave.Ampliar imagem

O nome do projeto é apenas um rótulo para você. Ele não aparece nas suas requisições e você pode criar mais de um projeto, até o limite exibido na página.

Quando você seleciona Criar chave live, a Cognivo mostra a chave completa exatamente uma vez, em uma caixa de diálogo com um botão de copiar. Copie nesse momento e guarde em um lugar seguro. Depois disso, a página mostra apenas uma versão mascarada, o prefixo e os quatro últimos caracteres, porque a Cognivo armazena a chave em um formato que ela não consegue ler de volta. Se você perder uma chave, ou achar que ela vazou, use Rotacionar ou Revogar na linha da chave. A chave antiga para de funcionar na hora.

Cada chave também carrega Permissões, que controlam o que ela pode chamar: Intelligence, Security e Liquidity. Dê a uma chave apenas as permissões de que ela precisa. O exemplo abaixo precisa de Liquidity.

Mais dois botões ficam no mesmo card. Adicionar créditos leva você à sua página de Billing. Acesso enterprise abre o fluxo de suporte, e é o único caminho que envolve uma solicitação, para preços sob medida ou limites maiores. Uma chave live normal não precisa de aprovação e funciona no momento em que você a cria.

Execute a chamada de exemplo​

Abra a aba Início rápido. Ela traz um exemplo funcional que você pode copiar e executar sem escrever nada por conta própria.

A aba Início rápido na página Developers, onde você copia um exemplo de chamada que já funciona.Ampliar imagem

O card Chaves de teste x chaves live explica a diferença. Uma chave de teste faz chamadas seguras com limites apertados, o que é bom para montar a integração. Uma chave live faz chamadas reais, cobradas do seu saldo de créditos Cognivo. O card Testar um endpoint live traz então cinco passos numerados e o próprio comando, com um ícone de copiar.

O comando é uma verificação de liquidez real em um contrato real na Base:

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":"0xe2b1dc2d4a3b4e59fdf0c47b71a7a86391a8b35a"}'

A mesma chamada em JavaScript ou TypeScript:

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);
  console.log(json.meta.request_id);
} else {
  console.error(json.error);
}

O que volta​

Todos os endpoints respondem com o mesmo envelope, que o bloco Resposta esperada da aba Início rápido mostra:

{
  "ok": true,
  "data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 0,
    "generated_at": "..."
  }
}

data guarda o resultado. Vale registrar meta.request_id nos seus logs, porque o suporte consegue localizar uma chamada específica por ele. meta.credits_charged informa exatamente quanto aquela chamada custou.

Um campo pode voltar vazio, desconhecido ou indisponível. Isso significa que a Cognivo não conseguiu verificá-lo com os dados aos quais tem acesso, não que não haja nada ali. Leia como "não confirmado" e não trate um resultado silencioso como sinal verde. A Cognivo informa o que verificou e o que encontrou, e nada em uma resposta prova que um token é golpe nem prova que ele é seguro.

Uma chamada que falha responde com ok igual a false, um código de error e um request_id. Chamadas com falha não são cobradas.

Custo, chains e limites​

  • Alguns endpoints são gratuitos com qualquer chave ativa. Outros são cobrados por chamada bem-sucedida do seu saldo de créditos Cognivo. A aba Endpoints lista cada endpoint com o seu preço em créditos Cognivo, ou Grátis quando for gratuito, então confira lá antes de construir em cima de um endpoint.
  • Você é cobrado apenas por uma chamada bem-sucedida, e meta.credits_charged confirma o valor. Erros, timeouts e chamadas bloqueadas não custam nada.
  • Toda conta recebe 5 créditos grátis por dia. Eles são renovados à meia-noite UTC e são usados antes de quaisquer créditos pagos.
  • Hoje a API cobre Ethereum, Base e BNB Chain. Alguns endpoints suportam menos chains do que outros.
  • Chaves de teste têm limites bem apertados e não são um plano de produção gratuito. Cada linha de chave na aba Chaves mostra os limites que a Cognivo está aplicando àquela chave neste momento, que podem ser menores que o padrão do nível.
  • Uma chave suspensa, ou uma chave em um projeto suspenso, não consegue executar nada, e o portal mostra o motivo.

Mantenha sua chave segura​

Chame a API a partir de um servidor, nunca de código de navegador ou de aplicativo móvel. Guarde a chave em uma variável de ambiente ou em um gerenciador de segredos, nunca em um repositório público, em uma mensagem de chat ou em uma captura de tela. Se uma chave puder ter vazado, rotacione ou revogue ela na aba Chaves.

Próximos passos​

Leia Autenticação e chaves para ver permissões e o manuseio de chaves por completo, Endpoints para saber o que cada chamada retorna e quanto custa, e Limites de taxa e erros para retentativas e códigos de erro. Para o seu saldo de créditos e recargas, veja Billing e créditos.