Skip to main content

​
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"

​
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>
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>
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

​
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

  1. Never use memory or encrypted-file backends in production
  2. Use KMS, HSM, or MPC for production key management
  3. Enable RPC pool failover for high availability
  4. Set appropriate retry limits to avoid cascading failures
  5. Monitor wallet creation rate and implement rate limiting
  1. Private keys never appear in logs or API responses
  2. Signing operations are isolated in wallet-engine
  3. All key material is encrypted at rest (except memory backend)
  4. Use separate wallets for different risk profiles
  5. Implement wallet status management (active/disabled)
  1. Use autoFund for quick devnet testing
  2. Label wallets clearly for debugging
  3. Use encrypted-file backend for local development
  4. Test RPC failover scenarios
  5. 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)

Build docs developers (and LLMs) love

Get started for freeTalk to us