Saltar al contenido principal

​
Claves de API

Cada solicitud a un endpoint /api/v1/public/ se autentica con una clave en el header X-API-Key, salvo las solicitudes a /api/v1/public/status, que no la necesita. La ruta de pago por llamada en /api/v1/x402/ no usa clave (ver Paga por llamada con x402):
Las claves son cadenas con la forma cck_ seguida de 56 caracteres hexadecimales. No hay soporte para Authorization: Bearer. Desde un navegador, un token Bearer devuelve 401. Desde un cliente de línea de comandos como curl o python-requests se rechaza una capa antes, como 403 {"error":"Forbidden"} sin campo code, porque una solicitud sin X-API-Key no se reconoce en absoluto como cliente de API. Envía siempre X-API-Key. Crea, lista y revoca claves en cctools.network/profile/api. El texto en claro se muestra exactamente una vez al crearla; después solo queda visible el prefijo. Cuando ya tengas una, cctools.network/api-docs ejecuta cualquier endpoint con ella desde el navegador. Cuántas claves activas puedes tener depende de tu plan; el número de cada uno está en Planes y límites. El límite por minuto se cuenta por clave y endpoint, así que cada clave extra suma rendimiento, mientras que el límite diario se cuenta para toda la cuenta y no crece con el número de claves.

​
Planes

Tu clave tiene el plan de tu cuenta, y el plan fija tus límites de solicitudes. Se refleja en cada respuesta como meta.tier.
Sin límite por clave no es lo mismo que sin límite. Cada solicitud a /api/, en todos los planes incluido Validator, también cuenta contra un techo de 600 solicitudes por minuto por dirección IP. Los excesos sostenidos escalan a un bloqueo temporal de la IP, así que espera tras un 429 en lugar de reintentar de inmediato. ¿Planeas un backfill que necesite más que eso? Consúltanos antes.
Los límites se cuentan de forma distinta. El límite por minuto es por clave y endpoint. El límite diario es por cuenta, durante un día UTC, y se suman las llamadas de todas tus claves. Para qué puede usarse cada plan. Una clave de evaluación es para pruebas y Pro es para uso personal. Los planes Data permiten el uso comercial, con atribución, de los endpoints marcados como Planes Data en la columna Uso de la referencia de endpoints. Los endpoints marcados como Uso personal son de uso personal en todos los planes. Los términos están en cctools.network/terms/api, y las cifras y los precios en Planes y límites. El plan Free ya terminó. Una clave creada con él responde 401 con el código tier_retired y un renew_url que apunta a los planes: elige un plan y crea una clave nueva.

​
Cómo obtener un plan

Abre /profile/api. El panel de planes muestra lo que tu cuenta puede contratar, y New key sigue desactivado hasta que tenga un plan.
  • Pro: con una suscripción a CCTools Pro, el panel de planes muestra Pro como tu plan. Pulsa Set up keys una vez (una cuenta que tuvo una clave Free o de evaluación ve Upgrade to Pro tier en su lugar) y luego New key.
  • Evaluation: para probar la API antes de comprar, pide una clave de evaluación a nuestro equipo. Una cuenta que nunca tuvo un plan la solicita en esa página; cualquier otra cuenta nos contacta. Nuestro equipo la emite a petición, solo para pruebas; cuánto dura está en Planes y límites.
  • Data Starter y Data Team: Buy Data Starter o Buy Data Team y paga en Canton Coin, por un mes o por un año. Aceptas los términos de la API al pagar. Los pagos de los planes Data no se reembolsan, salvo cuando la ley lo exija. Un plan no se renueva solo: el acceso termina al final del periodo salvo que lo renueves. Un plan Data comprado mientras corre el mismo plan u otro mayor empieza cuando ese termina. Un plan Data menor que está en curso se pausa mientras corre uno mayor y se reanuda después.
  • Validator: envía un party ID en la misma página.
  • Enterprise: contáctanos.
