viem-wallet
Functions
<dl> <dt><a href="#validateByoRpcUrl">validateByoRpcUrl(rpcUrl)</a> ⇒ <code>boolean</code></dt> <dd><p>Validates that a user-provided BYO (Bring Your Own) RPC URL comes from an allowed host. This prevents Server-Side Request Forgery (SSRF) and proxying requests to arbitrary destinations.</p> </dd> <dt><a href="#resolveRpcMode">resolveRpcMode([options])</a> ⇒ <code>'byo'</code> | <code>'managed'</code></dt> <dd><p>Resolves the RPC tier mode based on API key permissions and user request. Free tier users are forced into 'byo' (Bring Your Own) RPC mode.</p> </dd> <dt><a href="#normalizeRuntimeRpcUrl">normalizeRuntimeRpcUrl(raw)</a> ⇒ <code>string</code> | <code>null</code></dt> <dd><p>Normalizes and validates a runtime-provided RPC URL string.</p> </dd> <dt><a href="#resolveChainConfigForRequest">resolveChainConfigForRequest(chainName, [options])</a> ⇒ <code>object</code></dt> <dd><p>Resolves the specific chain configuration to use for the current request, applying BYO RPC overrides if required by the tier or requested by the user.</p> </dd> <dt><a href="#getChainConfig">getChainConfig(chainName)</a> ⇒ <code>object</code></dt> <dd><p>Retrieves the static chain configuration block for a given standard chain name.</p> </dd> <dt><a href="#createClientWithFallback">createClientWithFallback(chainConfig, [clientType])</a> ⇒ <code>Promise.<object></code></dt> <dd><p>Attempts to create a resilient viem client by pinging fallback RPCs sequentially until one responds successfully.</p> </dd> <dt><a href="#getSupportedChains">getSupportedChains()</a> ⇒ <code>Array.<{id: string, name: string, testnet: boolean, nativeCurrency: object}></code></dt> <dd><p>Returns a list of all EVM chains supported natively by this wallet service.</p> </dd> <dt><a href="#generatePrivateKey">generatePrivateKey()</a> ⇒ <code>string</code></dt> <dd><p>Generates a random 32-byte cryptographic private key for a new wallet.</p> </dd> <dt><a href="#createWallet">createWallet(params)</a> ⇒ <code>Promise.<object></code></dt> <dd><p>Creates a brand new EVM crypto wallet for an AI agent. Generates a private key, encrypts it at rest, stores the wallet in the active database, and returns the wallet details (without exposing the private key plaintext).</p> </dd> <dt><a href="#getBalance">getBalance(address, [chain], [options])</a> ⇒ <code>Promise.<{chain: string, eth: string, wei: string, rpc: string}></code></dt> <dd><p>Retrieves the native currency (e.g. ETH) balance for a given wallet address. Falls back to Redis cache if the RPC fails, or fetches fresh data from the blockchain.</p> </dd> <dt><a href="#signTransaction">signTransaction(params)</a> ⇒ <code>Promise.<{hash: string, chain: string, from: string, to: string, value: string}></code></dt> <dd><p>Signs and broadcasts a transaction to the blockchain. All transactions pass through the policy engine prior to execution.</p> </dd> <dt><a href="#getExplorerUrl">getExplorerUrl(chainName, txHash)</a> ⇒ <code>string</code></dt> <dd><p>Constructs the canonical block explorer URL for a given transaction hash on a specific chain.</p> </dd> <dt><a href="#getAllWallets">getAllWallets([options])</a> ⇒ <code>Promise.<Array.<object>></code></dt> <dd><p>Retrieves all wallets stored in the system (either from the database or memory store). Primarily used by admin dashboards and the CLI.</p> </dd> <dt><a href="#getWalletById">getWalletById(id)</a> ⇒ <code>object</code> | <code>undefined</code></dt> <dd><p>Pre-fetches a wallet from the active memory store by its internal ID.</p> </dd> <dt><a href="#getWalletByAddress">getWalletByAddress(address, [options])</a> ⇒ <code>Promise.<(object|undefined)></code></dt> <dd><p>Retrieves a specific wallet by its public blockchain address.</p> </dd> <dt><a href="#importWallet">importWallet(params)</a> ⇒ <code>Promise.<object></code></dt> <dd><p>Imports an external EVM wallet matching the provided private key into the Agent Wallet Service. The private key is immediately encrypted at rest.</p> </dd> <dt><a href="#getTransactionReceipt">getTransactionReceipt()</a></dt> <dd><p>Get transaction receipt</p> </dd> <dt><a href="#getMultiChainBalance">getMultiChainBalance()</a></dt> <dd><p>Get balance across all chains</p> </dd> <dt><a href="#estimateGas">estimateGas()</a></dt> <dd><p>Estimate gas for a transaction</p> </dd> <dt><a href="#sweepWallet">sweepWallet()</a></dt> <dd><p>Transfer all funds (sweep wallet)</p> </dd> <dt><a href="#transferErc20">transferErc20(from, to, tokenAddress, amount, decimals, chain, options)</a></dt> <dd><p>Transfer ERC-20 tokens</p> </dd> </dl>
<a name="validateByoRpcUrl"></a>
validateByoRpcUrl(rpcUrl) ⇒ <code>boolean</code>
Validates that a user-provided BYO (Bring Your Own) RPC URL comes from an allowed host. This prevents Server-Side Request Forgery (SSRF) and proxying requests to arbitrary destinations.
Kind: global function
Returns: <code>boolean</code> - True if the host is allowed.
Throws:
- <code>Error</code> If the host is not in the allowed list or the URL is malformed.
| Param | Type | Description |
|---|---|---|
| rpcUrl | <code>string</code> | The custom RPC URL provided in the request header or body. |
<a name="resolveRpcMode"></a>
resolveRpcMode([options]) ⇒ <code>'byo'</code> | <code>'managed'</code>
Resolves the RPC tier mode based on API key permissions and user request. Free tier users are forced into 'byo' (Bring Your Own) RPC mode.
Kind: global function
Returns: <code>'byo'</code> | <code>'managed'</code> - The resolved RPC routing mode.
| Param | Type | Default | Description |
|---|---|---|---|
| [options] | <code>object</code> | <code>{}</code> | Request options. |
| [options.tier] | <code>string</code> | The API key tier (e.g., 'free', 'pro', 'admin'). | |
| [options.rpcMode] | <code>string</code> | Explicitly requested RPC mode ('byo' or 'managed'). |
<a name="normalizeRuntimeRpcUrl"></a>
normalizeRuntimeRpcUrl(raw) ⇒ <code>string</code> | <code>null</code>
Normalizes and validates a runtime-provided RPC URL string.
Kind: global function
Returns: <code>string</code> | <code>null</code> - The normalized standard URL string, or null if empty.
Throws:
- <code>Error</code> If the string is provided but is not a valid URL format.
| Param | Type | Description |
|---|---|---|
| raw | <code>string</code> | The unvalidated RPC URL string. |
<a name="resolveChainConfigForRequest"></a>
resolveChainConfigForRequest(chainName, [options]) ⇒ <code>object</code>
Resolves the specific chain configuration to use for the current request, applying BYO RPC overrides if required by the tier or requested by the user.
Kind: global function
Returns: <code>object</code> - The effective chain configuration including the rpcs array to use.
Throws:
- <code>Error</code> If a BYO RPC is required but missing or invalid.
| Param | Type | Default | Description |
|---|---|---|---|
| chainName | <code>string</code> | The target network name (e.g., 'base-sepolia'). | |
| [options] | <code>object</code> | <code>{}</code> | Request options including tier and rpcUrl. |
<a name="getChainConfig"></a>
getChainConfig(chainName) ⇒ <code>object</code>
Retrieves the static chain configuration block for a given standard chain name.
Kind: global function
Returns: <code>object</code> - The chain configuration, containing viem definitions and default RPC endpoints.
Throws:
- <code>Error</code> If the chain is unsupported.
| Param | Type | Description |
|---|---|---|
| chainName | <code>string</code> | The name of the chain. |
<a name="createClientWithFallback"></a>
createClientWithFallback(chainConfig, [clientType]) ⇒ <code>Promise.<object></code>
Attempts to create a resilient viem client by pinging fallback RPCs sequentially until one responds successfully.
Kind: global function
Returns: <code>Promise.<object></code> - The initialized viem client.
Throws:
- <code>Error</code> If all configured RPCs for the chain fail.
| Param | Type | Default | Description |
|---|---|---|---|
| chainConfig | <code>object</code> | The resolved chain configuration object. | |
| [clientType] | <code>'public'</code> | <code>'wallet'</code> | <code>'public'</code> | The type of client to initialize. |
<a name="getSupportedChains"></a>
getSupportedChains() ⇒ <code>Array.<{id: string, name: string, testnet: boolean, nativeCurrency: object}></code>
Returns a list of all EVM chains supported natively by this wallet service.
Kind: global function
Returns: <code>Array.<{id: string, name: string, testnet: boolean, nativeCurrency: object}></code> - List of chains.
<a name="generatePrivateKey"></a>
generatePrivateKey() ⇒ <code>string</code>
Generates a random 32-byte cryptographic private key for a new wallet.
Kind: global function
Returns: <code>string</code> - Hex-encoded private key starting with '0x'.
<a name="createWallet"></a>
createWallet(params) ⇒ <code>Promise.<object></code>
Creates a brand new EVM crypto wallet for an AI agent. Generates a private key, encrypts it at rest, stores the wallet in the active database, and returns the wallet details (without exposing the private key plaintext).
Kind: global function
Returns: <code>Promise.<object></code> - The newly created wallet object (id, address, chain, agentName).
Throws:
- <code>Error</code> If database insertion fails.
| Param | Type | Default | Description |
|---|---|---|---|
| params | <code>object</code> | Wallet creation parameters. | |
| params.agentName | <code>string</code> | Identifier for the AI agent owning the wallet. | |
| [params.chain] | <code>string</code> | <code>"'base-sepolia'"</code> | The default chain network. |
| [params.tenantId] | <code>string</code> | Optional partition ID or tenant identifier for multi-tenant setups. |
<a name="getBalance"></a>
getBalance(address, [chain], [options]) ⇒ <code>Promise.<{chain: string, eth: string, wei: string, rpc: string}></code>
Retrieves the native currency (e.g. ETH) balance for a given wallet address. Falls back to Redis cache if the RPC fails, or fetches fresh data from the blockchain.
Kind: global function
Returns: <code>Promise.<{chain: string, eth: string, wei: string, rpc: string}></code> - Balance details.
Throws:
- <code>Error</code> If the wallet does not exist or all RPCs fail.
| Param | Type | Default | Description |
|---|---|---|---|
| address | <code>string</code> | The public address of the wallet. | |
| [chain] | <code>string</code> | The blockchain network. Defaults to the wallet's stored chain or base-sepolia. | |
| [options] | <code>object</code> | <code>{}</code> | Query options. |
| [options.tenantId] | <code>string</code> | Optional tenant partition ID for DB lookups. | |
| [options.tier] | <code>string</code> | User API tier, used to determine 'byo' vs 'managed' RPC usage. | |
| [options.rpcUrl] | <code>string</code> | Provide a BYO RPC endpoint if the tier dictates it. |
<a name="signTransaction"></a>
signTransaction(params) ⇒ <code>Promise.<{hash: string, chain: string, from: string, to: string, value: string}></code>
Signs and broadcasts a transaction to the blockchain. All transactions pass through the policy engine prior to execution.
Kind: global function
Returns: <code>Promise.<{hash: string, chain: string, from: string, to: string, value: string}></code> - Result containing the transaction hash.
Throws:
- <code>Error</code> If policy check fails, wallet is missing, or broadcast fails.
| Param | Type | Default | Description |
|---|---|---|---|
| params | <code>object</code> | Transaction parameters. | |
| params.from | <code>string</code> | The sender's wallet address. | |
| params.to | <code>string</code> | The recipient's address or contract address. | |
| params.value | <code>string</code> | <code>bigint</code> | The amount to send in ETH or native currency. | |
| [params.data] | <code>string</code> | <code>"'0x'"</code> | Hex-encoded smart contract calldata. |
| [params.chain] | <code>string</code> | The target blockchain. | |
| [params.context] | <code>object</code> | <code>{}</code> | Business context (e.g., purpose, workflow ID) logging. |
| [params.tenantId] | <code>string</code> | Optional tenant partition ID. | |
| [params.tier] | <code>string</code> | The API key tier for rate limiting and RPC routing. | |
| [params.rpcMode] | <code>string</code> | The explicitly requested RPC usage mode. | |
| [params.rpcUrl] | <code>string</code> | The custom BYO RPC endpoint URL. |
<a name="getExplorerUrl"></a>
getExplorerUrl(chainName, txHash) ⇒ <code>string</code>
Constructs the canonical block explorer URL for a given transaction hash on a specific chain.
Kind: global function
Returns: <code>string</code> - The full URL to the block explorer.
| Param | Type | Description |
|---|---|---|
| chainName | <code>string</code> | The name of the blockchain. |
| txHash | <code>string</code> | The transaction hash. |
<a name="getAllWallets"></a>
getAllWallets([options]) ⇒ <code>Promise.<Array.<object>></code>
Retrieves all wallets stored in the system (either from the database or memory store). Primarily used by admin dashboards and the CLI.
Kind: global function
Returns: <code>Promise.<Array.<object>></code> - A list of wallet summary payloads (excludes private keys).
| Param | Type | Default | Description |
|---|---|---|---|
| [options] | <code>object</code> | <code>{}</code> | Query options. |
| [options.tenantId] | <code>string</code> | Optional tenant partition ID. |
<a name="getWalletById"></a>
getWalletById(id) ⇒ <code>object</code> | <code>undefined</code>
Pre-fetches a wallet from the active memory store by its internal ID.
Kind: global function
Returns: <code>object</code> | <code>undefined</code> - The wallet object if found.
| Param | Type | Description |
|---|---|---|
| id | <code>string</code> | The internal wallet ID (e.g. wallet_xyz). |
<a name="getWalletByAddress"></a>
getWalletByAddress(address, [options]) ⇒ <code>Promise.<(object|undefined)></code>
Retrieves a specific wallet by its public blockchain address.
Kind: global function
Returns: <code>Promise.<(object|undefined)></code> - The wallet object if found in the DB/store.
| Param | Type | Default | Description |
|---|---|---|---|
| address | <code>string</code> | The public EVM address. | |
| [options] | <code>object</code> | <code>{}</code> | Query options. |
| [options.tenantId] | <code>string</code> | Optional tenant partition ID. |
<a name="importWallet"></a>
importWallet(params) ⇒ <code>Promise.<object></code>
Imports an external EVM wallet matching the provided private key into the Agent Wallet Service. The private key is immediately encrypted at rest.
Kind: global function
Returns: <code>Promise.<object></code> - The newly imported wallet summary (id, address, chain).
| Param | Type | Default | Description |
|---|---|---|---|
| params | <code>object</code> | Import parameters. | |
| params.privateKey | <code>string</code> | The external plain-text private key (with or without '0x'). | |
| params.agentName | <code>string</code> | Identifier for the AI agent owning the imported wallet. | |
| [params.chain] | <code>string</code> | <code>"DEFAULT_CHAIN"</code> | The default chain network. |
| [params.tenantId] | <code>string</code> | Optional tenant partition ID. |
<a name="getTransactionReceipt"></a>
getTransactionReceipt()
Get transaction receipt
Kind: global function
<a name="getMultiChainBalance"></a>
getMultiChainBalance()
Get balance across all chains
Kind: global function
<a name="estimateGas"></a>
estimateGas()
Estimate gas for a transaction
Kind: global function
<a name="sweepWallet"></a>
sweepWallet()
Transfer all funds (sweep wallet)
Kind: global function
<a name="transferErc20"></a>
transferErc20(from, to, tokenAddress, amount, decimals, chain, options)
Transfer ERC-20 tokens
Kind: global function
| Param | Type | Description |
|---|---|---|
| from | <code>string</code> | Sender wallet address |
| to | <code>string</code> | Recipient wallet address |
| tokenAddress | <code>string</code> | ERC-20 token contract address |
| amount | <code>string</code> | Amount to transfer (in human-readable format, e.g., "10.5") |
| decimals | <code>number</code> | Token decimals (default 18) |
| chain | <code>string</code> | Chain name |
| options | <code>object</code> | Options including tenantId, tier, rpcMode, rpcUrl |