Cómo Usar la API de Circle: Pagos USDC, Billeteras y Liquidaciones

Circle emite USDC, la segunda stablecoin más grande por capitalización de mercado, y expone un conjunto de APIs que te permiten mover dólares en la cadena sin construir infraestructura de custodia, cumplimiento o bancaria desde cero. Si alguna vez has querido liquidar un pago de mercado en minutos, permitir a un usuario depositar con tarjeta y retirar como USDC, o mover stablecoins a través de ocho blockchains con una sola llamada, la API de Circle es el camino más corto. La documentación oficial se encuentra en developers.circle.com, y la guía básica de USDC en circle.com/en/usdc vale la pena leerla antes de empezar a programar.

Esta guía recorre toda la superficie para desarrolladores: creación de cuentas, entorno de pruebas (sandbox) vs. producción, autenticación con token Bearer, puntos finales de pagos y desembolsos, Circle Wallets (Servicios Web3), el Protocolo de Transferencia entre Cadenas (CCTP), el texto cifrado del secreto de entidad para Developer-Controlled Wallets, webhooks, idempotencia y cumplimiento KYB. Espera fragmentos de curl y Node que puedes pegar en tu terminal. Lectura relacionada: nuestra guía sobre la mejor API de rampa de entrada/salida de fiat compara Circle con sus competidores más cercanos.

💡

También querrás un cliente API que hable REST y Web3 con fluidez mientras creas prototipos. Apidog maneja la autenticación Bearer de Circle, el cambio de entorno y la repetición de webhooks en un solo espacio de trabajo, para que puedas probar el sandbox y la producción en paralelo sin reescribir tu colección.

botón

TL;DR

La API de Circle es una familia de servicios: Circle Payments (tarjetas, ACH, transferencias bancarias), Circle Mint (emisión institucional de USDC), Circle Wallets / W3S (billeteras programables) y CCTP (quema y acuñación de USDC nativos entre cadenas).
Autentícate con un token Bearer; las claves del entorno de pruebas (sandbox) comienzan con TEST_API_KEY: y las claves de producción con LIVE_API_KEY:.
Las Developer-Controlled Wallets requieren un texto cifrado del secreto de entidad (cifrado RSA, regenerado por solicitud) para todas las operaciones de escritura.
CCTP mueve USDC nativos a través de Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana y más mediante una quema-acuñación atestiguada.
Se requiere aprobación KYB para producción. El sandbox está abierto a cualquier desarrollador.
Usa claves de idempotencia en cada solicitud mutante y verifica las firmas de los webhooks con la clave pública de /notifications/publicKey/get.

¿Qué es la API de Circle?

Circle es una empresa de pagos regulada que emite USDC y opera los rieles que lo mantienen anclado al dólar estadounidense. La API de Circle expone cuatro líneas de productos que puedes combinar:

La API de Circle Payments acepta tarjetas, ACH, SEPA y transferencias bancarias, y luego liquida el resultado como USDC en tu billetera de comerciante.
La API de Circle Payouts envía transferencias bancarias o ACH desde tu saldo de USDC a cualquier cuenta bancaria que hayas incorporado como beneficiario.
Circle Wallets (W3S) crea billeteras custodiadas o controladas por el desarrollador en múltiples cadenas, firma transacciones y maneja el gas.
CCTP quema USDC en una cadena de origen y acuña USDC equivalente en una cadena de destino, para que obtengas activos nativos, no un envoltorio puenteado.

Si estás comparando Circle con infraestructura Web3 de propósito general, lee nuestro desglose de la mejor API de billetera de criptomonedas y la guía cómo usar la API de Alchemy para ver dónde encaja cada herramienta.

Autenticación y configuración

Crea una cuenta en console.circle.com. La consola te ofrece dos entornos: de pruebas (sandbox) y de producción. El sandbox es gratuito y de autoservicio; la producción requiere aprobación Know Your Business (KYB), lo que lleva unos días hábiles y necesita documentos de constitución, información del beneficiario final y una cuenta de financiación.

Genera una clave API en Desarrolladores → Claves API. El formato de la clave es TEST_API_KEY:<id>:<secret> en el sandbox o LIVE_API_KEY:<id>:<secret> en producción. Pásala como un token Bearer:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

URLs base:

Entorno de pruebas (Sandbox): https://api-sandbox.circle.com
Producción: https://api.circle.com

Para las Developer-Controlled Wallets en W3S, también necesitas un secreto de entidad: una cadena hexadecimal de 32 bytes que generas una vez y registras a través del panel de control. Cada llamada de escritura debe incluir un entitySecretCiphertext nuevo, que es el secreto de entidad cifrado con la clave pública RSA de Circle. El SDK de Node lo regenera automáticamente; si implementas el tuyo propio, rota el texto cifrado en cada solicitud porque Circle rechaza los valores reutilizados.

Instala el SDK de Node:

npm install @circle-fin/developer-controlled-wallets

Puntos finales principales

Crear un conjunto de billeteras y una billetera

Las billeteras en W3S residen dentro de un conjunto de billeteras (un grupo que comparte una semilla HD). Crea el conjunto primero, luego genera billeteras dentro de él.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

Cada billetera devuelve un id, una address y la blockchain en la que reside. Fúndala con USDC de testnet del grifo de Circle para continuar.

Transferir USDC desde una billetera controlada por el desarrollador

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC on ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

La respuesta devuelve un id de transacción que puedes consultar a través de GET /v1/w3s/transactions/{id} o escuchar a través de un webhook.

Aceptar un pago con tarjeta y liquidar como USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

Los datos de la tarjeta deben estar cifrados con PGP usando la clave pública de Circle (obtenla de /v1/encryption/public). La respuesta devuelve un id de pago que pasa por los estados pendiente → confirmado → pagado.

