Cosmos wallet API reference

This reference covers the public package surface published in @base58-io/wdk-wallet-cosmos@1.0.0-beta.4.

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.

Repository main contains APIs that are not part of this release. Use the v1.0.0-beta.4 source tag when comparing this reference with code.

Package

Field	Value
Package	`@base58-io/wdk-wallet-cosmos`
Version	`1.0.0-beta.4`
Module format	ESM
Default entry	`index.js`
Bare conditional entry	`bare.js`
Type declarations	`types/index.d.ts`
Runtime engines	Not declared in `package.json`
Peer dependencies	None
WDK wallet dependency	`@tetherto/wdk-wallet@1.0.0-beta.8`

The package export map exposes the root module and a ./package subpath for package.json. Internal files are not supported public entrypoints.

Root exports

Export	Kind	Description
`default`	Runtime	`WalletManagerCosmos`
`WalletAccountCosmos`	Runtime	Seed-backed Cosmos account implementation
`resolveChainConfig(config)`	Runtime	Resolves registry or custom chain configuration
`getAvailableChains()`	Runtime	Returns bundled registry names whose chain type is `cosmos`
`isKnownChain(chainName)`	Runtime	Checks whether a name exists in the bundled registry
`FeeRates`	Type only	Normal and fast fee amounts
`KeyPair`	Type only	Public key and sensitive private-key fields
`TransactionResult`	Type only	Transaction hash and fee
`TransferOptions`	Type only	Denomination, recipient, and amount
`TransferResult`	Type only	Transfer hash and fee
`CosmosWalletConfig`	Type only	Input wallet configuration
`ResolvedChainConfig`	Type only	Resolved chain configuration

`WalletManagerCosmos`

Constructor

new WalletManagerCosmos(seed, config?)

Parameter	Type	Required	Description
`seed`	`string \| Uint8Array`	Yes	BIP-39 mnemonic or seed bytes
`config`	`CosmosWalletConfig`	No	Chain, RPC, fee, retry, and IBC configuration

The released constructor does not accept an external signer. Named signer overloads visible on repository main are not published in 1.0.0-beta.4.

Inherited static methods

Method	Returns	Description
`WalletManagerCosmos.getRandomSeedPhrase(wordCount = 12)`	`string`	Generates a 12- or 24-word BIP-39 mnemonic
`WalletManagerCosmos.isValidSeedPhrase(seedPhrase)`	`boolean`	Validates a BIP-39 mnemonic

Methods

Method	Returns	Behavior
`getAccount(index = 0)`	`Promise<WalletAccountCosmos>`	Derives and caches `0'/0/{index}` below the chain coin type
`getAccountByPath(path)`	`Promise<WalletAccountCosmos>`	Derives and caches a relative suffix such as `0'/0/5`
`getFeeRates()`	`Promise<FeeRates>`	Calculates normal and fast amounts for the fixed gas limit
`dispose()`	`void`	Disposes cached accounts, zeros the manager seed bytes, and marks the manager unusable

Properties

Property	Type	Description
`seed`	`Uint8Array`	Inherited sensitive seed bytes; do not log or retain
`isDisposed`	`boolean`	Whether `dispose()` has been called

getAccount() caches by relative derivation path. Disposing a cached account directly does not evict it from the manager; prefer disposing the manager at the end of its lifecycle.

`getFeeRates()`

const { normal, fast } = await manager.getFeeRates()

The returned values are deterministic fee amounts in the selected fee denomination:

registry configuration uses average and high gas-price tiers;
explicit gas-price configuration returns the same amount for both priorities;
final fallback uses 0.025 and 0.04;
all calculations use a gas limit of 200000.

The method requires at least one configured RPC endpoint but does not make an RPC request.

`WalletAccountCosmos`

Create accounts through WalletManagerCosmos. The exported static factory is also public:

const account = await WalletAccountCosmos.create(seed, "0'/0/0", config)

Do not call the class constructor directly. Its parameters are implementation details.

Account methods

Method	Returns	Behavior
`getAddress()`	`Promise<string>`	Returns the locally derived Bech32 address
`getBalance(denom?)`	`Promise<bigint>`	Reads one denomination; defaults to `nativeDenom`
`getTokenBalance(denom)`	`Promise<bigint>`	Alias behavior for a denomination-specific balance
`getTokenBalances(denoms)`	`Promise<Record<string, bigint>>`	Reads all balances and returns requested denominations that are present
`quoteTransfer(options)`	`Promise<{ fee: bigint }>`	Calculates a fixed-gas transfer fee without broadcasting
`transfer(options)`	`Promise<TransferResult>`	Sends a bank transfer or configured IBC transfer
`sign(message)`	`Promise<string>`	Returns a JSON-encoded ADR-36 `StdSignature`
`verify(message, signature)`	`Promise<boolean>`	Verifies ADR-36 data against this account
`signTransaction(transaction)`	`Promise<unknown>`	Returns a CosmJS signed `TxRaw` without broadcasting
`quoteSendTransaction(transaction)`	`Promise<{ fee: bigint }>`	Calculates a fixed-gas native-send fee
`sendTransaction(transaction)`	`Promise<TransactionResult>`	Signs and broadcasts a native bank send
`getTransactionReceipt(hash)`	`Promise<object>`	Returns the indexed transaction or throws when it is not found
`toReadOnlyAccount()`	Never succeeds	Throws because read-only accounts are not implemented
`dispose()`	`void`	Zeros the module-owned private-key buffer and marks the account unusable

