Construir una aplicación con billeteras programables requiere entender cómo interactuar con el API de Circle de forma práctica. Aquí se recorre el flujo completo: desde obtener una llave de acceso hasta generar el challenge que permite al usuario configurar su pin de seguridad y crear su billetera.
¿Cómo obtener tu API Key en la plataforma de Circle?
Antes de hacer cualquier llamada, necesitas una API Key. En la página principal de Circle, en el menú izquierdo bajo la sección API Keys, se crea una nueva llave asignándole un nombre y presionando Create a key [0:26]. Es fundamental copiarla y guardarla de inmediato, ya que después de salir de esa página no volverás a verla.
Una vez copiada, se pega en el API Reference de Circle. Esto otorga permisos para experimentar libremente con todos los endpoints documentados en la plataforma [0:46].
¿Cuáles son los pasos para crear un usuario y su sesión?
El flujo replica lo que sucede tras bambalinas en una aplicación real, como la app de iOS mostrada en clases anteriores.
¿Cómo se crea un usuario nuevo?
El primer endpoint es Create a User, un método POST que escribe un usuario nuevo en el sistema [1:06]. Requiere un solo campo: un user ID único. Para generarlo fácilmente se puede usar un sitio como un online UUID generator, que produce identificadores irrepetibles [1:22].
- Se pega el UUID en el campo correspondiente.
- Una respuesta exitosa muestra el botón verde, aunque el cuerpo venga vacío.
- El usuario queda registrado con ese único identificador [1:46].
¿Qué es el user token y para qué sirve?
El siguiente paso es llamar al endpoint Create a User Token [1:56]. Este POST abre una sesión que permite al usuario completar el challenge. Usa el mismo user ID creado previamente, ya que es la única referencia de identidad del usuario.
La respuesta exitosa devuelve un objeto con dos propiedades clave:
- user token: el token de sesión necesario para los siguientes pasos.
- encryption key: la llave de cifrado asociada [2:26].
Ambos valores deben guardarse porque se utilizan en las llamadas posteriores.
¿Cómo se configura el pin y se crea la billetera con un challenge?
El tercer endpoint es Create a Challenge for Pin Setup and Create Wallets [2:46]. Este paso combina dos acciones: permite al usuario configurar su pin de seguridad y sus preguntas de recuperación, y simultáneamente prepara la creación de su billetera.
Los campos que solicita son:
- User ID: el mismo identificador único.
- Tipo de cuenta: se puede elegir entre EOA (Externally Owned Account) o Smart Contract Account. Para esta aplicación se usa smart contract account porque permite al usuario hacer transacciones sin preocuparse por el gas [3:10].
- Blockchain: se selecciona Eth Sepolia, un test net que evita usar fondos reales [3:28].
- X-User Token: se pega el user token generado en el paso anterior. Es un token largo, así que hay que copiarlo completo [3:46].
Al ejecutar la llamada, la respuesta exitosa devuelve un challenge ID [4:06]. En la aplicación de iOS, este identificador se envía directamente al cliente y es lo que dispara la interfaz donde el usuario establece su pin y responde las preguntas de seguridad.
¿Por qué el challenge ID es tan importante?
Cada vez que una billetera controlada por el usuario quiere ejecutar una transacción, debe usar su pin para confirmar que es el dueño legítimo [4:20]. Esa confirmación genera una solicitud al API de Circle mediante un nuevo challenge ID. Es el mecanismo central de seguridad del flujo.
Dentro del API Reference existen varias categorías adicionales que cubren diferentes operaciones: billeteras, transacciones, token lookup y firma de transacciones [4:40]. Cada categoría incluye endpoints con documentación detallada para integrarlos en tu aplicación.
Si quieres ver cómo estos endpoints se implementan en un entorno de desarrollo real con Next.js, comparte tu experiencia y dudas sobre el flujo que acabamos de recorrer.
