wallet

The wallet extension provides wallet connectors for agent operations including challenge signing, transaction signing, and wallet management.

Installation

bun add @regent/wallet

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { wallets, walletsFromEnv } from '@regent/wallet';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .use(wallets({ config: walletsFromEnv() }))
  .build();

API Reference

wallets(options?)

Creates the wallets extension.

function wallets(options?: {
  config?: WalletsConfig;
}): Extension<{ wallets?: WalletsRuntime }>

WalletsConfig

type WalletsConfig = {
  agent?: AgentWalletConfig;
  developer?: DeveloperWalletConfig;
};

type AgentWalletConfig =
  | LocalWalletOptions
  | SignerWalletOptions
  | LucidWalletOptions
  | ThirdwebWalletOptions;

type DeveloperWalletConfig = {
  type: 'local';
  privateKey: string;
  // + optional metadata fields
};

walletsFromEnv()

Configure wallets from environment variables:

function walletsFromEnv(
  overrides?: WalletsConfig,
  env?: Record<string, string | undefined>
): WalletsConfig | undefined

WalletConnector Interface

All wallet implementations conform to this interface:

interface WalletConnector {
  // Sign challenge (required)
  signChallenge(challenge: AgentChallenge): Promise<string>;

  // Metadata
  getWalletMetadata(): Promise<WalletMetadata | null>;
  getAddress?(): Promise<string | null>;
  supportsCaip2?(caip2: string): boolean | Promise<boolean>;

  // Capabilities
  getCapabilities?(): WalletCapabilities | null;
  getSigner?(): Promise<LocalEoaSigner | null>;
  getWalletClient?<T>(): Promise<T | null>;
}

WalletMetadata

interface WalletMetadata {
  id?: string | null;
  address?: string | null;
  chain?: string | null;
  chainType?: string | null;
  provider?: string | null;
  accountId?: string | null;
  label?: string | null;
  caip2?: string | null;
}

WalletCapabilities

type WalletCapability = 'signer' | 'walletClient';
type WalletCapabilities = Partial<Record<WalletCapability, true>>;

Connector Types

LocalEoaWalletConnector

Local EOA wallet using a private key.

import { LocalEoaWalletConnector, createPrivateKeySigner } from '@regent/wallet';

const signer = createPrivateKeySigner('0x...');
const connector = new LocalEoaWalletConnector({
  signer,
  address: '0x...',
  chain: 'base',
  chainType: 'evm',
});

Options

interface LocalEoaWalletConnectorOptions {
  signer: LocalEoaSigner;
  address?: string | null;
  caip2?: string | null;
  chain?: string | null;
  chainType?: string | null;
  provider?: string | null;
  label?: string | null;
  walletClient?: LocalWalletClientConfig | null;
}

interface LocalWalletClientConfig {
  rpcUrl?: string | null;
  chainId?: number | null;
  chainName?: string | null;
  nativeCurrency?: {
    name: string;
    symbol: string;
    decimals: number;
  } | null;
}

Capabilities

signer: true - Provides LocalEoaSigner
walletClient: true - Provides viem WalletClient

ThirdwebWalletConnector

Server wallet via thirdweb Engine.

import { ThirdwebWalletConnector } from '@regent/wallet';

const connector = new ThirdwebWalletConnector({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
  walletLabel: 'agent-wallet',
  chainId: 84532,
});

Options

interface ThirdwebWalletConnectorOptions {
  secretKey: string;          // Required
  clientId?: string;
  walletLabel: string;        // Required
  chainId: number;            // Required
  address?: string | null;
  caip2?: string | null;
  chain?: string | null;
  chainType?: string | null;
  label?: string | null;
}

Dependencies

Requires peer dependency:

bun add thirdweb@^5.84.0

ServerOrchestratorWalletConnector

Server-orchestrated wallet via Regent API.

import { ServerOrchestratorWalletConnector } from '@regent/wallet';

const connector = new ServerOrchestratorWalletConnector({
  baseUrl: 'https://api.regent.example.com',
  agentRef: 'my-agent-id',
});

// Set access token before use
connector.setAccessToken('bearer-token');

Options

interface ServerOrchestratorWalletConnectorOptions {
  baseUrl: string;          // Required
  agentRef: string;         // Required
  fetch?: FetchExecutor;
  headers?: HeadersInit;
  accessToken?: string | null;
  authorizationContext?: Record<string, unknown>;
}

Access Token Management

// Set or update access token
connector.setAccessToken('new-token');

// Throws if token not set when signing
ServerOrchestratorMissingAccessTokenError

Environment Variables

