Blog

Cómo Usar la API de Circle para Operar con USDC

Mark Ponomarev

Mark Ponomarev

23 June 2025

Cómo Usar la API de Circle para Operar con USDC

USD Coin (USDC) se ha consolidado como una piedra angular de estabilidad y fiabilidad. Como una stablecoin totalmente respaldada por dólares, USDC cierra la brecha entre la moneda fiduciaria tradicional y el floreciente mundo de los activos digitales. Ofrece la velocidad y el alcance global de las criptomonedas, al tiempo que mantiene la estabilidad de precios del dólar estadounidense, lo que la convierte en un medio ideal para el comercio, las transacciones y las remesas en internet.

En el corazón del ecosistema USDC se encuentra Circle, el desarrollador principal de la stablecoin. Circle proporciona un conjunto de APIs que permiten a desarrolladores y empresas integrar USDC en sus aplicaciones de manera fluida. La Circle Mint API, en particular, ofrece una potente puerta de enlace para acuñar nuevo USDC, canjearlo por moneda fiduciaria y transferirlo a través de una multitud de blockchains compatibles. Esto no es "comercio" en el sentido de especular sobre las fluctuaciones de precios en un mercado abierto, sino algo más fundamental: la capacidad de mover valor programáticamente, de incorporar fondos desde los sistemas financieros tradicionales al mundo digital y de retirarlos de nuevo.

Este artículo es su guía completa para dominar la API de Circle para transacciones con USDC. Nos embarcaremos en un viaje detallado, desde la configuración inicial de su cuenta de desarrollador hasta la ejecución de transferencias y pagos complejos. Cubriremos:

Al final de esta guía, tendrá el conocimiento y los ejemplos prácticos necesarios para construir aplicaciones sofisticadas que aprovechen el poder de un dólar digital estable, global y programable.

💡
¿Quiere una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada, todo en uno, para que su equipo de desarrolladores trabaje con máxima productividad?

¡Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Primeros Pasos con Circle

Antes de que pueda escribir una sola línea de código, necesita configurar su entorno de desarrollo y obtener sus credenciales. Este paso fundamental es crucial para un proceso de integración fluido.

Entornos de Pruebas (Sandbox) vs. Producción

Circle proporciona dos entornos distintos para sus APIs: Sandbox y Producción. Comprender sus roles es el primer paso para una integración exitosa y segura.

Los hosts de API para cada entorno son los siguientes:

Entorno URL del Host de la API
Sandbox https://api-sandbox.circle.com
Producción https://api.circle.com

A lo largo de esta guía, todos los ejemplos utilizarán la URL del sandbox. Esta es una mejor práctica crítica: siempre desarrolle y pruebe primero en el entorno sandbox.

Creación de su Cuenta Sandbox

Su viaje comienza creando una cuenta de desarrollador de Circle, lo que le dará acceso al entorno sandbox.

  1. Navegue al Sitio Web de Circle: Vaya a la página oficial de desarrolladores de Circle.
  2. Regístrese: Busque la opción para registrarse para una cuenta de desarrollador o sandbox. Deberá proporcionar información básica, como su dirección de correo electrónico y una contraseña segura.
  3. Verifique su Correo Electrónico: Después de enviar el formulario de registro, recibirá un correo electrónico de verificación. Haga clic en el enlace dentro de este correo electrónico para activar su cuenta.
  4. Acceda al Panel de Control: Una vez que su cuenta esté verificada, podrá iniciar sesión en el panel de control de desarrollador. Este panel es su centro principal para administrar sus aplicaciones, claves de API y ver su actividad en el sandbox.

Generación de su Primera Clave de API

Una clave de API es un token secreto único que autentica las solicitudes de su aplicación a la API de Circle. Demuestra que una solicitud proviene de usted y no de un tercero no autorizado.

Aquí le mostramos cómo generar una clave de API desde su nuevo panel de control sandbox:

  1. Inicie sesión en su cuenta de desarrollador sandbox de Circle.
  2. Navegue a la Sección de Claves de API: En el panel de control, busque una sección etiquetada como "Claves de API" o "Configuración de Desarrollador".
  3. Cree una Nueva Clave: Habrá una opción para "Crear una Nueva Clave de API". Haga clic en ella.
  4. Asigne un Nombre a su Clave: Déle a su clave un nombre descriptivo (por ejemplo, "Mi Aplicación de Trading - Prueba"). Esto le ayudará a identificar el propósito de la clave más adelante, especialmente si tiene varias claves para diferentes aplicaciones.
  5. Copie y Asegure su Clave: Después de la creación, su clave de API se mostrará en la pantalla. Esta es la única vez que se mostrará la clave completa. Debe copiarla inmediatamente y almacenarla en un lugar seguro, como un gestor de contraseñas o un archivo de variables de entorno para su proyecto. No codifique su clave de API directamente en su código fuente.

