Local Wallet Standard v0.1

An open standard for secure local wallet storage and agent access.

Abstract

The Local Wallet Standard (LWS) defines how cryptographic wallets are stored on a local filesystem, how agents and CLI tools access them through a unified interface, and how policy-based controls govern what operations are permitted — all without ever exposing private keys to the calling process.

As AI agents become first-class participants in blockchain ecosystems — executing trades, paying for services, managing treasuries — they need a standardized, secure way to access wallets locally. Today, every tool rolls its own approach: environment variables with raw private keys, proprietary cloud APIs, bespoke keystore formats. LWS replaces this fragmentation with a single open standard.

Core Types

All types use CAIP identifiers and are defined in TypeScript for clarity. Implementations may use any language.

// === Identifiers ===

/** CAIP-2 chain identifier */
type ChainId = `${string}:${string}`;
// e.g. "eip155:1", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"

/** CAIP-10 account identifier */
type AccountId = `${ChainId}:${string}`;
// e.g. "eip155:1:0xab16a96d..."

/** Wallet identifier (UUID v4) */
type WalletId = string;

// === Wallet Descriptor ===

interface WalletDescriptor {
  id: WalletId;
  name: string;
  createdAt: string;                 // ISO 8601
  chainType: ChainType;
  accounts: AccountDescriptor[];
  metadata: Record<string, unknown>;
}

interface AccountDescriptor {
  accountId: AccountId;              // CAIP-10
  address: string;                   // chain-native
  derivationPath: string;            // BIP-44 path
  chainId: ChainId;                  // CAIP-2
}

// === API Keys ===

interface ApiKey {
  id: string;                        // UUID v4
  name: string;                      // human-readable label
  tokenHash: string;                 // SHA-256 of raw token
  createdAt: string;                 // ISO 8601
  walletIds: WalletId[];             // wallets this key can access
  policyIds: string[];               // policies evaluated per request
  expiresAt?: string;                // optional expiry
}

// === Operations ===

interface SignRequest {
  walletId: WalletId;
  chainId: ChainId;
  transaction: SerializedTransaction;
  simulate?: boolean;                // default: true
}

interface SignAndSendRequest extends SignRequest {
  maxRetries?: number;
  confirmations?: number;
}

interface SignMessageRequest {
  walletId: WalletId;
  chainId: ChainId;
  message: string | Uint8Array;
  encoding?: "utf8" | "hex";
}

// === Policy ===

interface Policy {
  id: string;
  name: string;
  executable: string;                  // absolute path to policy executable
  config?: Record<string, unknown>;    // static config passed to executable
  action: "deny" | "warn";
}

interface PolicyContext {
  transaction: SerializedTransaction;
  chainId: ChainId;
  wallet: WalletDescriptor;
  simulation?: SimulationResult;
  timestamp: string;
  apiKeyId: string;                  // the API key making this request
}

interface PolicyResult {
  allow: boolean;
  reason?: string;
}

Specification Documents

License

This specification is released under CC0 1.0 Universal — dedicated to the public domain.