Agent Wallet

Common:

AGENT_WALLET_TYPE=local|thirdweb|regent

For Local Wallets (type=local):

AGENT_WALLET_PRIVATE_KEY=0x...
AGENT_WALLET_ADDRESS=0x...
AGENT_WALLET_CHAIN=ethereum
AGENT_WALLET_CHAIN_TYPE=evm
AGENT_WALLET_RPC_URL=http://...
AGENT_WALLET_CHAIN_ID=1

For Thirdweb Wallets (type=thirdweb):

AGENT_WALLET_SECRET_KEY=...
AGENT_WALLET_CLIENT_ID=...
AGENT_WALLET_LABEL=agent-wallet
AGENT_WALLET_CHAIN_ID=84532

For Regent Wallets (type=regent):

AGENT_WALLET_BASE_URL=https://...
AGENT_WALLET_AGENT_REF=agent-id
AGENT_WALLET_ACCESS_TOKEN=...

Developer Wallet

DEVELOPER_WALLET_PRIVATE_KEY=0x...
DEVELOPER_WALLET_ADDRESS=0x...
DEVELOPER_WALLET_CHAIN=ethereum

Challenge Signing

AgentChallenge

interface AgentChallenge {
  id: string;
  credential_id?: string | null;
  payload?: unknown;
  payload_hash?: string | null;
  nonce: string;
  scopes?: string[];
  issued_at: string | Date;
  expires_at: string | Date;
  server_signature?: string | null;
}

Signing Modes

EIP-712 Typed Data

// Challenge with typedData payload
const challenge = {
  id: 'challenge-123',
  nonce: 'abc',
  payload: {
    typedData: {
      primaryType: 'Message',
      types: { Message: [{ name: 'content', type: 'string' }] },
      domain: { name: 'MyApp', version: '1' },
      message: { content: 'Hello' },
    },
  },
  issued_at: new Date(),
  expires_at: new Date(Date.now() + 60000),
};

const signature = await connector.signChallenge(challenge);

EIP-191 Message

// Challenge with string message
const challenge = {
  id: 'challenge-123',
  nonce: 'abc',
  payload: { message: 'Sign this message' },
  issued_at: new Date(),
  expires_at: new Date(Date.now() + 60000),
};

const signature = await connector.signChallenge(challenge);

Message Encoding Detection

import { detectMessageEncoding } from '@regent/wallet';

detectMessageEncoding('0x1234abcd');  // 'hex'
detectMessageEncoding('Hello');       // 'utf-8'

LocalEoaSigner Interface

interface LocalEoaSigner {
  signMessage(message: string | Uint8Array): Promise<string>;

  signTypedData?(payload: {
    domain: Record<string, unknown>;
    primaryType: string;
    types: Record<string, Array<{ name: string; type: string }>>;
    message: Record<string, unknown>;
  }): Promise<string>;

  signTransaction?(transaction: {
    to?: `0x${string}` | null;
    value?: bigint;
    data?: `0x${string}`;
    gas?: bigint;
    gasPrice?: bigint;
    nonce?: number;
    chainId?: number;
  }): Promise<`0x${string}`>;

  getAddress?(): Promise<string | null>;
}

Viem Integration

Signature Utilities

import { signMessageWithViem, signTypedDataWithViem } from '@regent/wallet';
import type { SignerWalletClient } from '@regent/wallet';

// Sign message (EIP-191)
const signature = await signMessageWithViem(walletClient, 'Hello');

// Sign typed data (EIP-712)
const signature = await signTypedDataWithViem(walletClient, {
  domain: { name: 'MyApp', version: '1', chainId: 1, verifyingContract: '0x...' },
  types: { Message: [{ name: 'content', type: 'string' }] },
  primaryType: 'Message',
  message: { content: 'Hello' },
});

Creating Private Key Signer

import { createPrivateKeySigner } from '@regent/wallet';

const signer = createPrivateKeySigner('0x...');
// Uses viem's privateKeyToAccount internally

Custom Wallet Connector

Bring your own wallet implementation:

import { createSignerConnector, type CompatibleWallet } from '@regent/wallet';

const wallet: CompatibleWallet = {
  address: '0x...',
  signMessage: async (msg) => { /* ... */ },
  signTypedData: async (data) => { /* ... */ },
};

const signer = createSignerConnector(wallet);

CompatibleWallet Interface