Su clave de API es una información sensible. Cualquiera que la tenga puede realizar solicitudes en nombre de su cuenta. Trátela con el mismo nivel de seguridad que trataría una contraseña.

Autenticación y Configuración Inicial

Con su clave de API en mano, ahora está listo para realizar sus primeras llamadas a la API de Circle. El primer paso es dominar el proceso de autenticación y probar su conexión para asegurarse de que todo esté configurado correctamente.

Autenticación de API: El Token de Portador (Bearer Token)

La API de Circle utiliza el esquema de autenticación Bearer Token. Este es un método de autenticación HTTP estándar donde cada solicitud de API debe incluir un encabezado Authorization que contenga su clave de API.

El formato del encabezado es: Authorization: Bearer YOUR_API_KEY

Debe reemplazar YOUR_API_KEY con la clave secreta real que generó en el capítulo anterior.

Probando su Conexión

Antes de sumergirse en transacciones complejas, es esencial realizar dos pruebas simples: una para verificar la conectividad básica de red a los servidores de la API de Circle y otra para verificar que su clave de API esté configurada correctamente.

Probando la Conectividad Bruta con /ping

El endpoint /ping es una simple verificación de estado. No requiere autenticación y se utiliza para confirmar que puede llegar a los servidores de la API de Circle.

Así es como se llama usando cURL, una herramienta común de línea de comandos para realizar solicitudes HTTP:

curl -H 'Accept: application/json' \
  -X GET --url https://api-sandbox.circle.com/ping

Respuesta Exitosa:

Si su conexión es exitosa, la API devolverá un objeto JSON simple:

{
  "message": "pong"
}

Si recibe esta respuesta, ha establecido con éxito una conexión con el entorno sandbox. Si no, verifique su conexión de red, firewalls o cualquier error tipográfico en la URL.

Probando su Clave de API con /v1/configuration

Ahora, probemos si su clave de API es válida y está formateada correctamente. El endpoint /v1/configuration recupera información de configuración básica para su cuenta y requiere autenticación.

Aquí está el comando cURL. Recuerde reemplazar ${YOUR_API_KEY} con su clave de API real. Por seguridad, es mejor usar una variable de entorno.

# Es una buena práctica almacenar su clave de API en una variable de entorno
# export YOUR_API_KEY='SU_CLAVE_AQUI'

curl -H 'Accept: application/json' \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -X GET --url https://api-sandbox.circle.com/v1/configuration

Respuesta Exitosa:

Una solicitud exitosa devolverá un objeto JSON que contiene su ID de monedero maestro. El masterWalletId es el identificador único para el monedero principal asociado a su cuenta donde se guardan sus fondos.

{
  "data": {
    "payments": {
      "masterWalletId": "1234567890"
    }
  }
}

Respuesta de Error:

Si hay un problema con su clave de API o cómo ha formateado el encabezado Authorization, recibirá un error 401 Unauthorized.

{
  "code": 401,
  "message": "Malformed authorization. Are the credentials properly encoded?"
}

Si ve este error, verifique lo siguiente:

Uso de SDKs de Circle para una Integración más Sencilla

Aunque siempre puede interactuar con la API directamente usando solicitudes HTTP, Circle proporciona Kits de Desarrollo de Software (SDKs) para lenguajes de programación populares como Node.js, Python y Java. Estos SDKs manejan el código repetitivo para la autenticación, el formato de las solicitudes y el análisis de las respuestas, lo que hace que su proceso de desarrollo sea más rápido y menos propenso a errores.

Aquí tiene un breve ejemplo de cómo podría inicializar el SDK de Circle para Node.js:

// Instale el SDK primero: npm install @circle-fin/circle-sdk

import { Circle, CircleEnvironments } from "@circle-fin/circle-sdk";

const circle = new Circle(
  process.env.CIRCLE_API_KEY, // Clave de API de la variable de entorno
  CircleEnvironments.sandbox   // Apuntando al entorno sandbox
);

async function getConfiguration() {
  try {
    const response = await circle.core.getConfiguration();
    console.log(response.data.payments.masterWalletId);
  } catch (error) {
    console.error(error.response.data);
  }
}

getConfiguration();

