RGB wallet API reference

Public API reference for the released @utexo/wdk-wallet-rgb 2.0.3 community module.

This page covers the public declarations and runtime methods in @utexo/wdk-wallet-rgb@2.0.3.

Community modules are developed and maintained independently by third-party contributors.

Tether and the WDK Team do not endorse or assume responsibility for their code, security, or maintenance. Use your own judgment and proceed at your own risk.

Package

Field	Value
Package	`@utexo/wdk-wallet-rgb@2.0.3`
Repository	UTEXO-Protocol/wdk-wallet-rgb
Module format	ESM
Entries	`index.js`; conditional Bare entry `bare.js`
Declarations	`types/index.d.ts`

Exports

Export	Description
`default`	`WalletManagerRgb`
`WalletAccountRgb`	Full account class
`WalletAccountReadOnlyRgb`	Query-only account class
Types	`RgbWalletConfig`, `RgbTransaction`, `TransferOptions`, `RgbTransactionReceipt`, `RgbTransferReceipt`, and WDK fee/key/result aliases

`RgbWalletConfig`

Field	Runtime requirement	Description
`network`	Required	`'mainnet'`, `'testnet'`, or `'regtest'`.
`dataDir`	Optional at construction	Local RGB state path. Treat it as operationally required and persistent.
`indexerUrl`	Optional	Electrs-compatible indexer endpoint.
`transportEndpoint`	Optional	RGB consignment transport endpoint.
`keys`	Internal	Generated by `WalletManagerRgb`; applications normally do not set it.
`transferMaxFee`	Not effective through the manager path	Declared on the config/account, but `WalletManagerRgb.getAccount()` does not forward it to the account in v2.0.3. Enforce a fee limit in application code after quoting.

The generated RgbWalletConfig TypeScript alias exposes only network and keys, although the released runtime and JSDoc accept dataDir, indexerUrl, transportEndpoint, and transferMaxFee. JavaScript can pass the operational fields; TypeScript consumers may need a local, release-scoped augmentation until the package declarations are corrected.

`WalletManagerRgb`

Member	Returns	Behavior
`constructor(seed, config)`	`WalletManagerRgb`	Accepts a BIP-39 mnemonic string or seed bytes. Runtime requires `config.network`.
`getAccount(index = 0)`	`Promise<WalletAccountRgb>`	Creates or returns the only account. Any nonzero index throws.
`restoreAccountFromBackup(config)`	`Promise<WalletAccountRgb>`	Restores the backup into `config.dataDir`, creates the account, and caches it at index `0`.
`getAccountByPath(path)`	`Promise<never>`	Always throws; arbitrary paths are unsupported.
`getFeeRates()`	`Promise<{normal: bigint, fast: bigint}>`	Reads mempool.space recommended fees without selecting the wallet network.
`dispose()`	`void`	Clears manager-owned derived-key fields and disposes cached accounts.

`WalletAccountRgb`

Static factories

Member	Returns	Notes
`WalletAccountRgb.at(seed, config)`	`Promise<WalletAccountRgb>`	Low-level factory used by `WalletManagerRgb.getAccount()`. It requires `config.network` and generated `config.keys`, and accepts `dataDir`, `indexerUrl`, and `transportEndpoint`. Applications should normally use `manager.getAccount(0)` so the manager derives the keys and caches the account.
`WalletAccountRgb.fromBackup(seed, config)`	`Promise<WalletAccountRgb>`	Low-level restore factory used by `WalletManagerRgb.restoreAccountFromBackup()`. It requires `config.network`, generated `config.keys`, `backupFilePath`, `password`, and `dataDir`; it restores before opening the account. Prefer the manager method so keys are derived and the restored account is cached at index `0`.

Both declarations make config optional, but the v2.0.3 runtime throws when these required fields are absent.

Identity and WDK methods

Member	Returns	Notes
`index`	`0`	The only supported account index.
`path`	`string`	`m/86'/0'/0'` on mainnet; `m/86'/1'/0'` otherwise.
`coloredPath`	`string`	`m/86'/827166'/0'` on mainnet; `m/86'/827167'/0'` otherwise.
`keyPair`	`RgbKeyPair`	Includes WDK key bytes plus RGB xpubs and fingerprint. Treat every returned key field as sensitive.
`getAddress()`	`string`	Returns the current Bitcoin address synchronously.
`getBalance()`	`Promise<bigint>`	Settled Bitcoin balance in satoshis.
`getTokenBalance(assetId)`	`Promise<bigint>`	Settled RGB amount in the asset's base unit.
`sign(message)`	`Promise<string>`	Signs through the underlying RGB wallet.
`verify(message, signature)`	`Promise<boolean>`	Full-account verification.
`sendTransaction(tx)`	`Promise<{hash, fee}>`	Sends Bitcoin with `sendBtcBegin → signPsbt → sendBtcEnd`.
`quoteSendTransaction(tx)`	`Promise<{fee}>`	Builds and signs a PSBT to estimate the fee.
`transfer(options)`	`Promise<{hash, fee}>`	Sends an RGB asset to an `rgb:` invoice.
`quoteTransfer(options)`	`Promise<{fee}>`	Builds and signs an RGB PSBT to estimate the fee.
`getTransfers(options?)`	`RgbTransfer[]`	Filters and paginates; returns `[]` for both no results and any underlying error.
`toReadOnlyAccount()`	`Promise<WalletAccountReadOnlyRgb>` in the declarations	The v2.0.3 runtime returns synchronously, but `await` works with both behaviors and satisfies the published type.
`dispose()`	`void`	Zeroes the wrapper's derived private-key bytes and disposes its RGB wallet.

