Superficie de la API
La referencia que necesitas, sin perder de vista el sistema.
Todo cuelga del prefijo /api. La apiBaseUrl del SDK termina en /api, no en la raíz.
Autenticación — x-api-key#
| Método | Ruta | Para qué |
|---|---|---|
POST | /auth/send-otp | Envía un código de un solo uso al correo del usuario |
POST | /auth/login | Inicia sesión con correo y código; devuelve el JWT |
POST | /auth/totp-login | Inicia sesión con un código TOTP |
GET | /auth/google | Arranca el flujo de Google OAuth |
POST | /auth/refresh-token | Renueva el JWT |
GET | /auth/check-auth-status | Consulta el estado de autenticación |
Passkeys — WebAuthn#
| Método | Ruta | Para qué |
|---|---|---|
POST | /webauthn/register/options | Opciones de registro de una passkey |
POST | /webauthn/register/verify | Verifica y persiste el registro |
POST | /webauthn/authenticate/options | Opciones de autenticación |
POST | /webauthn/authenticate/verify | Verifica la aserción |
Custodia — JWT del usuario#
| Método | Ruta | Para qué |
|---|---|---|
POST | /custody/wallets | Registra una wallet generada en el cliente, con su fragmento de servidor y su sobre. Atómico. |
GET | /custody/wallets/{walletId}/share | Entrega al dueño el fragmento que custodia el servidor |
GET | /custody/wallets/{walletId}/recovery-envelope | Entrega al dueño su sobre de recuperación |
POST | /custody/wallets/{walletId}/recovery-envelope | Rota el sobre de una wallet que ya tiene uno |
POST | /custody/wallets/{walletId}/reshare | Reemplaza atómicamente fragmento y sobre tras una recuperación |
El cuerpo del alta muestra el modelo entero de un vistazo:
POST /api/custody/wallets
{
"name": "Cuenta principal",
"blockchainType": "polygon",
"networkType": "testnet",
"address": "0x…",
"serverShare": "<base64 del fragmento B>",
"envelopeCiphertext": "<base64 del sobre, cifrado en el navegador>",
"envelopeFormat": "webauthn-prf-v1"
}Eso es todo lo que Nyx llega a ver de una llave: un fragmento y un sobre cerrado.
La ruta de rotación del sobre responde 409 sobre una wallet que todavía no tiene ninguno. No sirve para darle el primero: eso es trabajo del alta, y es deliberado. Que el servidor aceptara registrar una wallet sin sobre era el fallo.
Cuenta inteligente — JWT del usuario#
| Método | Ruta | Para qué |
|---|---|---|
POST | /account/address | Calcula la dirección de una cuenta antes de desplegarla |
POST | /account/operations/sponsorship | Pide que Nyx patrocine el gas, antes de firmar |
POST | /account/operations | Retransmite al bundler una operación ya firmada |
GET | /account/operations/{userOpHash}/receipt | Consulta el recibo sin exponer el bundler |
POST /account/operations rechaza cualquier operación sin firma. No es validación cosmética: deja escrito en el código que por ahí no pasa nada que Nyx pudiera haber autorizado.
Guardianes#
| Método | Ruta | Para qué |
|---|---|---|
POST | /account/guardians | Fija o reemplaza el roster |
GET | /account/guardians | Lee el roster |
POST | /account/guardians/recovery | Un guardián propone un firmante nuevo |
GET | /account/guardians/recovery/{recoveryId} | Estado: votos, plazo, veto |
POST | /account/guardians/recovery/{recoveryId}/vote | Un guardián se suma |
POST | /account/guardians/recovery/{recoveryId}/veto | El firmante actual cancela |
Salud#
| Método | Ruta | Para qué |
|---|---|---|
GET | /health | Vivacidad del proceso |
GET | /health/readiness | Si esta instancia puede operar de verdad |
readiness comprueba las dependencias reales del camino de escritura: base de datos, caché, cliente de cifrado, configuración de la cuenta inteligente, nodo y bundler. No responde "listo" si el camino de escritura más importante está muerto. Compruébalo desde tu entorno antes de crear la primera wallet.
Lo que la API no tiene, a propósito#
- Ninguna ruta devuelve una llave privada ni una frase de recuperación.
- Ninguna ruta firma en nombre del usuario.
- El bundler nunca se expone al navegador.