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

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

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

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

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

Get Wallet Status

Returns connectivity and network status for the wallets service — 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
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);

Create Wallet​

Request

Headers

Body

Response

Example response

Auth groups

Load Wallet by Address​

Request

Headers

Body

Response

Example response (output: 2)

Generate Mnemonic from Entropy​

Request

Headers

Body

Response

Restore Wallet from Mnemonic​

Request

Headers

Body

Response

Restore Wallet from Key Hex​

Request

Headers

Body

Response

Get Wallet Status​

Request

Headers

Response

Create Wallet

Load Wallet by Address

Example response `(output: 2)`

Generate Mnemonic from Entropy

Restore Wallet from Mnemonic

Restore Wallet from Key Hex

Get Wallet Status