Referencia de la API de Billeteras

Crear Billetera

Genera una nueva billetera y opcionalmente la guarda en almacenamiento. Al guardar en almacenamiento, la access key debe llevar un network tag, así que se debe pasar X-Tag: mainnet o X-Tag: testnet en los encabezados de la solicitud.

Solicitud

POST /api/v1/wallets

Encabezados

X-AccessKey — La entity access key
X-Tag — Network tag: mainnet o testnet (requerido cuando save_to_storage es true)
Content-Type: application/json

Cuerpo

entropy — Fuerza en bits de la clave generada. Opciones: 128, 160, 192, 224, 256. Se recomienda usar 256.
key_type — Algoritmo criptográfico: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377. Se debe enviar el número, no el nombre: "key_type": "secp256k1" (o la cadena "0") se rechaza con 400 invalid request body
output — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = JSON completo de la billetera (inseguro)
passphrase (opcional) — Encripta la billetera almacenada. Esta passphrase es necesaria para cada operación futura con esta billetera.
save_to_storage — Si se debe persistir la billetera. Requiere un encabezado de network tag.
parent (opcional) — Dirección de la billetera padre para billeteras jerárquicas
auth_groups (opcional) — Grupos de permisos asignados a esta billetera. Cada grupo es un mapa de booleanos create, read, update, delete.

Respuesta

Retorna la address de la billetera y el mnemonic (dependiendo del valor de output).

Ejemplo de respuesta

{
"address": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"mnemonic": "word1 word2 word3 ... word24",
"publicKey": "04FBF905...",
"keyType": "secp256k1",
"enabled": true
}

Auth groups

Los auth groups permiten definir qué pueden hacer los diferentes roles con esta billetera. El nombre del grupo es libre, así que se recomienda nombrarlos como tenga sentido para el caso de uso.

{

"auth_groups": {
"admin": { "create": true, "read": true, "update": true, "delete": true },
"writer": { "create": true, "read": true, "update": false, "delete": false },
"reader": { "create": false, "read": true, "update": false, "delete": false }
}
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/wallets' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'X-Tag: mainnet' \
-H 'Content-Type: application/json' \
-d '{
"entropy": 256,
"key_type": 0,
"output": 1,
"passphrase": "my-secure-passphrase",
"save_to_storage": true,
"auth_groups": {
"admin": { "create": true, "read": true, "update": true, "delete": true },
"writer": { "create": true, "read": true, "update": false, "delete": false },
"reader": { "create": false, "read": true, "update": false, "delete": false }
}
}'

const res = await fetch('https://your-tms-url/api/v1/wallets', {
method: 'POST',
headers: {
'X-AccessKey': 'your-entity-access-key',
'X-Tag': 'mainnet',
'Content-Type': 'application/json',
},
body: JSON.stringify({
entropy: 256,
key_type: 0,
output: 1,
passphrase: 'my-secure-passphrase',
save_to_storage: true,
auth_groups: {
admin: { create: true, read: true, update: true, delete: true },
writer: { create: true, read: true, update: false, delete: false },
reader: { create: false, read: true, update: false, delete: false },
},
}),
});

if (!res.ok) {
throw new Error('Failed to create wallet: ' + res.status);
}

const wallet = await res.json();
console.log('Wallet address:', wallet.address);
console.log('Mnemonic:', wallet.mnemonic);

Cargar Billetera por Address

Carga una billetera almacenada desde el almacenamiento usando su address. La billetera debe haber sido creada previamente con save_to_storage: true.

Solicitud

POST /api/v1/wallets/load-by-address

Encabezados

X-AccessKey — La entity access key

Cuerpo

address (requerido) — La address de la billetera a cargar
output — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = JSON completo de la billetera
passphrase (opcional) — Requerida si la billetera fue creada con una passphrase

Respuesta

Retorna la billetera según el formato de output solicitado.

Ejemplo de respuesta `(output: 2)`

{

"wallet": {
"address": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"publicKey": "04FBF905...",
"keyType": "secp256k1",
"enabled": true,
"authGroups": { ... }
}
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/wallets/load-by-address' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"address": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"output": 2,
"passphrase": "my-secure-passphrase"
}'

const res = await fetch('https://your-tms-url/api/v1/wallets/load-by-address', {
method: 'POST',
headers: {
'X-AccessKey': 'your-entity-access-key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
address: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
output: 2,
passphrase: 'my-secure-passphrase',
}),
});

if (!res.ok) {
throw new Error('Failed to load wallet: ' + res.status);
}

const data = await res.json();
console.log('Wallet:', data.wallet);

Generar Mnemonic desde Entropía

Genera una frase mnemónica BIP-39 a partir de una fortaleza de entropía determinada. Se usa para producir una frase de recuperación antes de llamar a /from-mnemonic para derivar la billetera real.

Solicitud

POST /api/v1/wallets/generate-mnemonic-from-entropy

Encabezados

X-AccessKey — La entity access key
Content-Type: application/json

Cuerpo

