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 ofrece una potente API para mover dólares en la cadena sin desarrollar infraestructura bancaria, de custodia o cumplimiento desde cero. Si necesitas liquidar pagos en minutos, permitir depósitos con tarjeta y retiros en USDC, o transferir stablecoins entre ocho blockchains con una sola llamada, la API de Circle es la solución más directa. Consulta la documentación oficial en developers.circle.com y la guía básica de USDC en circle.com/en/usdc antes de comenzar la implementación.

Prueba Apidog hoy

En esta guía cubrimos: creación de cuentas, diferencias entre sandbox y producción, autenticación con Bearer token, endpoints para pagos y desembolsos, Circle Wallets (Web3 Services), CCTP, cifrado del secreto de entidad para Developer-Controlled Wallets, webhooks, idempotencia y cumplimiento KYB. Incluimos ejemplos prácticos en curl y Node.js para que puedas implementarlo directamente. Consulta también nuestra comparativa sobre la mejor API de rampa de entrada/salida de fiat donde analizamos Circle frente a sus competidores.

💡Para desarrollar y probar, necesitas un cliente API que soporte REST y Web3 de forma ágil. Apidog gestiona la autenticación Bearer de Circle, permite cambiar de entorno y simular webhooks en un solo workspace, facilitando pruebas simultáneas en sandbox y producción sin duplicar tus colecciones.

TL;DR

• La API de Circle es un conjunto de servicios: Circle Payments (tarjetas, ACH, transferencias), Circle Mint (emisión institucional de USDC), Circle Wallets/W3S (billeteras programables), y CCTP (quema y acuñación de USDC entre cadenas).
• Autenticación vía token Bearer; claves de sandbox inician con TEST_API_KEY:, las de producción con LIVE_API_KEY:.
• Developer-Controlled Wallets requieren un secreto de entidad cifrado (RSA, regenerado por solicitud) para operaciones de escritura.
• CCTP transfiere USDC nativo entre Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana y más mediante quema-acuñación atestiguada.
• Se exige aprobación KYB para producción; el sandbox está abierto a cualquier desarrollador.
• Usa claves de idempotencia en cada mutación y verifica firmas de webhooks con la clave pública de /notifications/publicKey/get.

¿Qué es la API de Circle?

Circle es una fintech regulada que emite USDC y opera la infraestructura para mantenerlo anclado al dólar. Su API expone cuatro productos principales que puedes integrar:

• Circle Payments API: acepta pagos vía tarjeta, ACH, SEPA y transferencias, liquidando como USDC en tu billetera de comerciante.
• Circle Payouts API: envía transferencias o ACH desde tu saldo USDC a cualquier cuenta bancaria previamente verificada.
• Circle Wallets (W3S): crea billeteras custodiadas o controladas por el desarrollador en múltiples cadenas, firma transacciones y gestiona el gas.
• CCTP: quema USDC en una cadena y acuña el equivalente en otra, entregando activos nativos sin tokens puenteados.

¿Comparando con otras soluciones Web3? Lee nuestro análisis de la mejor API de billetera de criptomonedas y la guía cómo usar la API de Alchemy para entender el posicionamiento de cada herramienta.

Autenticación y configuración

1. Crea una cuenta: en console.circle.com. Tienes dos entornos: sandbox (gratuito, autoservicio) y producción (requiere aprobación KYB, documentos legales y cuenta de fondeo).
2. Genera una clave API: desde Developers → API Keys.
   • Sandbox: TEST_API_KEY:<id>:<secret>
   • Producción: LIVE_API_KEY:<id>:<secret>
3. Autenticación: usa la clave como Bearer token:

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

URLs base:

• Sandbox: https://api-sandbox.circle.com
• Producción: https://api.circle.com

Developer-Controlled Wallets (W3S): necesitas un secreto de entidad (hexadecimal de 32 bytes) generado y registrado una vez. Cada operación de escritura incluye un nuevo entitySecretCiphertext cifrado con la clave pública RSA de Circle. El SDK de Node lo maneja automáticamente; si implementas tu versión, asegúrate de rotar el cifrado en cada solicitud.

Instala el SDK de Node.js:

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

Puntos finales principales

Crear un conjunto de billeteras y una billetera

Las billeteras en W3S se agrupan en un conjunto de billeteras (wallet set). Primero crea el set, luego genera billeteras individuales:

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 retorna un id, una address y la blockchain asociada. Usa el faucet de Circle para fondear con USDC de testnet.

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 en ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

La respuesta incluye un id de transacción consultable por GET /v1/w3s/transactions/{id} o vía 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": "[e-mail]", "sessionId": "..." }
  }'

