Wallets Reference

Create Wallet

Generates a new wallet and optionally saves it to storage. When saving to storage, your access key must carry a network tag — pass X-Tag: mainnet or X-Tag: testnet in the request headers.

Request

POST /api/v1/wallets

Headers

• X-AccessKey — Your entity access key
• X-Tag — Network tag: mainnet or testnet (required when save_to_storage is true)
• Content-Type: application/json

Body

• entropy — Bit strength of the generated key. Options: 128, 160, 192, 224, 256. Use 256.
• key_type — Cryptographic algorithm: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377
• output — What to return: 0 = address only, 1 = address + mnemonic, 2 = full wallet JSON (unsafe)
• passphrase (optional) — Encrypts the stored wallet. You'll need this passphrase for every future operation with this wallet.
• save_to_storage — Whether to persist the wallet. Requires a network tag header.
• parent (optional) — Parent wallet address for hierarchical wallets
• auth_groups (optional) — Permission groups assigned to this wallet. Each group is a map of create, read, update, delete booleans.

Response

Returns the wallet address and mnemonic (depending on output value).

Example response

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

Auth groups

Auth groups let you define what different roles can do with this wallet. The group name is up to you — name them whatever makes sense for your use case.

{

"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

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 }
}
}'

TypeScript

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);

---

Load Wallet by Address

Loads a stored wallet from storage using its address. The wallet must have been previously created with save_to_storage: true.

Request

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

Headers

• X-AccessKey — Your entity access key

Body

• address (required) — The wallet address to load
• output — What to return: 0 = address only, 1 = address + mnemonic, 2 = full wallet JSON
• passphrase (optional) — Required if the wallet was created with a passphrase

Response

Returns the wallet based on the requested output format.

Example response (output: 2)

{

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

cURL

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"
}'

TypeScript

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);