@qubic.org/wallet

High-level wallet for building and signing transactions, plus AES-256-GCM encrypted seed vault management.

A Wallet holds a single seed and exposes methods to build, sign, and encode transactions in one call. It abstracts the buildTransaction → signTransaction → encodeTransaction pipeline from @qubic.org/tx.

import { createWallet, generateSeed } from "@qubic.org/wallet"

const wallet = createWallet(generateSeed())
wallet.identity   // the Identity derived from the seed
wallet.publicKey  // the 32-byte public key

Vault

A Vault stores multiple labeled seeds, encrypted with a user password using AES-256-GCM + PBKDF2. Seeds never leave the vault in plain form — you export only the encrypted blob and decrypt at runtime with the password.

const vault = await createVault("my-password")
await vault.addSeed("main", seed)
const walletFromVault = createWalletFromVault(vault, "main")

When to use this vs `@qubic.org/tx`

@qubic.org/wallet is the right choice for applications — it handles the full transaction lifecycle and key management. Use @qubic.org/tx directly only if you need raw binary control, custom signing flows, or hardware wallet integration.

Installation

bun add @qubic.org/wallet

npm install @qubic.org/wallet

pnpm add @qubic.org/wallet

API reference

Page	What's covered
Transfers	`createWallet`, `generateSeed`, `buildTransfer`, `buildScTransaction`
Vault	`createVault`, `exportVault`, `importVault`, `unlockVault`, `createWalletFromVault`, `addSeedToVault`

All exports

import {
  // Wallet
  createWallet,
  generateSeed,

  // Vault
  createVault,
  exportVault,
  importVault,
  unlockVault,
  addSeedToVault,
  createWalletFromVault,
} from "@qubic.org/wallet"

Examples

Send a QU transfer

import { createWallet, generateSeed } from "@qubic.org/wallet"
import { createLiveClient } from "@qubic.org/rpc"
import { toIdentity } from "@qubic.org/types"

const live   = createLiveClient()
const wallet = createWallet(generateSeed())
const { tick } = await live.getTickInfo()

const { encoded, hash } = await wallet.buildTransfer({
  destination: toIdentity("CFBMEMZOIDEXQAUXYYSZIURADQLAPWPMNJXQSNVQZAHYVOPYUKKJBJUCTVJL"),
  amount: 1_000_000n,
  targetTick: tick + 5,
  currentTick: tick,
})

const result = await live.broadcastTransaction(encoded)
console.log(`TX ${hash} broadcast to ${result.peersBroadcastedTo} peers`)

Store seeds in an encrypted vault

import { createVault, addSeedToVault, exportVault, importVault, createWalletFromVault } from "@qubic.org/wallet"
import { createWallet, generateSeed } from "@qubic.org/wallet"

// Create and populate a vault
const vault = await createVault("my-strong-password")
const seed  = generateSeed()
await addSeedToVault(vault, "trading", seed)

// Export to a portable encrypted blob (store in localStorage, file, etc.)
const blob = await exportVault(vault)

// Later: restore and use
const restored = await importVault(blob, "my-strong-password")
const wallet   = createWalletFromVault(restored, "trading")
console.log("Wallet identity:", wallet.identity)

Call a smart contract

import { createWallet, generateSeed } from "@qubic.org/wallet"
import { qearn } from "@qubic.org/contracts"
import { createLiveClient } from "@qubic.org/rpc"
import { toIdentity } from "@qubic.org/types"

const live   = createLiveClient()
const wallet = createWallet(generateSeed())
const { tick } = await live.getTickInfo()

const payload     = qearn.buildLockInput({ amount: 10_000_000n })
const destination = toIdentity("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA")

const { encoded, hash } = await wallet.buildScTransaction({
  destination,
  amount: 10_000_000n,
  targetTick: tick + 5,
  currentTick: tick,
  inputType: qearn.LOCK_INPUT_TYPE,
  payload,
})

await live.broadcastTransaction(encoded)
console.log("SC TX hash:", hash)