Los datos de la tarjeta deben cifrarse con PGP usando la clave pública de Circle (/v1/encryption/public). El resultado retorna un id de pago con estados: pending → confirmed → paid.

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": "[e-mail]" }
  }'

Mover USDC entre cadenas con CCTP

CCTP es un protocolo en smart contracts, no un endpoint REST. El flujo es:

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

Esto entrega USDC nativo en la cadena destino, evitando tokens envueltos y riesgos de puente.

Webhooks e idempotencia

• Circle envía eventos POST (payments, payouts, transfers, chargebacks) a tus endpoints HTTPS suscritos vía /v1/notifications/subscriptions.
• Todos los webhooks están firmados (ECDSA). Recupera la clave pública con /v1/notifications/publicKey/get y verifica el header X-Circle-Signature antes de procesar el payload.
• Los endpoints mutantes requieren un header Idempotency-Key (UUID v4 recomendado). Una solicitud repetida con la misma clave retorna la respuesta original, evitando duplicados en pagos o transferencias.

Errores comunes y límites de tasa

• 401 Unauthorized: Token Bearer ausente, mal formado o ambiente incorrecto.
• 400 invalid_entity_secret_ciphertext: Texto cifrado reutilizado o clave pública desactualizada. Regenera y reintenta.
• 429 Too Many Requests: Sandbox ~10 req/s por endpoint, producción escala con volumen. Implementa backoff exponencial.
• insufficient_funds: Saldo insuficiente en la billetera o verificación AVS/CVV fallida en la tarjeta.

Consulta nuestro resumen de la mejor API de emisión de tarjetas para ver emisores que se integran bien con Circle.

Precios de la API de Circle

• Sandbox: gratuito.
• Producción: Circle Mint no cobra por acuñar/canjear USDC (clientes institucionales con volumen).
• Circle Payments: comisión por transacción con tarjeta (2.9% + $0.30 típico, negociable).
• Payouts bancarios en EE.UU.: pocos dólares por transacción.
• Wallets W3S: precio por billetera y transacción (contactar ventas).
• CCTP: gratuito; pagas únicamente el gas de origen y destino.

Probando la API de Circle con Apidog

La API de Circle abarca REST, webhooks firmados y contratos on-chain, lo que hace que una sola colección de Postman sea insuficiente. Apidog importa la OpenAPI de Circle, gestiona tokens de sandbox y producción como entornos separados, y permite automatizar scripts que encadenan pagos, desembolsos y pruebas de webhooks en una sola ejecución.

Descarga Apidog y carga la especificación de Circle desde su portal. Usa el simulador de webhooks para probar tu manejador de firmas antes de apuntar a tu endpoint real. Para equipos, el workspace compartido protege tu secreto de entidad y versiona colecciones junto al backend.

Preguntas frecuentes

¿Necesito KYB para probar la API de Circle?

No. El sandbox está abierto a cualquier correo electrónico. KYB solo es necesario para operar en producción con fondos reales. El sandbox incluye faucets de USDC en todas las cadenas compatibles.

¿Diferencias entre Circle Mint y Circle Wallets?

Circle Mint es la rampa institucional: depositas USD y recibes USDC (o viceversa). Circle Wallets/W3S es infraestructura de custodia y transacción para usuarios finales. Apps de consumo usan Wallets, tesorería usa Mint. Consulta nuestra guía cómo usar la API de MoonPay para alternativas minoristas.

¿Cómo evita CCTP el riesgo de puente?

USDC nativo se quema en la cadena de origen y se acuña en la de destino con atestación firmada por Circle. No hay fondos bloqueados expuestos a exploits de bridge; solo confías en el servicio de atestación de Circle.

¿Puedo usar Circle Wallets sin gestionar claves privadas?

Sí. Las User-Controlled Wallets en W3S usan MPC y autenticación PIN. Los usuarios finales autorizan transacciones vía SDK de Circle, sin exponer llaves privadas. Developer-Controlled Wallets delega la firma al backend usando el secreto de entidad.

¿Circle soporta Solana y cadenas no EVM?

Sí. W3S soporta Solana, Aptos, NEAR y varias L2 EVM. CCTP v2 añadió soporte para Solana en 2024, permitiendo transferencias nativas entre Solana y el ecosistema EVM.

¿Cómo roto el secreto de entidad de forma segura?

Circle permite rotar el secreto desde el panel. Genera uno nuevo, regístralo y opera ambos cifrados en paralelo durante la transición. El SDK lee el secreto de tu variable de entorno, facilitando la rotación en CI/CD.