Enviar un pago vía transferencia bancaria o ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

Mover USDC entre cadenas con CCTP

CCTP es un protocolo de contrato inteligente, no un punto final REST, por lo que combinas una quema en cadena con el servicio de atestación de Circle:

Llama a depositForBurn en el contrato TokenMessenger en la cadena de origen.
Consulta https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} hasta que status: "complete" y recibas un blob hexadecimal de attestation.
Llama a receiveMessage en el contrato MessageTransmitter en la cadena de destino con los bytes del mensaje y la atestación.

Obtienes USDC nativos en la cadena de destino, acuñados de la nada contra una quema verificable. Sin tokens envueltos, sin riesgo de liquidez del puente.

Webhooks e idempotencia

Circle envía eventos POST (payments, payouts, transfers, chargebacks) a cualquier punto final HTTPS al que te suscribas a través de /v1/notifications/subscriptions. Cada webhook está firmado con una clave ECDSA; obtén la clave pública de /v1/notifications/publicKey/get y verifica el encabezado X-Circle-Signature antes de confiar en la carga útil.

Cada punto final mutante requiere un encabezado Idempotency-Key (un UUID v4 es estándar). Reintentar una solicitud con la misma clave devuelve la respuesta original en lugar de crear un pago duplicado. Esto es importante: las tarjetas y transferencias no perdonan los envíos duplicados.

Errores comunes y límites de tasa

401 Unauthorized: Token Bearer faltante, mal formado o entorno incorrecto.
400 invalid_entity_secret_ciphertext: reutilizaste un texto cifrado o cifraste contra una clave pública desactualizada. Regenera y reintenta.
429 Too Many Requests: el sandbox tiene un límite de alrededor de 10 solicitudes por segundo por punto final; los límites de producción escalan con el volumen. Retrocede exponencialmente.
insufficient_funds: la billetera de origen no tiene suficiente USDC, o la tarjeta de origen falló la verificación AVS/CVV.

Para una visión más amplia de la infraestructura de tarjetas, nuestro resumen de la mejor API de emisión de tarjetas cubre a los emisores que se combinan bien con los pagos de Circle.

Precios de la API de Circle

El sandbox es gratuito. En producción, Circle Mint no cobra nada por acuñar o canjear USDC para clientes institucionales aprobados con volumen calificado. Circle Payments cobra un porcentaje más una tarifa fija por transacción con tarjeta (típicamente 2.9% + 30 centavos, negociado a escala). Los pagos a transferencias bancarias de EE. UU. cuestan unos pocos dólares por transacción. Las billeteras W3S tienen un precio por billetera y por transacción; contacta a ventas para una cotización de producción. CCTP en sí es gratuito; pagas el gas de la cadena de origen y destino.

Probando la API de Circle con Apidog

La superficie de Circle abarca REST, webhooks firmados y contratos en cadena, por lo que una única colección de Postman rara vez captura el flujo completo. Apidog importa la especificación OpenAPI de Circle directamente, almacena tokens Bearer de sandbox y producción como entornos separados, y te permite escribir un script de prueba que encadena un pago con tarjeta, un desembolso y una verificación de webhook en una sola ejecución.

Descarga Apidog y carga la especificación de Circle desde su portal de desarrolladores. Usa el servidor de simulación para simular entregas de webhook mientras construyes el manejador de verificación, luego cambia a un punto final real una vez que estés listo. Para equipos, el espacio de trabajo compartido mantiene tu secreto de entidad fuera del chat y versiona tu colección junto con el código de tu backend.

Preguntas frecuentes

¿Necesito KYB para probar la API de Circle?No. Las cuentas de sandbox están abiertas a cualquier persona con una dirección de correo electrónico. Solo necesitas KYB para mover dólares reales en producción. El sandbox viene con grifos para USDC en todas las cadenas compatibles.

¿Cuál es la diferencia entre Circle Mint y Circle Wallets?Circle Mint es la rampa de entrada institucional: depositas USD por transferencia y obtienes USDC (y viceversa). Circle Wallets / W3S es la infraestructura de custodia y transacciones para tus usuarios finales. La mayoría de las aplicaciones de consumo utilizan Wallets; las aplicaciones de tesorería utilizan Mint directamente. Nuestra guía cómo usar la API de MoonPay cubre una alternativa solo para minoristas si no necesitas la emisión a nivel de Mint.

¿Cómo evita CCTP el riesgo de puente?El USDC nativo se quema en la cadena de origen y se acuña de nuevo en la cadena de destino contra una atestación firmada por Circle. No hay un fondo de liquidez bloqueado que un exploit de puente pueda vaciar. Sigues confiando en el servicio de atestación de Circle, pero no estás confiando en un conjunto de validadores de puente de terceros.

¿Puedo usar Circle Wallets sin tener las claves?Sí. Las User-Controlled Wallets en W3S utilizan MPC y autenticación basada en PIN, por lo que los usuarios finales autorizan las transacciones a través del SDK de Circle y nunca tocas una clave privada. Las Developer-Controlled Wallets delegan la autoridad de firma en tu backend a través del secreto de entidad.

¿Circle soporta Solana y cadenas no EVM?Sí. W3S cubre Solana, Aptos, NEAR y varias L2 de EVM. CCTP v2 amplió el soporte para Solana en 2024, por lo que el USDC nativo ahora se mueve libremente entre Solana y el ecosistema EVM.

¿Cómo roto el secreto de entidad de forma segura?Circle soporta la rotación del secreto de entidad a través del panel de control. Genera un nuevo secreto, regístralo y ejecuta tanto los cifrados antiguos como los nuevos en paralelo durante una breve ventana de transición. El SDK lee el secreto que se encuentre en tu variable de entorno, por lo que una implementación continua lo maneja de manera limpia.