Wallets

Wallets are the foundation of the Agentic Wallet system. Each wallet represents a Solana keypair with flexible custody options and built-in balance management.

Wallet Creation

Wallets are created through the wallet-engine service and assigned a UUID identifier for internal tracking:

interface WalletMetadata {
  id: string;                    // UUID wallet identifier
  publicKey: string;             // Base58-encoded Solana public key
  provider: string;              // Custody provider type
  keyProvenance?: KeyProvenance; // Key generation details
  createdAt: string;             // ISO-8601 timestamp
  status: 'active' | 'disabled';
  label?: string;                // Optional human-readable label
}

Creating a Wallet

npm run cli -- wallet create "My Trading Wallet"

curl -X POST http://localhost:3000/api/v1/wallets \
  -H "Content-Type: application/json" \
  -d '{"label": "My Trading Wallet"}'

const wallet = await client.wallet.create({
  label: "My Trading Wallet"
});

Auto-Funding (Devnet Only)

For development, wallets can be automatically funded on creation:

{
  "label": "Test Wallet",
  "autoFund": true,
  "fundLamports": 1000000000
}

Auto-funding only works with devnet RPC URLs and requires WALLET_AUTOFUND_PAYER_PRIVATE_KEY to be configured.

Signer Backends

Agentic Wallet supports multiple signer backends for different security and deployment requirements:

Encrypted File

Development & TestingKeys encrypted with AES-256-GCM and stored locally.

WALLET_SIGNER_BACKEND=encrypted-file
WALLET_ENCRYPTION_SECRET=your-secret

Memory

Testing OnlyKeys stored in-memory, lost on restart.

WALLET_SIGNER_BACKEND=memory

KMS

Production: CloudAWS KMS or compatible key management service.

WALLET_SIGNER_BACKEND=kms
WALLET_KMS_MASTER_SECRET=...
WALLET_KMS_KEY_ID=...

HSM

Production: HardwareHardware Security Module integration.

WALLET_SIGNER_BACKEND=hsm
WALLET_HSM_PIN=...
WALLET_HSM_MODULE_SECRET=...
WALLET_HSM_SLOT=0

MPC

Production: DistributedMulti-Party Computation with threshold signatures.

WALLET_SIGNER_BACKEND=mpc
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3

Key Provenance

Each wallet includes provenance metadata:

interface KeyProvenance {
  backend: 'encrypted-file' | 'memory' | 'kms' | 'hsm' | 'mpc';
  custody: 'local' | 'external';
  deterministicAddressing: boolean;
}

Balance Queries

SOL Balance

Query the native SOL balance for any wallet:

npm run cli -- wallet balance <walletId>

curl http://localhost:3000/api/v1/wallets/{walletId}/balance

Response:

{
  "data": {
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "publicKey": "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g",
    "lamports": 1000000000,
    "sol": 1.0
  }
}

SPL Token Balances

Query all SPL token holdings:

npm run cli -- wallet tokens <walletId>

curl http://localhost:3000/api/v1/wallets/{walletId}/tokens

Response:

{
  "data": {
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "tokens": [
      {
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "amount": "1000000",
        "decimals": 6,
        "uiAmount": 1.0
      }
    ]
  }
}

Signing Operations

The wallet-engine provides a secure signing boundary. Private keys never leave the service:

Transaction Signing

{
  "transaction": "base64-encoded-transaction"
}

Returns:

{
  "data": {
    "signedTransaction": "base64-signed-transaction",
    "signature": "base58-signature",
    "txVersion": "v0" | "legacy"
  }
}

Message Signing

{
  "message": "base64-encoded-message"
}

Returns:

{
  "data": {
    "signatureBase64": "...",
    "signatureBase58": "..."
  }
}

The /api/v1/wallets/:walletId/sign endpoint should only be called by trusted internal services (transaction-engine). Never expose this endpoint to external clients.

Wallet Listing

List all wallets or filter by public key:

curl http://localhost:3000/api/v1/wallets

curl "http://localhost:3000/api/v1/wallets?publicKey=9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g"

RPC Reliability

Wallet-engine includes automatic RPC retry logic:

Health-scored RPC pool: Automatic failover using SOLANA_RPC_POOL_URLS
Adaptive retries: Configurable max retries and delay
Error detection: Automatic retry for 429, fetch failures, blockhash issues

Configuration

SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_RPC_POOL_URLS=https://rpc1.com,https://rpc2.com
SOLANA_RPC_MAX_RETRIES=5
SOLANA_RPC_RETRY_DELAY_MS=500

Best Practices

Production Deployment

Never use memory or encrypted-file backends in production
Use KMS, HSM, or MPC for production key management
Enable RPC pool failover for high availability
Set appropriate retry limits to avoid cascading failures
Monitor wallet creation rate and implement rate limiting

Security

Private keys never appear in logs or API responses
Signing operations are isolated in wallet-engine
All key material is encrypted at rest (except memory backend)
Use separate wallets for different risk profiles
Implement wallet status management (active/disabled)

Development

Use autoFund for quick devnet testing
Label wallets clearly for debugging
Use encrypted-file backend for local development
Test RPC failover scenarios
Validate balance before attempting transactions

Source Code Reference

Wallet functionality is implemented in:

services/wallet-engine/src/app.ts - Main wallet API (services/wallet-engine/src/app.ts:1)
services/wallet-engine/src/key-provider/factory.ts - Signer backend factory
packages/common/src/schemas/wallet.ts - TypeScript schemas (packages/common/src/schemas/wallet.ts:1)

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

Wallets

Wallets

Wallet Creation

Creating a Wallet

Auto-Funding (Devnet Only)

Signer Backends

Encrypted File

Memory

KMS

HSM

MPC

Key Provenance

Balance Queries

SOL Balance

SPL Token Balances

Signing Operations

Transaction Signing

Message Signing

Wallet Listing

RPC Reliability

Configuration

Best Practices

Source Code Reference

​Wallets

​Wallet Creation

​Creating a Wallet

​Auto-Funding (Devnet Only)

​Signer Backends

Encrypted File

Memory

KMS

HSM

MPC

​Key Provenance

​Balance Queries

​SOL Balance

​SPL Token Balances

​Signing Operations

​Transaction Signing

​Message Signing

​Wallet Listing

​RPC Reliability

​Configuration

​Best Practices

​Source Code Reference

Wallets

Wallet Creation

Creating a Wallet

Auto-Funding (Devnet Only)

Signer Backends

Key Provenance

Balance Queries

SOL Balance

SPL Token Balances

Signing Operations

Transaction Signing

Message Signing

Wallet Listing

RPC Reliability

Configuration

Best Practices

Source Code Reference