El uso de un SDK abstrae los detalles de bajo nivel, lo que le permite centrarse en la lógica de negocio de su aplicación. Recomendamos usar un SDK para cualquier proyecto serio.

Conceptos Fundamentales y Recursos de la API

Para utilizar eficazmente la API de Circle, debe comprender su modelo de datos subyacente. La API se construye alrededor de un conjunto de recursos —objetos JSON que representan las entidades centrales del sistema, como pagos, monederos y transferencias.

Una Visión General de los Recursos de la API

Los recursos de Circle se pueden clasificar en varios grupos:

Recursos Principales: Estos representan las principales acciones financieras que puede realizar.

Métodos e Instrumentos:

Recursos Anidados: Estos son objetos que a menudo se incrustan dentro de otros recursos para proporcionar información detallada.

Análisis Detallado: El Objeto Payment

Un payment es cómo recibe fondos. Aunque la API admite pagos con tarjeta, para los casos de uso de USDC, a menudo tratará con pagos que financian su monedero de Circle.

Ejemplo de Objeto Payment:

{
  "id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
  "type": "payment",
  "merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
  "merchantWalletId": "1000002853",
  "amount": {
    "amount": "10.00",
    "currency": "USD"
  },
  "source": {
    "id": "86461e9f-db1a-487f-915b-641138062e7c",
    "type": "card"
  },
  "description": "New customer payment",
  "status": "confirmed",
  "fees": {
    "amount": "0.58",
    "currency": "USD"
  },
  "createDate": "2024-01-10T02:29:53.888Z",
  "updateDate": "2024-01-10T02:32:19.421Z"
}

Atributos Clave:

Análisis Detallado: El Objeto Transfer

Una transferencia es, posiblemente, el objeto más importante para "comerciar" o mover USDC. Representa el movimiento de moneda digital.

Ejemplo de Objeto Transfer:

{
  "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
  "source": {
    "type": "wallet",
    "id": "1000002853"
  },
  "destination": {
    "type": "blockchain",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
    "chain": "ETH"
  },
  "amount": {
    "amount": "150.50",
    "currency": "USD"
  },
  "status": "pending",
  "createDate": "2024-05-15T18:44:03.484Z",
  "updateDate": "2024-05-15T18:44:03.484Z"
}

Atributos Clave:

Objetos de Origen y Destino

Estos objetos anidados son vitales, ya que definen el flujo de fondos en cualquier transacción.

Su campo type determina el tipo de origen o destino:

Cadenas y Monedas Compatibles

Circle es agnóstico a las cadenas y expande constantemente su soporte. A finales de 2024, USDC está disponible en numerosas blockchains importantes, incluyendo:

Debe especificar el identificador chain correcto al realizar transferencias. Para las monedas fiduciarias, la API soporta principalmente USD y EUR. La currency en el objeto Money siempre debe establecerse en USD cuando se trata de transferencias de USDC.

Ejecutando Transacciones: El Ciclo de Vida Completo

Ahora llegamos al corazón del asunto: usar la API para mover dinero. Recorreremos un ciclo de vida completo: la incorporación de fiat para obtener USDC, la transferencia de ese USDC a una dirección externa y, finalmente, la retirada de fondos a una cuenta bancaria fiat.

Paso 1: Incorporación de Fiat con un Payment

Para muchas aplicaciones, el primer paso es convertir la moneda fiduciaria de un cliente en USDC en su monedero de Circle. El endpoint de la API Create Payment se utiliza para esto. Aunque la API admite varias fuentes de pago, nos centraremos en el concepto.

Supongamos que un cliente le está pagando 500 $. Haría una solicitud POST a /v1/payments.

Solicitud de API para Crear un Pago:

curl -X POST \
  https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "su-uuid-unico-aqui-para-pago",
        "source": {
          "id": "algun-id-de-tarjeta-o-banco",
          "type": "card"
        },
        "amount": {
          "amount": "500.00",
          "currency": "USD"
        },
        "description": "Pago por servicios prestados"
      }'

Nota Importante: La idempotencyKey es crucial aquí. Es un ID único (en formato UUID) que usted genera para esta solicitud. Si envía la misma solicitud dos veces (por ejemplo, debido a un error de red), Circle reconocerá la clave y solo procesará el pago una vez. Cubriremos esto con más detalle en el próximo capítulo.

Una vez que este pago se procesa y su status cambia a confirmed o paid, la cantidad equivalente de USDC (menos las tarifas) se acreditará a su merchantWalletId.

Paso 2: Verificando el Saldo de su Monedero

