fetchWalletMetadata

Function Signature

fetchWalletMetadata(accountAddress: string): Promise<WalletMetadata>

Description

Returns wallet identity metadata for an account address. Useful for re-identifying a wallet (chain, derivation path, threshold scheme) when you have only the address — for example in admin tooling or read-only audit flows. This is an identity-only lookup — the returned walletMetadata includes walletId, accountAddress, chainName, derivationPath, and thresholdSignatureScheme, but not externalServerKeySharesBackupInfo. The backup-pointer metadata is not recoverable from the server via SDK-scoped endpoints.

fetchWalletMetadata is not a lost-cache recovery path for signing or exporting. When you pass caller-supplied externalServerKeyShares into signMessage, signTransaction, exportKey, or exportPrivateKey, the SDK requires walletMetadata.externalServerKeySharesBackupInfo to be present and throws if it is missing. The identity-only metadata returned here will be rejected by those methods. Treat the full walletMetadata from createWalletAccount / importPrivateKey as recovery-critical and persist it from creation.

Operation	Works with identity-only `walletMetadata`?
`signMessage` / `signTransaction` (with caller-supplied `externalServerKeyShares`)	❌ No — throws `MissingBackupInfoError`
`exportKey` / `exportPrivateKey` (with caller-supplied `externalServerKeyShares`)	❌ No — throws `MissingBackupInfoError`
`verifyPassword`, `refreshWalletAccountShares`, `reshare`, `updatePassword`	❌ No — requires the full `walletMetadata` from creation
Re-identifying a wallet (display chain / derivation path in admin UI)	✅ Yes

The recommended path is to persist the full walletMetadata from creation. fetchWalletMetadata is an identification primitive, not a recovery primitive.

Parameters

accountAddress (string) — The wallet’s account address

Returns

Promise<WalletMetadata> — Identity-only metadata.

Example

import { authenticatedSvmClient } from './client';

const svmClient = await authenticatedSvmClient();

// Re-identify a wallet by address — e.g. for an admin tool that needs
// to render chain / derivation path next to the address.
const walletMetadata = await svmClient.fetchWalletMetadata(accountAddress);

console.log(walletMetadata.chainName);              // "SVM"
console.log(walletMetadata.thresholdSignatureScheme); // ThresholdSignatureScheme.TWO_OF_TWO

// Do NOT attempt to sign or export from this object — those throw
// because externalServerKeySharesBackupInfo is missing:
//   await svmClient.signMessage({ walletMetadata, externalServerKeyShares, ... });
//   // → MissingBackupInfoError

WalletMetadata - The metadata object passed to every operation
createWalletAccount() - The canonical source of complete walletMetadata
Storage Best Practices - Persist the full walletMetadata to avoid this fallback

Getting Started

Server Wallets

Agent Wallets

EVM Guides

SVM Guides

TON Guides

BTC Guides

Auth & Sessions Reference

EVM Reference

SVM Reference

Types

Upgrade Guides

fetchWalletMetadata

Function Signature

Description

Parameters

Returns

Example

​Function Signature

​Description

​Parameters

​Returns

​Example

​Related

Function Signature

Description

Parameters

Returns

Example

Related