RGB, UTXO, and state methods

Method	Returns	Notes
`getRgbWallet()`	RGB SDK `WalletManager`	Advanced escape hatch; its API and lifecycle are maintained by `@utexo/rgb-sdk`.
`listAssets()`	`ListAssets[]`	Current asset inventory.
`issueAssetNia({ticker, name, amounts, precision})`	`IssueAssetNIA`	Issues a Non-Inflatable Asset. Other issuance schemas are not declared by this release.
`receiveAsset({assetId?, amount, witness})`	`InvoiceReceiveData`	Creates a witness invoice when `witness` is true, otherwise a blind invoice.
`sendBegin(options)`	`string`	Creates a base64 PSBT for an RGB send.
`signPsbt(psbt)`	`Promise<string>`	Signs a base64 PSBT.
`sendEnd({signedPsbt})`	`SendResult`	Finalizes and broadcasts the RGB send.
`createUtxos(options)`	`Promise<number>`	Combined create/sign/finalize flow.
`createUtxosBegin(options)`	`string`	Creates a UTXO-creation PSBT.
`createUtxosEnd({signedPsbt})`	`number`	Finalizes UTXO creation.
`listUnspents()`	`Unspent[]`	Current RGB wallet UTXOs.
`listTransactions()`	`RgbTransactionReceipt[]`	Bitcoin transaction records.
`listTransfers(assetId?)`	`RgbTransfer[]`	Native transfer list with optional asset filter.
`failTransfers(request)`	`boolean`	Forwards transfer-failure handling to the RGB SDK. The v2.0.3 declaration and JSDoc disagree on the parameter name/type; inspect the matching SDK before calling it.
`createBackup({password, backupPath})`	Backup response	Creates an encrypted backup file.
`restoreFromBackup({password, backupFilePath, dataDir})`	Restore response	Low-level account restore. Prefer the manager restore flow before opening the destination.
`refreshWallet()`	`void`	Refreshes RGB transfer state.
`registerWallet()`	`Promise<{address, btcBalance}>`	Registers the wallet and returns its address and Bitcoin balance.
`syncWallet()`	`void`	Synchronizes with the Bitcoin chain.

Version 2.0.3 has a declaration/runtime mismatch for sendEnd(): the published declaration requires signed_psbt, while the runtime reads signedPsbt. Pass the runtime-correct camel-case field and use a narrow type assertion until the upstream declaration is corrected:

const request = { signedPsbt } as unknown as Parameters<typeof account.sendEnd>[0]
const result = account.sendEnd(request)

`WalletAccountReadOnlyRgb`

The read-only class is constructed from an address and configuration. It inherits balance methods and exposes:

Method	Returns	Behavior
`getBalance()`	`Promise<bigint>`	Settled Bitcoin balance.
`getTokenBalance(assetId)`	`Promise<bigint>`	Settled RGB balance.
`getTransactionReceipt(hash)`	`Promise<RgbTransactionReceipt \| null>`	Bitcoin receipt or `null`.
`getTransferReceipt(hash)`	`Promise<RgbTransferReceipt \| null>`	RGB transfer receipt or `null`.
`quoteSendTransaction()`	Rejected promise	Read-only accounts cannot construct or sign a quote PSBT.
`quoteTransfer()`	Rejected promise	Read-only accounts cannot construct or sign a quote PSBT.

The v2.0.3 read-only class does not implement verify(). Use a live full account or a separately validated public-key verification path.

Input shapes

Bitcoin transaction

Field	Required	Meaning
`to`	Yes	Bitcoin address.
`value`	Yes	Satoshis as `number` or `bigint`.
`feeRate`	No	sat/vbyte; send defaults to `1`, while quote obtains an estimate.

RGB transfer

Field	Required	Meaning
`recipient`	Yes	Single-use RGB invoice beginning with `rgb:`.
`token`	Yes	RGB asset ID.
`amount`	Yes	Asset base units as `number` or `bigint`.
`feeRate`	No	Bitcoin fee rate in sat/vbyte.
`minConfirmations`	No	Minimum confirmations.
`witnessData`	No	Optional `{amountSat, blinding}` witness data.

Release-specific cautions

getTransfers() suppresses native errors and returns []; use direct state checks when an empty result is consequential.
sendTransaction() wraps Bitcoin-send failures with the text RGB transfer failed, so the prefix does not identify the failed operation.
Quote methods construct and sign PSBTs. Treat them as wallet operations, not pure arithmetic.
getFeeRates() reads main mempool.space recommendations without choosing testnet or regtest.
transferMaxFee is dropped by the normal manager-to-account construction path. Quote and enforce your own limit before sending.
Preserve and back up dataDir; do not assume the mnemonic alone reconstructs RGB state.