Account properties

Property	Type	Description
`index`	`number`	Last component of the full derivation path
`path`	`string`	Full path such as `m/44'/118'/0'/0/0`
`keyPair`	`KeyPair`	Public key and the underlying sensitive private-key buffer
`isDisposed`	`boolean`	Whether `dispose()` has been called

keyPair.privateKey exposes the account's underlying private-key bytes. Avoid using this property unless an integration requires it. Never log, serialize, or retain the value, and do not assume dispose() can erase copies held elsewhere.

Balance behavior

getBalance(), getTokenBalance(), and getTokenBalances() require RPC endpoints. Values are returned in base units.

getTokenBalances(denoms) calls the RPC all-balances query and filters it. A requested denomination with no returned balance is omitted rather than included with 0n.

Message signing

sign(message) signs UTF-8 text with ADR-36 and returns a JSON string containing the public key and base64 signature. verify():

binds the signature public key to this account's Bech32 address;
returns false for a different message or account;
returns false, rather than throwing, for malformed signature input.

Transaction input

signTransaction(), quoteSendTransaction(), and sendTransaction() consume the shared WDK transaction shape:

type Transaction = {
  to: string
  value: number | bigint
}

The account converts this input to one /cosmos.bank.v1beta1.MsgSend:

denomination is always the configured nativeDenom;
amount is value converted to a string;
memo is fixed to Transfer via WDK;
gas is fixed at 200000.

signTransaction() needs RPC to obtain signing context and returns a signed CosmJS TxRaw. Its generated beta declaration types the result as unknown.

sendTransaction() in 1.0.0-beta.4 accepts only the unsigned WDK transaction shape. It does not accept or broadcast the signed value returned by signTransaction().

quoteSendTransaction() ignores the transaction contents after receiving them. It checks for configured endpoints, calculates the fixed-gas fee, and applies transferMaxFee; it does not simulate or validate the transaction through RPC.

Transfer input

type TransferOptions = {
  token: string
  recipient: string
  amount: number | bigint
}

Field	Meaning
`token`	Cosmos denomination such as `uatom` or an IBC denomination
`recipient`	Destination Bech32 address
`amount`	Integer amount in base units

For matching Bech32 prefixes, transfer() calls a bank send. For a different prefix, it selects ibcChannels[recipientPrefix] and broadcasts IBC MsgTransfer with a fixed 600-second timestamp timeout.

transfer() checks transferMaxFee only after the bank or IBC operation has been signed and broadcast. A transfer can succeed on-chain and then throw the fee-limit error. Call quoteTransfer(), enforce an application limit, and validate the operation before transfer().

quoteTransfer() checks that an IBC channel mapping exists for a different prefix. It does not query RPC, simulate gas, validate the sender balance, or prove that the channel is active.

Transaction receipts

getTransactionReceipt(hash) performs one StargateClient.getTx() lookup. It returns the raw indexed transaction object when found. When the transaction is not yet indexed or does not exist, it throws:

Transaction not found: <hash>

The method does not poll.

`CosmosWalletConfig`

Field	Type	Required	Resolved behavior
`chainName`	`string`	No	Selects bundled registry metadata; unknown names throw
`rpcEndpoints`	`string[]`	No	Replaces registry endpoints when non-empty
`retryCount`	`number`	No	Defaults to `3` retry rounds
`retryDelay`	`number`	No	Defaults to `150` milliseconds
`addressPrefix`	`string`	No	Registry prefix or `cosmos`
`nativeDenom`	`string`	No	First registry fee denomination or `uatom`
`coinType`	`number`	No	Registry SLIP-44 value or `118`
`gasPrice`	`string`	No	Compact amount and denomination such as `0.025uatom`
`transferMaxFee`	`number \| bigint`	No	Quote limit and post-broadcast `transfer()` check
`ibcChannels`	`Record<string, { sourceChannel: string }>`	No	IBC source channels keyed by destination prefix

See Configuration for precedence and safety details.

`ResolvedChainConfig`

resolveChainConfig() returns:

Field	Type
`rpcEndpoints`	`string[]`
`retryCount`	`number`
`retryDelay`	`number`
`addressPrefix`	`string`
`nativeDenom`	`string`
`coinType`	`number`
`gasPrice`	`string \| undefined`
`gasPriceStep`	`{ low: number, average: number, high: number, denom: string } \| undefined`
`transferMaxFee`	`number \| bigint \| undefined`
`chainId`	`string \| undefined`
`prettyName`	`string \| undefined`
`ibcChannels`	`Record<string, { sourceChannel: string }> \| undefined`

Invalid mnemonic and derivation paths reject account creation.
RPC-backed methods throw when the endpoint list is empty.
Most Cosmos ABCI, JSON-RPC validation, funds, gas, sequence, and signing errors are not retried.
Network-shaped errors can fall back or retry. A write error can therefore have an ambiguous on-chain outcome.
Every account operation except toReadOnlyAccount() checks disposal state; the read-only method always throws its unsupported error.
dispose() makes manager and account methods unusable, but it cannot revoke seed or key copies held by application code.

See Handle errors for safe write and recovery guidance.