Después de recibir un pago, querrá verificar que los fondos han llegado. Puede verificar el saldo de cualquiera de sus monederos, pero más comúnmente su monedero maestro.

Solicitud de API para Obtener Saldos:

curl -X GET \
  https://api-sandbox.circle.com/v1/wallets/${YOUR_WALLET_ID}/balances \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Reemplace ${YOUR_WALLET_ID} con el masterWalletId que recuperó anteriormente.

Respuesta de la API:

La respuesta será una lista de saldos, uno por cada moneda que posea.

{
  "data": {
    "available": [
      {
        "amount": "495.50",
        "currency": "USD"
      }
    ],
    "unsettled": [
      {
        "amount": "0.00",
        "currency": "USD"
      }
    ]
  }
}

El saldo available es lo que puede transferir o pagar inmediatamente.

Paso 3: Transferencia de USDC en Cadena

Este es el núcleo del uso de USDC. Puede transferir fondos de su monedero a cualquier dirección externa en una blockchain compatible. Esto es perfecto para pagar a proveedores, mover fondos a un protocolo DeFi o enviar valor a un usuario.

Supongamos que desea enviar 100 USDC a una dirección de Ethereum.

Solicitud de API para Crear una Transferencia:

curl -X POST \
  https://api-sandbox.circle.com/v1/transfers \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "otro-uuid-unico-para-transferencia",
        "source": {
          "type": "wallet",
          "id": "1000002853"
        },
        "destination": {
          "type": "blockchain",
          "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
          "chain": "ETH"
        },
        "amount": {
          "amount": "100.00",
          "currency": "USD"
        }
      }'

Desglose del Cuerpo de la Solicitud:

La API responderá con un objeto Transfer, inicialmente con un status de pending.

Comprendiendo las Confirmaciones de Blockchain

Las transacciones en cadena no son instantáneas. Una transferencia debe ser transmitida a la red y luego confirmada por mineros o validadores. El status de su transferencia solo cambiará a complete después de haber recibido un número suficiente de confirmaciones en la blockchain. Circle gestiona esta complejidad por usted. Puede rastrear el estado ya sea consultando el endpoint GET /v1/transfers/{id} o, preferiblemente, utilizando webhooks (cubierto en el próximo capítulo) para recibir una notificación una vez que la transferencia se complete.

Paso 4: Retiro de USDC a Fiat con un Payout

El paso final en el ciclo de vida es convertir su USDC de nuevo en moneda fiduciaria en una cuenta bancaria. Esto se hace a través de un payout. Antes de poder crear un desembolso, primero debe vincular y verificar una cuenta bancaria, lo que crea un objeto Wire Account.

Una vez que tenga una cuenta bancaria de destino configurada (con su propio id), puede crear el desembolso.

Solicitud de API para Crear un Desembolso:

curl -X POST \
  https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
        "idempotencyKey": "otro-uuid-unico-para-desembolso",
        "destination": {
          "type": "wire",
          "id": "su-uuid-de-cuenta-bancaria-aqui"
        },
        "amount": {
          "amount": "250.00",
          "currency": "USD"
        }
      }'

La API responderá con un objeto Payout. El status será pending inicialmente y pasará a complete una vez que los fondos hayan sido enviados con éxito al banco de destino.

Características Avanzadas y Mejores Prácticas

Para construir una aplicación verdaderamente robusta y escalable, necesita ir más allá de las llamadas básicas a la API y aprovechar las características avanzadas que Circle proporciona. Estas características están diseñadas para garantizar la integridad de los datos, proporcionar actualizaciones en tiempo real y hacer que su aplicación sea resiliente.

Solicitudes Idempotentes: Prevención de Doble Gasto

Hemos mencionado la idempotencyKey varias veces, pero su importancia no puede ser exagerada. En los sistemas financieros, realizar accidentalmente una operación dos veces (como enviar un pago o una transferencia) puede ser catastrófico. Los problemas de red pueden hacer que una solicitud agote el tiempo de espera, incluso si el servidor la procesó con éxito. Sin idempotencia, su aplicación podría reintentar automáticamente la solicitud, lo que llevaría a una transacción duplicada.

Cómo funciona:

Esto garantiza que una solicitud específica solo se pueda ejecutar una vez, sin importar cuántas veces se envíe.

Mejor Práctica: Siempre genere y envíe una idempotencyKey para cada operación POST.

Actualizaciones en Tiempo Real con Webhooks

Consultar una API repetidamente para verificar el estado de una transacción (GET /v1/transfers/{id}) es ineficiente y lento. El enfoque correcto y moderno es usar webhooks.

