Ecency wallets

Use @ecency/wallets for Hive, Hive Engine, Points and external chain asset queries, MetaMask transfers and Hive key derivation.

The @ecency/wallets package (currently 6.x) is the wallet layer of the Ecency web and mobile apps. It builds on the Ecency SDK and gives you:

Asset queries for Hive (HIVE, HP, HBD), Hive Engine tokens and Ecency Points, re-exported from the SDK.
Token price and token list queries.
External chain balances (BTC, ETH, BNB, SOL) and MetaMask transfers for ETH, BNB and SOL.
MetaMask multichain discovery and Hive Snap helpers.
Hive key derivation from a BIP44 seed or a master password.
Helpers to save linked wallet addresses to the Hive profile.

It is published on npm under the MIT license. The source is in ecency/vision-web under packages/wallets.

Installation

Install it together with the SDK and HiveSigner:

npm install --legacy-peer-deps @ecency/wallets @ecency/sdk hivesigner

Peer dependencies:

Package	Version	Required
`@ecency/sdk`	latest	Yes, install it alongside
`hivesigner`	`^4.0.0`	Yes
`react`	`>=18`	Optional, needed for the hooks
`@tanstack/react-query`	`>=5`	Optional, needed for the query options and hooks
`@solana/web3.js`	`>=1`	Optional, only for SOL transfers
`@wallet-standard/app`	`>=1`	Optional, only for MetaMask multichain discovery and SOL

Configure the SDK first (at least ConfigManager.setQueryClient), as described on the SDK page.

Supported currencies

Currency	Balance query	Transfer via MetaMask	How it signs
BTC	Yes	No
ETH	Yes	Yes	`eth_sendTransaction`
BNB	Yes	Yes	`eth_sendTransaction` with chain switch
SOL	Yes	Yes	Wallet Standard `solana:signAndSendTransaction`

The EcencyWalletCurrency enum has the values BTC, ETH, BNB and SOL. EcencyWalletBasicTokens has POINTS, HP, HIVE and HBD.

Asset queries

These query option builders come from the SDK and are re-exported by @ecency/wallets, so you can import them from either package.

Hive

Function	Returns
`getHiveAssetGeneralInfoQueryOptions(username)`	HIVE balance, savings and price info
`getHbdAssetGeneralInfoQueryOptions(username)`	HBD balance, savings and interest info
`getHivePowerAssetGeneralInfoQueryOptions(username)`	Hive Power, delegations and power down info
`getHiveAssetTransactionsQueryOptions(username, limit?, filters?)`	HIVE history (infinite)
`getHbdAssetTransactionsQueryOptions(...)` / `getHivePowerAssetTransactionsQueryOptions(...)`	HBD and HP history
`getHiveAssetMetricQueryOptions(...)`	HIVE market metrics
`getHiveAssetWithdrawalRoutesQueryOptions(username)`	Power down withdraw routes
`getHivePowerDelegatesInfiniteQueryOptions(...)`	Outgoing HP delegations
`getHivePowerDelegatingsQueryOptions(username)`	Incoming HP delegations
`getAccountWalletAssetInfoQueryOptions(username, asset, { currency? })`	One asset’s info for any asset symbol (HIVE, HP, HBD, POINTS or an engine token)

Hive Engine

getAllHiveEngineTokensQueryOptions, getHiveEngineTokensBalancesQueryOptions(username), getHiveEngineBalancesWithUsdQueryOptions, getHiveEngineTokenGeneralInfoQueryOptions(username, symbol), getHiveEngineTokensMetadataQueryOptions, getHiveEngineTokenTransactionsQueryOptions, getHiveEngineTokensMetricsQueryOptions, getHiveEngineTokensMarketQueryOptions and getHiveEngineUnclaimedRewardsQueryOptions.

Ecency Points

Function	Returns
`getPointsQueryOptions(username, filter?)`	Points balance, unclaimed Points and transactions
`getPointsAssetGeneralInfoQueryOptions(username)`	Points as a wallet asset
`getPointsAssetTransactionsQueryOptions(...)`	Points history

Points mutation: useClaimPoints(username, accessToken, onSuccess?, onError?) claims pending Points.

Wallet operations

useWalletOperation(username, asset, operation, auth?) runs a wallet action for an asset. operation is an AssetOperation value such as Transfer, TransferToSavings, WithdrawFromSavings, Delegate, PowerUp, PowerDown, ClaimInterest, Convert, Gift, Claim, Stake, Unstake or Undelegate.

