Referencia de Wallets

Crear Wallet

Genera una nueva wallet y opcionalmente la guarda en almacenamiento. Al guardar en almacenamiento, su access key debe llevar un network tag — pase X-Tag: mainnet o X-Tag: testnet en los encabezados de la solicitud.

Solicitud

POST /api/v1/wallets

Encabezados

X-AccessKey — Su 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. Use 256.
key_type — Algoritmo criptográfico: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377
output — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = wallet JSON completo (inseguro)
passphrase (opcional) — Encripta la wallet almacenada. Necesitará esta passphrase para cada operación futura con esta wallet.
save_to_storage — Si se debe persistir la wallet. Requiere un encabezado de network tag.
parent (opcional) — Dirección de la wallet padre para wallets jerárquicas
auth_groups (opcional) — Grupos de permisos asignados a esta wallet. Cada grupo es un mapa de booleanos create, read, update, delete.

Respuesta

Retorna la address de la wallet 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 le permiten definir qué pueden hacer los diferentes roles con esta wallet. El nombre del grupo depende de usted — nómbrelos como tenga sentido para su 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 Wallet por Address

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

Solicitud

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

Encabezados

X-AccessKey — Su entity access key

Cuerpo

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

Respuesta

Retorna la wallet 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. Usa esto para producir una frase de recuperación antes de llamar a /from-mnemonic para derivar el wallet real.

Solicitud

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

Encabezados

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

Cuerpo

entropy (requerido) — Fortaleza en bits del mnemonic. Opciones: 128, 160, 192, 224, 256. Use 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 Wallet desde Mnemonic

Deriva un wallet a partir de una frase mnemónica BIP-39 existente. Usa esto para recuperar un wallet o importar uno generado externamente. Establece save_to_storage: truepara persistirlo en el almacenamiento del TMS.

Solicitud

POST /api/v1/wallets/from-mnemonic

Encabezados

X-AccessKey — Su 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
passphrase (opcional) — Cifra el wallet almacenado
save_to_storage (opcional) — Si se debe persistir el wallet. Por defecto false.
output (opcional) — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = wallet JSON completo

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 Wallet desde Clave Hex

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

Solicitud

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

Encabezados

X-AccessKey — Su 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
save_to_storage (opcional) — Si se debe persistir el wallet. Por defecto false.
output (opcional) — Qué retornar: 0 = solo address, 1 = address + mnemonic, 2 = wallet JSON completo

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 Wallets

Devuelve el estado de conectividad y red del servicio de wallets — 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 — Su 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 Wallet​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta

Auth groups

Cargar Wallet por Address​

Solicitud

Encabezados

Cuerpo

Respuesta

Ejemplo de respuesta (output: 2)

Generar Mnemonic desde Entropía​

Solicitud

Encabezados

Cuerpo

Respuesta

Restaurar Wallet desde Mnemonic​

Solicitud

Encabezados

Cuerpo

Respuesta

Restaurar Wallet desde Clave Hex​

Solicitud

Encabezados

Cuerpo

Respuesta

Obtener Estado del Servicio de Wallets​

Solicitud

Encabezados

Respuesta

Crear Wallet

Cargar Wallet por Address

Ejemplo de respuesta `(output: 2)`

Generar Mnemonic desde Entropía

Restaurar Wallet desde Mnemonic

Restaurar Wallet desde Clave Hex

Obtener Estado del Servicio de Wallets