Un webhook es un mensaje automatizado enviado desde una aplicación (Circle) a otra aplicación (la suya) cuando ocurre un evento específico. Puede configurar una URL en su panel de control de Circle donde desea recibir estas notificaciones.

Cuando el estado de un pago, transferencia o desembolso cambia, Circle enviará una solicitud POST a su URL configurada con una carga útil de notificación que contiene el objeto actualizado.

Ejemplo de Carga Útil de Notificación para una Transferencia Completada:

{
  "notification": {
    "id": "uuid-de-notificacion",
    "type": "transfers",
    "subscriptionId": "su-id-de-suscripcion"
  },
  "transfer": {
    "id": "c332d75a-3870-410c-b26a-93e5a3ab90e8",
    "source": { ... },
    "destination": { ... },
    "amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "status": "complete",
    "transactionHash": "0x123abc...",
    "createDate": "2024-05-15T18:44:03.484Z",
    "updateDate": "2024-05-15T18:48:12.123Z"
  }
}

Al escuchar estas notificaciones, su aplicación puede reaccionar instantáneamente a eventos como una transferencia completada o un pago fallido, proporcionando una experiencia de usuario mucho mejor y permitiendo la automatización en tiempo real.

Paginación y Filtrado: Manejo de Grandes Conjuntos de Datos

A medida que su aplicación crece, acumulará miles de pagos, transferencias y otros registros. Solicitar todos ellos a la vez utilizando un endpoint GET como /v1/transfers sería lento y engorroso.

La API de Circle utiliza la paginación basada en cursor para resolver esto. Cuando lista recursos, la respuesta solo contendrá un número limitado de elementos (la "página"). Puede controlar el tamaño de esta página con el parámetro pageSize. Para obtener la página siguiente o anterior de resultados, use los parámetros pageAfter o pageBefore, pasando el ID del último o primer elemento que vio.

Ejemplo: Obtener la primera página de 20 transferencias:
GET /v1/transfers?pageSize=20

Ejemplo: Obtener la siguiente página de 20 transferencias:
GET /v1/transfers?pageSize=20&pageAfter={id_de_la_ultima_transferencia_de_la_pagina_anterior}

También puede filtrar los resultados basándose en rangos de tiempo (marcas de tiempo from y to) y otros atributos específicos del recurso.

Manejo de Errores: Construyendo una Aplicación Resiliente

Las cosas pueden y van a salir mal. Una solicitud de API podría fallar debido a una entrada inválida, fondos insuficientes o un problema temporal del servidor. Una aplicación robusta debe anticipar y manejar estos errores con gracia.

La API de Circle utiliza códigos de estado HTTP estándar para indicar el resultado de una solicitud.

Cuando ocurre un error, el cuerpo de la respuesta de la API contendrá un objeto JSON con más detalles.

Ejemplo de Respuesta de Error (400 Bad Request):

{
  "code": 2,
  "message": "Invalid or missing parameter. See details for more information.",
  "errors": [
    {
      "location": "body",
      "message": "destination address is invalid",
      "param": "destination.address"
    }
  ]
}

Su código siempre debe estar envuelto en bloques try/catch (o el equivalente para su lenguaje) para manejar posibles excepciones de las llamadas a la API. Debe registrar los detalles del error y, si es apropiado, presentar un mensaje útil al usuario.

Conclusión: Empoderando el Futuro de las Finanzas

Hemos recorrido todo el proceso de uso de la API de Circle para realizar transacciones con USDC. Desde la configuración inicial del sandbox y la autenticación hasta la ejecución de pagos, transferencias y desembolsos, ahora posee el conocimiento fundamental para construir potentes aplicaciones financieras. También hemos explorado las características avanzadas como la idempotencia, los webhooks y el manejo de errores que son esenciales para crear sistemas profesionales y listos para producción.

La API de Circle hace más que simplemente permitirle mover una moneda digital; proporciona los raíles programables para un nuevo sistema financiero nativo de internet. Al abstraer las complejidades de la tecnología blockchain y proporcionar una API limpia y orientada a recursos, Circle empodera a los desarrolladores para innovar y construir la próxima generación de comercio global, servicios financieros y pagos entre pares.

Las posibilidades son inmensas. Las herramientas están en sus manos. Ahora, ¡vaya y construya algo asombroso!

💡
¿Quiere una excelente herramienta de prueba de API que genere hermosa documentación de API?

¿Quiere una plataforma integrada, todo en uno, para que su equipo de desarrolladores trabaje con máxima productividad?

¡Apidog satisface todas sus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar