Wallets API 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, so 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. Send the number, not the name: "key_type": "secp256k1" (or the string "0") is rejected with 400 invalid request body
• 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, so 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);

---

Generate Mnemonic from Entropy

Generates a BIP-39 mnemonic phrase from a given entropy strength. Use this to produce a recovery phrase before calling /from-mnemonic to derive the actual wallet.

Request

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

Headers

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

Body

• entropy (required) — Bit strength of the mnemonic. Options: 128, 160, 192, 224, 256. Use 256 for 24-word phrases.

Response

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

cURL

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

TypeScript

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

---

Restore Wallet from Mnemonic

Derives a wallet from an existing BIP-39 mnemonic phrase. Use this to recover a wallet or import one generated externally. Set save_to_storage: trueto persist it in TMS storage.

Request

POST /api/v1/wallets/from-mnemonic

Headers

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

Body

• mnemonic (required) — The BIP-39 recovery phrase
• key_type (optional) — Cryptographic algorithm: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377. Send the number, not the name: "key_type": "secp256k1" (or the string "0") is rejected with 400 invalid request body
• passphrase (optional) — Encrypts the stored wallet
• save_to_storage (optional) — Whether to persist the wallet. Defaults to false.
• output (optional) — What to return: 0 = address only, 1 = address + mnemonic, 2 = full wallet JSON

Response

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

cURL

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

TypeScript

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

---

Restore Wallet from Key Hex

Imports a wallet from a raw public/private key pair in hexadecimal format. Useful when migrating keys from external systems or hardware wallets.

Request

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

Headers

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

Body

• public_key_hex (required) — The public key in hex
• private_key_hex (required) — The private key in hex
• key_type (optional) — Cryptographic algorithm: 0 = secp256k1, 1 = mldsa87, 2 = ed25519, 3 = bls12377. Send the number, not the name: "key_type": "secp256k1" (or the string "0") is rejected with 400 invalid request body
• save_to_storage (optional) — Whether to persist the wallet. Defaults to false.
• output (optional) — What to return: 0 = address only, 1 = address + mnemonic, 2 = full wallet JSON

Response

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

cURL

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

TypeScript

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

---

Get Wallet Status

Returns connectivity and network status for the wallets service, covering which networks are reachable and whether storage is available. Useful for health-checking the TMS before submitting transactions.

Request

GET /api/v1/wallets/status

Headers

• X-AccessKey — Your entity access key

Response

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

cURL

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

TypeScript

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