Saltar para o conteúdo principal

​
Chaves de API

Cada requisição a um endpoint /api/v1/public/ se autentica com uma chave no cabeçalho X-API-Key, exceto as requisições a /api/v1/public/status, que não precisa de chave. A rota paga por chamada em /api/v1/x402/ não usa chave (veja Pague por chamada com x402):
As chaves são strings no formato cck_ seguido de 56 caracteres hexadecimais. Não há suporte a Authorization: Bearer. Em um navegador, um token Bearer devolve 401. Em um cliente de linha de comando como curl ou python-requests, ele é recusado uma camada antes, como 403 {"error":"Forbidden"} sem o campo code, porque uma requisição sem X-API-Key não é reconhecida como cliente de API. Sempre envie X-API-Key. Crie, liste e revogue chaves em cctools.network/profile/api. O texto em claro é exibido exatamente uma vez, na criação; depois disso apenas o prefixo fica visível. Com uma chave em mãos, cctools.network/api-docs roda qualquer endpoint com ela direto no navegador. Quantas chaves ativas você pode manter depende do seu plano; o número de cada um está em Planos e limites. O limite por minuto é contado por chave e endpoint, então cada chave extra soma vazão, enquanto o limite diário é contado para a conta inteira e não cresce com o número de chaves.

​
Planos

Sua chave tem o plano da sua conta, e o plano define os seus limites de requisições. Ele é devolvido em toda resposta como meta.tier.
Sem limite por chave não é o mesmo que sem limite. Toda requisição para /api/, em qualquer plano, inclusive o Validator, também conta para um teto de 600 requisições por minuto por endereço IP. Violações sustentadas escalam para um bloqueio temporário do IP, então recue diante de um 429 em vez de repetir na hora. Planeja um backfill que precise de mais? Fale conosco antes.
Os limites são contados de formas diferentes. O limite por minuto é por chave e endpoint. O limite diário é por conta, ao longo de um dia UTC, e as chamadas de todas as suas chaves se somam. Para que cada plano pode ser usado. Uma chave de avaliação é para testes e o Pro é para uso pessoal. Os planos Data permitem o uso comercial, com atribuição, dos endpoints marcados como Planos Data na coluna Uso da referência de endpoints. Os endpoints marcados como Uso pessoal são de uso pessoal em todos os planos. Os termos estão em cctools.network/terms/api, e os números e os preços em Planos e limites. O plano Free acabou. Uma chave criada nele responde 401 com o código tier_retired e um renew_url que aponta para os planos: escolha um plano e crie uma chave nova.

​
Como obter um plano

Abra /profile/api. O painel de planos mostra o que a sua conta pode contratar, e New key fica desativado até ela ter um plano.
  • Pro: com uma assinatura do CCTools Pro, o painel de planos mostra o Pro como o seu plano. Aperte Set up keys uma vez (uma conta que teve uma chave Free ou de avaliação vê Upgrade to Pro tier no lugar) e depois New key.
  • Evaluation: para testar a API antes de comprar, peça uma chave de avaliação à nossa equipe. Uma conta que nunca teve um plano faz o pedido nessa página; qualquer outra conta fala conosco. Nossa equipe a emite sob pedido, somente para testes; quanto tempo ela dura está em Planos e limites.
  • Data Starter e Data Team: Buy Data Starter ou Buy Data Team e pague em Canton Coin, por um mês ou por um ano. Você aceita os termos da API ao pagar. Os pagamentos dos planos Data não são reembolsados, exceto quando a lei exigir. Um plano não se renova sozinho: o acesso termina no fim do período, a menos que você renove. Um plano Data comprado enquanto o mesmo plano, ou um maior, está em curso começa quando esse termina. Um plano Data menor em curso fica em pausa enquanto um maior está em curso e continua depois dele.
  • Validator: envie um party ID na mesma página.
  • Enterprise: fale conosco.