import { useQuery } from "@tanstack/react-query";
import { getAccountWalletAssetInfoQueryOptions, useWalletOperation, AssetOperation } from "@ecency/wallets";

const { data: hive } = useQuery(getAccountWalletAssetInfoQueryOptions("alice", "HIVE"));

const transfer = useWalletOperation("alice", "HIVE", AssetOperation.Transfer, auth);

Wallet package queries

Function	Returns
`getTokenPriceQueryOptions(currency)`	Latest USD price for a currency (BTC, ETH, SOL, BNB, HBD, HIVE)
`getAllTokensListQueryOptions(username?)`	`{ basic, external, layer2 }`: the basic tokens, external currencies and Hive Engine tokens
`getAccountWalletListQueryOptions(username, currency?)`	The token symbols the user chose to show in their wallet
`getTokenOperationsQueryOptions(token, username, isForOwner?, currency?)`	The `AssetOperation` values available for a token
`useGetExternalWalletBalanceQuery(currency, address)`	Balance of an external address (`balanceString`, `balanceBigInt`, `unit`)

import { useQuery } from "@tanstack/react-query";
import { getTokenPriceQueryOptions, useGetExternalWalletBalanceQuery, EcencyWalletCurrency } from "@ecency/wallets";

const { data: ethUsd } = useQuery(getTokenPriceQueryOptions("ETH"));
const { data: balance } = useGetExternalWalletBalanceQuery(EcencyWalletCurrency.ETH, "0x...");

MetaMask discovery

import { discoverMetaMaskWallets, installHiveSnap, getHivePublicKeys } from "@ecency/wallets";

// Discover ETH, BNB, SOL and BTC addresses from MetaMask
const addresses = await discoverMetaMaskWallets();
// { ETH: "0x...", BNB: "0x...", SOL: "7xyz...", BTC: "bc1..." }

// Install the Hive Snap and read Hive public keys
await installHiveSnap();
const hiveKeys = await getHivePublicKeys();
// [{ publicKey: "STM...", role: "owner", accountIndex: 0, addressIndex: 0 }, ...]

Related helpers: fetchMultichainAddresses() and fetchEvmAddress().

Sending ETH, BNB or SOL

useExternalTransfer(currency) is a mutation that signs with MetaMask. It accepts ETH, BNB or SOL.

import { useExternalTransfer, EcencyWalletCurrency } from "@ecency/wallets";

function SendEthButton({ linkedAddress }: { linkedAddress: string }) {
  const transfer = useExternalTransfer(EcencyWalletCurrency.ETH);

  const handleSend = async () => {
    const result = await transfer.mutateAsync({
      to: "0xRecipientAddress...",
      amount: "0.05",
      expectedFrom: linkedAddress,
    });
    console.log("Tx hash:", result.txHash);
  };

  return <button onClick={handleSend}>Send 0.05 ETH</button>;
}

Payload fields:

Field	Description
`to`	Recipient address
`amount`	Amount as a decimal string
`expectedFrom`	EVM only, optional. The address the user linked. If the active MetaMask account is a different address, the send is blocked so funds never leave the wrong account.

The result is { txHash, currency }. On success, cached external balances are invalidated.

Lower-level helpers: sendEvmTransfer(to, amountWei, currency, expectedFrom?), ensureEvmChain, estimateEvmGas, parseToWei, formatWei, getEvmChainConfig, getEvmExplorerUrl, sendSolTransfer(to, amountSol), parseToLamports, formatLamports and getSolExplorerUrl.

Hive key derivation

import { deriveHiveKeys, deriveHiveMasterPasswordKeys, detectHiveKeyDerivation } from "@ecency/wallets";

// From a BIP44 seed phrase
const keys = deriveHiveKeys(mnemonic); // { owner, active, posting, memo, ownerPubkey, ... }

// From a classic master password
const legacy = deriveHiveMasterPasswordKeys("alice", masterPassword);

// Which scheme matches the account on chain?
const kind = await detectHiveKeyDerivation("alice", seedOrPassword); // "bip44" | "master-password" | "unknown"

Single-role versions are deriveHiveKey(mnemonic, role, accountIndex?) and deriveHiveMasterPasswordKey(username, password, role). See the seed phrase migration guide for what this means for users.

Saving wallet addresses to the profile

useSaveWalletInformationToMetadata(username, auth?, options?) writes linked wallet addresses and the wallet token list to the user’s Hive profile (profile.tokens). Ecency’s apps read the visible wallet tokens from there.