Creating Wallets

Overview

Agentic Wallet provides multiple interfaces for creating and managing Solana wallets. All wallets are created with secure key custody, automatic signing capabilities, and support for both SOL and SPL tokens.

The CLI provides the simplest way to create wallets for testing and development.

Basic Wallet Creation

npm run cli -- wallet create my-wallet

Auto-funded Wallet (Devnet Only)

Create a wallet and automatically fund it with SOL:

npm run cli -- wallet create trader-1 --auto-fund --fund-lamports 2000000

Auto-funding requires WALLET_AUTOFUND_PAYER_PRIVATE_KEY or PRIVATE_KEY in your environment.

Legacy Compatibility CLI

For orchestrator compatibility:

npm run wallets -- create --label bot-trader
npm run wallets -- create --label bot-trader --auto-fund --fund-lamports 2000000
npm run wallets -- list

Create wallets via HTTP requests to the API gateway.

Basic Request

curl -X POST http://localhost:3000/api/v1/wallets \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -d '{"label": "trading-wallet"}'

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "publicKey": "8xKz...",
    "label": "trading-wallet",
    "createdAt": "2026-03-08T12:00:00.000Z"
  }
}

With Auto-funding

curl -X POST http://localhost:3000/api/v1/wallets \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-api-key" \
  -d '{
    "label": "funded-wallet",
    "autoFund": true,
    "fundLamports": 2000000
  }'

Use the TypeScript SDK for programmatic wallet creation.

Initialize Client

import { createAgenticWalletClient } from '@agentic-wallet/sdk';

const client = createAgenticWalletClient('http://localhost:3000', {
  apiKey: 'dev-api-key',
  tenantId: 'optional-tenant-id'
});

Create Wallet

const wallet = await client.wallet.create({
  label: 'my-trading-bot'
});

console.log(`Wallet ID: ${wallet.id}`);
console.log(`Public Key: ${wallet.publicKey}`);

Create with Auto-funding

const fundedWallet = await client.wallet.create({
  label: 'funded-bot',
  autoFund: true,
  fundLamports: 2_000_000 // 0.002 SOL
});

Full Example from Source

Real implementation from scripts/wallets.ts:

import 'dotenv/config';
import { createAgenticWalletClient } from '../packages/sdk/src/index.js';

const apiBase = process.env.API_BASE_URL ?? 'http://localhost:3000';
const apiKey = process.env.API_KEY ?? 'dev-api-key';

const client = createAgenticWalletClient(apiBase, { apiKey });

// Create wallet
const data = await client.wallet.create({
  label: 'my-wallet',
  autoFund: true,
  fundLamports: 2000000
});

console.log(JSON.stringify({ status: 'success', data }, null, 2));

Querying Wallet Information

Get Wallet Details

Retrieve wallet information by ID:

npm run cli -- wallet get <walletId>

curl -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/wallets/<walletId>

const wallet = await client.wallet.get(walletId);

Check SOL Balance

Query the wallet’s SOL balance:

npm run cli -- wallet balance <walletId>

curl -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/wallets/<walletId>/balance

const balance = await client.wallet.balance(walletId);
console.log(`Balance: ${balance.lamports} lamports`);

Response:

{
  "status": "success",
  "data": {
    "publicKey": "8xKz...",
    "lamports": 2000000,
    "sol": 0.002
  }
}

List SPL Tokens

Get all SPL token balances:

npm run cli -- wallet tokens <walletId>

curl -H "x-api-key: dev-api-key" \
  http://localhost:3000/api/v1/wallets/<walletId>/tokens

const tokens = await client.wallet.tokens(walletId);

Response:

{
  "status": "success",
  "data": {
    "tokens": [
      {
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "balance": "1000000",
        "decimals": 6,
        "uiAmount": 1.0
      }
    ]
  }
}

List All Wallets

Retrieve all wallets or find by public key:

npm run wallets -- list

npm run wallets -- list --public-key 8xKz...

const wallets = await client.wallet.list();

const wallet = await client.wallet.findByPublicKey(publicKey);

Key Management

Signer Backends

Wallets use pluggable signer backends for key custody:

WALLET_SIGNER_BACKEND=encrypted-file
WALLET_KEY_ENCRYPTION_SECRET=your-secret

WALLET_SIGNER_BACKEND=memory
# Keys lost on restart

WALLET_SIGNER_BACKEND=kms
WALLET_KMS_MASTER_SECRET=your-kms-secret
WALLET_KMS_KEY_ID=optional-key-id

WALLET_SIGNER_BACKEND=hsm
WALLET_HSM_PIN=your-pin
WALLET_HSM_MODULE_SECRET=your-secret
WALLET_HSM_SLOT=optional-slot

WALLET_SIGNER_BACKEND=mpc
WALLET_MPC_NODE_SECRETS=secret1,secret2,secret3
# Or individual secrets:
WALLET_MPC_NODE1_SECRET=secret1
WALLET_MPC_NODE2_SECRET=secret2
WALLET_MPC_NODE3_SECRET=secret3

Production Security: Use kms, hsm, or mpc backends in production. The encrypted-file backend is suitable for development only. Never use memory backend in production.

Backend Selection Guide

encrypted-file: Best for local development and prototyping
memory: Testing only (ephemeral, keys lost on restart)
kms: Managed key governance with audit trails
hsm: Hardware-rooted custody for compliance
mpc: Distributed custody to reduce single-key-holder risk

Security Considerations

Important Security Features:

Private keys never exposed via API
All signing happens within wallet-engine boundary
Agent code never has direct key access
Multiple signer backend options for different security postures

Trust Boundaries

Agent Boundary: Agents emit intents only, never handle keys
Signing Boundary: Only wallet-engine signs transactions
Policy Boundary: All spend-capable intents pass policy evaluation before signing

Usage Guides

Advanced

Creating Wallets

Overview