entropy (requerido) — Fortaleza en bits del mnemonic. Opciones: 128, 160, 192, 224, 256. Se recomienda usar 256 para frases de 24 palabras.

Respuesta

{
"mnemonic": "word1 word2 word3 ... word24"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/wallets/generate-mnemonic-from-entropy' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{ "entropy": 256 }'

const res = await fetch('https://your-tms-url/api/v1/wallets/generate-mnemonic-from-entropy', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({ entropy: 256 }),
});

const { mnemonic } = await res.json();
console.log('Mnemonic:', mnemonic);

Restaurar Billetera desde Mnemonic

Deriva una billetera a partir de una frase mnemónica BIP-39 existente. Se usa para recuperar una billetera o importar uno generado externamente. Se establece save_to_storage: truepara persistirlo en el almacenamiento del TMS.

Solicitud

POST /api/v1/wallets/from-mnemonic

Encabezados

X-AccessKey — La entity access key
Content-Type: application/json

Cuerpo

mnemonic (requerido) — La frase de recuperación BIP-39
key_type (opcional) — Algoritmo criptográfico: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377. Se debe enviar el número, no el nombre: "key_type": "secp256k1" (o la cadena "0") se rechaza con 400 invalid request body
passphrase (opcional) — Cifra la billetera almacenada
save_to_storage (opcional) — Si se debe persistir la billetera. Por defecto false.
output (opcional) — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = JSON completo de la billetera

Respuesta

{
"address": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"mnemonic": "word1 word2 word3 ... word24",
"publicKey": "04FBF905...",
"keyType": "secp256k1"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/wallets/from-mnemonic' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"mnemonic": "word1 word2 word3 ... word24",
"key_type": 0,
"passphrase": "my-secure-passphrase",
"save_to_storage": true,
"output": 1
}'

const res = await fetch('https://your-tms-url/api/v1/wallets/from-mnemonic', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  mnemonic: 'word1 word2 word3 ... word24',
  key_type: 0,
  passphrase: 'my-secure-passphrase',
  save_to_storage: true,
  output: 1,
}),
});

const wallet = await res.json();
console.log('Wallet address:', wallet.address);

Restaurar Billetera desde Clave Hex

Importa una billetera a partir de un par de claves pública/privada en formato hexadecimal. Útil al migrar claves desde sistemas externos o billeteras de hardware.

Solicitud

POST /api/v1/wallets/from-key-hex

Encabezados

X-AccessKey — La entity access key
Content-Type: application/json

Cuerpo

public_key_hex (requerido) — La clave pública en hex
private_key_hex (requerido) — La clave privada en hex
key_type (opcional) — Algoritmo criptográfico: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377. Se debe enviar el número, no el nombre: "key_type": "secp256k1" (o la cadena "0") se rechaza con 400 invalid request body
save_to_storage (opcional) — Si se debe persistir la billetera. Por defecto false.
output (opcional) — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = JSON completo de la billetera

Respuesta

{
"address": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"publicKey": "04FBF905...",
"keyType": "secp256k1"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/wallets/from-key-hex' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"public_key_hex": "04FBF905...",
"private_key_hex": "a1b2c3d4...",
"key_type": 0,
"save_to_storage": false,
"output": 1
}'

const res = await fetch('https://your-tms-url/api/v1/wallets/from-key-hex', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  public_key_hex: '04FBF905...',
  private_key_hex: 'a1b2c3d4...',
  key_type: 0,
  save_to_storage: false,
  output: 1,
}),
});

const wallet = await res.json();
console.log('Wallet address:', wallet.address);

Obtener Estado del Servicio de Billeteras

Devuelve el estado de conectividad y red del servicio de billeteras, e indica qué redes son accesibles y si el almacenamiento está disponible. Útil para verificar el estado del TMS antes de enviar transacciones.

Solicitud

GET /api/v1/wallets/status

Encabezados

X-AccessKey — La entity access key

Respuesta

{
"networks": {
  "mainnet": "connected",
  "testnet": "connected"
},
"storage": "available"
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/wallets/status' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const res = await fetch('https://your-tms-url/api/v1/wallets/status', {
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Accept': 'application/json',
},
});

const status = await res.json();
console.log('Networks:', status.networks);

Crear Billetera​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta

Auth groups

Cargar Billetera por Address​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta (output: 2)

Generar Mnemonic desde Entropía​

Solicitud

Encabezados

Cuerpo

Respuesta

Restaurar Billetera desde Mnemonic​

Solicitud

Encabezados

Cuerpo

Respuesta

Restaurar Billetera desde Clave Hex​

Solicitud

Encabezados

Cuerpo

Respuesta

Obtener Estado del Servicio de Billeteras​

Solicitud

Encabezados

Respuesta

Crear Billetera

Cargar Billetera por Address

Ejemplo de respuesta `(output: 2)`

Generar Mnemonic desde Entropía

Restaurar Billetera desde Mnemonic

Restaurar Billetera desde Clave Hex

Obtener Estado del Servicio de Billeteras