Skip to main content

Wallets

Everything starts with a wallet. Wallets are how you sign transactions, and without a signature nothing gets written to the chain.

Wallets in ULedger are hierarchical — you can create child wallets from a parent, which is useful when you need to separate concerns within the same organization. A wallet per app, a wallet per user, a wallet per department. The structure is yours to decide.

Creating a wallet​

Call POST /api/v1/wallets with your access key and the network tag. The wallet is generated, optionally encrypted with a passphrase, and stored by the TMS.

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,        // 0 = secp256k1
    output: 1,          // 1 = address + mnemonic
    passphrase: 'my-secure-passphrase',
    save_to_storage: true,
  }),
});

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

Hold onto the mnemonic or wallet address . It's the only way to recover the wallet if you lose it.

If you created the wallet without a passphrase, leave passphrase out entirely. Every future operation with this wallet needs to match.

Loading a wallet​

Retrieve a stored wallet at any time by address:

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: 'your-wallet-address',
    output: 2,                           // 2 = full wallet JSON
    passphrase: 'my-secure-passphrase',  // omit if created without one
  }),
});

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

Auth groups​

When creating a wallet you can assign auth groups — named permission sets that control what different roles can do with it. The names are yours to define.

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 },
  },
}),

Recovering a wallet​

If you need to restore a wallet — whether after a data loss or to import a wallet generated elsewhere — use the mnemonic recovery flow.

First, generate a mnemonic if you don't already have one:

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();
// Store this securely — it's the only way to recover the wallet

Then restore the wallet from that mnemonic at any time:

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('Recovered address:', wallet.address);

If you're migrating keys from an external system and already have a raw key pair in hex, use POST /api/v1/wallets/from-key-hex instead — see the Wallets Reference for details.

Next step​

A wallet on its own can't do anything on the blockchain until it's registered and to do so we need to create our first transaction. Head to Transactions to register your wallet and start writing data.