Precisa de mais do que um plano oferece? Fale conosco sobre o Enterprise em cctools.network/contact. As chaves que emitimos diretamente para uma organização ficam ligadas a essa organização, e não a uma pessoa, então não seguem o plano de nenhuma conta e não há nada que uma integração servidor-a-servidor precise manter viva. Uma chave para de funcionar quando é revogada ou quando expira; uma chave de plano expira quando o plano dela termina (401 com o código plan_ended). Suas chaves seguem o plano da sua conta, até o número de chaves do plano. Uma chave que você cria assume os limites do plano que a sua conta tem e vale até a cobertura desse plano acabar. Se você tem mais chaves do que o plano permite, ficam as usadas mais recentemente e as demais terminam. Quando você renova o Pro ou compra um plano Data, suas chaves existentes assumem a nova cobertura, então não há chave nova a criar: depois de renovar o Pro, aperte Extend access em /profile/api e suas chaves são estendidas na mesma medida. Apertá-lo nunca rebaixa nada: um plano Validator ou Enterprise concedido à sua conta permanece. Quando não resta nenhum plano, suas chaves respondem 401 com o código plan_ended e um renew_url. Renovar o Pro ou um plano Data as traz de volta; uma avaliação encerrada é estendida pela nossa equipe, então fale conosco.

​
Limites de requisições

Dois limites contam as suas chamadas. O limite por minuto é contado por chave, por endpoint, por minuto, por processo. A API roda como um cluster multiprocesso em que cada processo mantém o próprio contador, então um cliente que espalha requisições por muitas conexões pode ultrapassar o número informado antes que algo o barre. Trate o número como a taxa sustentada para a qual projetar, não como um teto a ser testado. Quando você de fato ultrapassa, recebe 429 com um cabeçalho Retry-After: 60:
O limite diário é contado por conta ao longo de um dia UTC, das 00:00 às 24:00 UTC. As chamadas de todas as suas chaves se somam (uma chave emitida pela nossa equipe tem um teto próprio), e uma chamada que um limite recusa não é contada. Acima do teto você recebe 429 com o código daily_limit, um Retry-After com os segundos que faltam até as 00:00 UTC e X-RateLimit-Remaining-Day: 0:
Uma recusa por minuto em um dia cujo teto já se esgotou também responde daily_limit, com o mesmo Retry-After. Uma chave sob um teto diário recebe X-RateLimit-Limit-Day e X-RateLimit-Remaining-Day em toda resposta bem-sucedida e nos dois 429, rate_limited e daily_limit; se o contador não puder ser lido, só X-RateLimit-Limit-Day é enviado. Toda resposta bem-sucedida também traz o seu teto em meta.rate_limit_remaining. Em planos sem limite por chave ele vem null, então tipe-o como nullable. meta.daily_limit_remaining são as chamadas que restam hoje; vem null quando o seu plano não tem limite diário ou o contador não pôde ser lido.
Apesar do nome, rate_limit_remaining é o seu teto, não uma contagem regressiva. Ele devolve o mesmo número em toda resposta e nunca decrementa, porque uma contagem exata por requisição custaria uma leitura de banco no caminho crítico. Não condicione sua lógica a ele cair em direção a zero, porque isso nunca vai acontecer. Use o 429 e o header Retry-After dele como o seu sinal real de recuo. daily_limit_remaining é a exceção: ele conta para baixo.

​
Erros

A maioria dos erros traz { "error": "...", "code": "..." }, mas o code é específico do endpoint, e não retirado de uma lista fixa. Ramifique pelo status HTTP, que é estável, e trate o code como detalhe. Duas respostas vêm da camada de borda antes de o handler rodar e trazem apenas { "error" }, sem nenhum code: o 403 para um cliente de ferramenta sem chave, e o 429 do teto por IP.

​
Boas práticas

Nunca publique uma chave em um bundle de navegador ou app mobile. Passe por um backend que você controla. Uma chave vazada pode ser usada até o limite dela até você revogá-la.
A revogação é imediata: a chave passa a devolver 401 na hora. Gere a substituta primeiro, migre o tráfego e só então revogue a antiga.
Respeite o Retry-After. Para cargas constantes, fique dentro dos limites do seu plano em vez de disparar rajadas e depois recuar.
Canton é uma marca registrada da Digital Asset (Switzerland) GmbH. A Digital Asset não é afiliada ao CCTools e não o patrocinou nem o endossou.