interface CompatibleWallet {
  address?: string;
  getAddress?: () => Promise<string>;
  signMessage: (message: string | Uint8Array) => Promise<string>;
  signTypedData?: (data: {
    domain: Record<string, unknown>;
    primaryType: string;
    types: Record<string, Array<{ name: string; type: string }>>;
    message: Record<string, unknown>;
  }) => Promise<string>;
  signTransaction?: (transaction: {
    to?: `0x${string}` | null;
    value?: bigint;
    data?: `0x${string}`;
    gas?: bigint;
    gasPrice?: bigint;
    nonce?: number;
    chainId?: number;
  }) => Promise<`0x${string}`>;
}

WalletsRuntime

When the extension is used, agent.wallets provides:

type WalletsRuntime = {
  agent?: AgentWalletHandle;
  developer?: DeveloperWalletHandle;
};

interface AgentWalletHandle {
  kind: AgentWalletKind;
  connector: WalletConnector;
  setAccessToken?(token: string | null): void;
}

interface DeveloperWalletHandle {
  kind: 'local';
  connector: WalletConnector;
}

Address Utilities

import { normalizeAddress, sanitizeAddress, toCaip10, ZERO_ADDRESS } from '@regent/wallet';

// Normalize to lowercase hex (throws on invalid)
const address = normalizeAddress('0xABCD...');

// Sanitize (returns ZERO_ADDRESS on invalid)
const safe = sanitizeAddress(maybeAddress);

// Convert to CAIP-10 format
const caip10 = toCaip10({
  chainId: 1,
  address: '0x...',
});
// Returns: "eip155:1:0x..."

Exports

// Extension
export { wallets } from '@regent/wallet';
export { walletsFromEnv } from '@regent/wallet';

// Connectors
export {
  LocalEoaWalletConnector,
  ThirdwebWalletConnector,
  ServerOrchestratorWalletConnector,
  ServerOrchestratorMissingAccessTokenError,
} from '@regent/wallet';

// Signer utilities
export { createPrivateKeySigner, createSignerConnector } from '@regent/wallet';
export type { CompatibleWallet, LocalEoaSigner } from '@regent/wallet';

// Challenge utilities
export {
  normalizeChallenge,
  extractSignature,
  extractWalletMetadata,
  detectMessageEncoding,
} from '@regent/wallet';

// Address utilities
export { normalizeAddress, sanitizeAddress, toCaip10, ZERO_ADDRESS } from '@regent/wallet';

// Viem utilities
export { signMessageWithViem, signTypedDataWithViem } from '@regent/wallet';
export type { SignerWalletClient } from '@regent/wallet';

// Types
export type {
  WalletsConfig,
  WalletsRuntime,
  WalletConnector,
  WalletMetadata,
  WalletCapabilities,
  AgentChallenge,
} from '@regent/wallet';

Previoustypes Nextx402

Last updated 2 months ago

Good night

hashtagInstallation

hashtagBasic Usage

hashtagAPI Reference

hashtagwallets(options?)

hashtagWalletsConfig

hashtagwalletsFromEnv()

hashtagWalletConnector Interface

hashtagWalletMetadata

hashtagWalletCapabilities

hashtagConnector Types

hashtagLocalEoaWalletConnector

hashtagOptions

hashtagCapabilities

hashtagThirdwebWalletConnector

hashtagOptions

hashtagDependencies

hashtagServerOrchestratorWalletConnector

hashtagOptions

hashtagAccess Token Management

hashtagEnvironment Variables

hashtagAgent Wallet

hashtagDeveloper Wallet

hashtagChallenge Signing

hashtagAgentChallenge

hashtagSigning Modes

hashtagEIP-712 Typed Data

hashtagEIP-191 Message

hashtagMessage Encoding Detection

hashtagLocalEoaSigner Interface

hashtagViem Integration

hashtagSignature Utilities

hashtagCreating Private Key Signer

hashtagCustom Wallet Connector

hashtagCompatibleWallet Interface

hashtagWalletsRuntime

hashtagAddress Utilities

hashtagExports

Installation

Basic Usage

API Reference

wallets(options?)

WalletsConfig

walletsFromEnv()

WalletConnector Interface

WalletMetadata

WalletCapabilities

Connector Types

LocalEoaWalletConnector

Options

Capabilities

ThirdwebWalletConnector

Options

Dependencies

ServerOrchestratorWalletConnector

Options

Access Token Management

Environment Variables

Agent Wallet

Developer Wallet

Challenge Signing

AgentChallenge

Signing Modes

EIP-712 Typed Data

EIP-191 Message

Message Encoding Detection

LocalEoaSigner Interface

Viem Integration

Signature Utilities

Creating Private Key Signer

Custom Wallet Connector

CompatibleWallet Interface

WalletsRuntime

Address Utilities

Exports