¿Necesitas más de lo que da un plan? Habla con nosotros sobre Enterprise en cctools.network/contact. Las claves que emitimos directamente a una organización quedan ligadas a esa organización y no a una persona, así que no siguen el plan de ninguna cuenta ni hay nada que una integración servidor a servidor deba mantener viva. Una clave deja de funcionar cuando se revoca o cuando expira; una clave de plan expira cuando termina su plan (401 con el código plan_ended). Tus claves siguen el plan de tu cuenta, hasta el número de claves del plan. Una clave que creas toma los límites del plan que tiene tu cuenta y funciona hasta que termina la cobertura de ese plan. Si tienes más claves de las que permite el plan, se mantienen las que usaste más recientemente y las demás terminan. Cuando renuevas Pro o compras un plan Data, tus claves existentes toman la nueva cobertura, así que no hace falta crear otra: tras renovar Pro, pulsa Extend access en /profile/api y tus claves se extienden en consecuencia. Pulsarlo nunca degrada nada: un plan Validator o Enterprise concedido a tu cuenta se mantiene. Cuando no queda ningún plan, tus claves responden 401 con el código plan_ended y un renew_url. Renovar Pro o un plan Data las devuelve a funcionar; una evaluación terminada la extiende nuestro equipo, así que contáctanos.

​
Límites de solicitudes

Dos límites cuentan tus llamadas. El límite por minuto se cuenta por clave, por endpoint, por minuto, por proceso. La API corre como un clúster multiproceso donde cada proceso mantiene su propio contador, así que un cliente que reparte solicitudes entre muchas conexiones puede superar la cifra indicada antes de que algo lo frene. Trata el número como la tasa sostenida para la que diseñar, no como un techo que sondear. Cuando lo superas recibes un 429 con un header Retry-After: 60:
El límite diario se cuenta por cuenta durante un día UTC, de las 00:00 a las 24:00 UTC. Se suman las llamadas de todas tus claves (una clave emitida por nuestro equipo tiene su propio tope), y una llamada que un límite rechaza no se cuenta. Por encima del tope recibes un 429 con el código daily_limit, un Retry-After con los segundos que faltan hasta las 00:00 UTC y X-RateLimit-Remaining-Day: 0:
Un rechazo por minuto en un día cuyo tope ya se agotó también responde daily_limit, con el mismo Retry-After. Una clave con tope diario recibe X-RateLimit-Limit-Day y X-RateLimit-Remaining-Day en cada respuesta correcta y en los dos 429, rate_limited y daily_limit; si no se puede leer el contador, solo se envía X-RateLimit-Limit-Day. Cada respuesta correcta también lleva tu techo en meta.rate_limit_remaining. En los planes sin límite por clave es null, así que decláralo como nullable. meta.daily_limit_remaining son las llamadas que te quedan hoy; es null cuando tu plan no tiene tope diario o no se pudo leer el contador.
A pesar del nombre, rate_limit_remaining es tu techo, no una cuenta regresiva. Devuelve el mismo número en cada respuesta y nunca disminuye, porque un conteo exacto por solicitud costaría una lectura de base de datos en el camino crítico. No condiciones tu lógica a que baje hacia cero, porque nunca lo hará. Usa el 429 y su header Retry-After como tu señal real de retroceso. daily_limit_remaining es la excepción: ese sí cuenta hacia atrás.

​
Errores

La mayoría de los errores llevan { "error": "...", "code": "..." }, pero el code es específico del endpoint y no sale de una lista fija. Ramifica según el estado HTTP, que es estable, y trata code como detalle. Dos respuestas vienen de la capa edge antes de que corra el handler y llevan solo { "error" } sin ningún code: el 403 para un cliente de herramienta sin clave y el 429 del techo por IP.

​
Buenas prácticas

Nunca incluyas una clave en un bundle de navegador o en una app móvil. Pasa por un backend que controles. Una clave filtrada puede usarse hasta agotar su límite mientras no la revoques.
Revocar es inmediato: la clave empieza a devolver 401 de una vez. Genera primero una clave de reemplazo, migra a ella y luego revoca la antigua.
Respeta Retry-After. Para cargas de trabajo constantes, mantente dentro de los límites de tu plan en lugar de hacer ráfagas y luego frenar.
Canton es una marca registrada de Digital Asset (Switzerland) GmbH. Digital Asset no está afiliada a CCTools, y no lo ha patrocinado ni respaldado.