AI Agent Wallet — Solana Devnet

An autonomous AI agent wallet for Solana that manages wallets, executes DeFi operations, and interacts with on-chain protocols — all through natural language. Secured by Turnkey hardware-backed key custody, on-chain PDA vault policy enforcement, and Kora gasless transactions. Supports multiple independent agents, each with their own isolated wallet, security policy, and decision-making context.

Built with Vercel AI SDK, Solana Agent Kit v2, Next.js 15, and Turnkey secure enclave.

For Judges — Quick Navigation

| Judging Criteria | What to Look At | Command / Link | |---|---|---| | C1: Functional Demo | Autonomous DeFi agent with 93 tools, SSE activity feed, one-click demos | pnpm dev → Dashboard | | C2: Security & Key Mgmt | Turnkey secure enclave, PDA vault, Kora gasless, spending limits, HMAC audit chain | Security tab in UI, Security & Threat Model | | C3: Documentation | 11-chapter deep dive, Mermaid diagrams, machine-readable SKILLS.md | Documentation set (architecture + threat model), SKILLS.md | | C4: Multi-Agent Scalability | Fleet health dashboard, bulk provisioning, agent-to-agent transfers | pnpm dev → Agent Monitor tab |

Key Differentiators

• Comprehensive test suite — run pnpm test to verify
• MCP server for Claude Desktop integration — pnpm mcp
• 3-layer security: Turnkey secure enclave → PDA vault → Kora gasless
• 93 DeFi tools via Solana Agent Kit v2 (vs typical 2-4)

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                            WEB UI (Next.js)                              │
│  Chat Interface │ Wallet Panel │ Portfolio │ Agent Monitor │ Analytics   │
│  Activity Feed  │ Demo Launcher │ Backup        │ Lifecycle                │
│  Security Tab: Vault Mgmt │ Audit Log Viewer │ Fleet Health │ Spending   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │  HTTP + SSE
┌───────────────────────────────────▼─────────────────────────────────────┐
│                      SECURITY MIDDLEWARE (every route)                   │
│  HMAC-SHA256 Request Signing  │  Per-IP Rate Limiter  │  Audit Logger   │
│  Spending Limit Enforcement   │  Agent Lifecycle Gate │  Input Sanit.   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                              AGENT CORE                                  │
│  LLM Provider (Claude / GPT-4)    Solana Agent Kit v2 (93 DeFi Tools)   │
│  Multi-step Tool Chaining         Success Detection Pipeline             │
│  Per-Agent SSE Event Bus          Scheduled & Recurring Payments        │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                           WALLET LAYER                                   │
│  Turnkey Secure Enclave: hardware-backed key custody (no keys in memory)   │
│  BIP-32 HD wallet: per-agent sub-accounts at m/44'/501'/{index}'/0'      │
│  PDA Vault: on-chain spending limits, program allowlists, cooldowns      │
└──────────────────┬────────────────────────────────┬─────────────────────┘
                   │ direct SOL fees                │ gasless (Kora)
                   │                                │
                   │         ┌──────────────────────▼──────────────────┐
                   │         │          KORA PAYMASTER (optional)      │
                   │         │  Fee Payer Co-signing │ Token Fee Mode  │
                   │         │  Sponsored (free) │ Margin │ Fixed      │
                   │         └──────────────────────┬──────────────────┘
                   │                                │
┌──────────────────▼────────────────────────────────▼─────────────────────┐
│                           SOLANA DEVNET                                  │
│  Jupiter │ Orca │ Raydium │ Drift │ Lulo │ Meteora │ Pyth │ deBridge    │
└─────────────────────────────────────────────────────────────────────────┘

Quick Start (Under 3 Minutes)

Prerequisites

• Node.js 18+
• pnpm (npm i -g pnpm)

Setup

# 1. Install dependencies
pnpm install

# 2. Copy environment config
cp .env.example .env

# 3. Generate a wallet encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# → paste the output as WALLET_ENCRYPTION_KEY in .env

# 4. Add your LLM API key to .env (optional — headless demo works without it)
# ANTHROPIC_API_KEY=sk-ant-api03-{your-key-here}

# 5. (Optional) Set a scheduler secret for the /api/cron/tick endpoint
# CRON_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
# CRON_JOB_API_KEY=your-cron-job-org-api-key   # For webhook automations

# 6. Start the web app
pnpm dev

Open http://localhost:3000.

First 2 Minutes

Once the app is running:

1. Click Create New Wallet in the left sidebar — the agent wallet is created and auto-funded with devnet SOL
2. In the empty chat area, click the green DeFi Explorer demo card
3. Watch the Activity Feed (bottom of page) stream live tool calls and transaction signatures in real time
4. Click any transaction signature → opens directly in Solana Explorer on devnet (every TX is a clickable link to the explorer)

Gasless Transactions (Optional — Kora Paymaster)

To enable gasless transactions where agents don't need SOL for fees:

# 1. Start the Kora paymaster server (requires Rust toolchain or Docker)
cd ../kora_server && chmod +x setup.sh && ./setup.sh

# 2. Add to .env
KORA_ENDPOINT=http://localhost:8080
KORA_FEE_MODE=sponsored

See kora_server/README.md for full setup details.

CLI Mode

pnpm cli

Features

Autonomous Agent Wallet (C1)

• Turnkey-backed wallet creation — BIP-32 HD sub-accounts derived from user's Turnkey wallet, hardware-backed key custody
• No keys in memory — private keys never leave the Turnkey secure enclave; signing happens server-side via Turnkey API
• Automatic transaction signing — no human approval required; agent signs and submits
• 93 DeFi tools via Solana Agent Kit v2 (TokenPlugin + DefiPlugin)
• Multi-step tool chaining — up to 10 sequential tool calls per LLM request
• Natural language → on-chain execution — "swap 0.1 SOL for USDC" → Jupiter swap tx
• Real-time SSE activity feed — live streaming of every tool call, tx signature, and balance change as they happen
• Scheduled & recurring payments — schedule future SOL transfers or set up daily/weekly/monthly recurring payments, all persisted to DB and auto-executed by the scheduler
• One-click demo mode — 3 pre-built autonomous DeFi scenarios; spawns wallet, funds it, and executes while you watch
• Portfolio view — aggregate SOL + SPL holdings across all agent wallets with USD values (Jupiter Price API)
• Transaction analytics dashboard — success/failure rates, SOL spent, tool usage charts, hourly timeline
• Security tab — dedicated sidebar panel with vault management, HMAC-chained audit log viewer with integrity verification, fleet health dashboard (grade distribution, agents needing attention), and per-wallet spending limits editor

Security & Key Management (C2)

3-layer defense-in-depth: Turnkey secure enclave → PDA vault → Kora gasless

• Turnkey secure enclave — hardware-backed key custody; private keys never leave the enclave, never exist in application memory. One HD wallet per user, BIP-32 sub-accounts per agent at m/44'/501'/{unixSeconds}'/0'
• PDA vault (on-chain) — Anchor program at Bm2NAhhpw1iopQqba8ywXi9NH27EmyyV62wddDfpjMoF enforces spending limits, program allowlists, and cooldowns at the Solana runtime level. Seeds: [b"vault", agent_pubkey]
• Kora gasless transactions — paymaster co-signing; agents transact without holding SOL for fees. Fee payer separation means agent keys never touch gas funds. Supports sponsored (free), margin, and fixed token fee modes. See kora_server/ for local setup
• HMAC-SHA256 request signing — every write/delete request signed with a derived key; replays blocked via 5-minute window
• Per-IP sliding-window rate limiting — 12 per-bucket presets; prevents API abuse and DoS
• Spending limits — configurable max SOL per-transaction and per-day per agent; blocks over-budget tool calls
• HMAC-chained audit log — append-only JSONL with each entry hashing the previous; tamper detection via verifyAuditIntegrity()
• Agent lifecycle enforcement — paused/terminated agents are blocked from executing at the API level (403 AGENT_NOT_ACTIVE)
• Input sanitization — HTML/XSS stripped from labels, wallet IDs validated by strict hex regex, JSON parse errors handled gracefully
• Jito MEV protection — bundle submission bypasses public mempool to prevent sandwich attacks (mainnet-beta only; devnet transactions use standard RPC submission)
• Agent isolation — separate wallet sub-account, RPC context, tx log, spending ledger, lifecycle state per agent

Documentation & Deep Dive (C3)

• Documentation set — 11-chapter architecture deep dive covering:
  • Wallet architecture & adapter pattern, cryptographic internals (Argon2id + scrypt KDFs)
  • Agent reasoning, multi-step tool chaining, 8-scope spend guard layer
  • PDA vault on-chain enforcement, Turnkey HSM integration, threat model
  • CLI reference, MCP/AI tools integration, Studio dashboard
  • Agent evolution (audit trails, memory, self-reflection), Kora gasless transactions
• BENCHMARK.md — Stress test results: 12 concurrent agents, 76 ops, 0% error rate, 1.8s total, wallet isolation proof, memory profile, extrapolation to 100+ agents
• SKILLS.md — Complete agent capability catalog (93 tools across 11 categories) for judges/agents to read
• VIDEO_SCRIPT.md — Structured 7-scene, 5-minute demo recording script
• DEMO.md — Judge-friendly walkthrough of all demo scripts

Multi-Agent Scalability (C4)

• Independent wallet isolation — each agent has its own keypair, RPC context, tx log, spending ledger, and lifecycle state; cryptographically verified (see BENCHMARK.md)
• Agent monitoring dashboard — live view of all agents: balance, status (idle/executing/error/paused/terminated), last action, daily spending bar, success rate
• Agent lifecycle management — pause, resume, or terminate agents with proper cleanup; terminated is terminal; transition history persisted
• Agent-to-agent transfers — one agent can send SOL or SPL tokens to another agent's wallet; lifecycle and spending checks enforced

UI/UX Polish

• Dark/light theme toggle — CSS variable system with localStorage persistence, FOUC-free SSR
• Loading skeletons — shimmer placeholders for wallet panel, portfolio, agent monitor, analytics
• Toast notifications — success/error/info toasts for every user action (wallet create, airdrop, backup, transfer, lifecycle transition)
• Copy-to-clipboard — animated clipboard → checkmark for wallet addresses, tx signatures, mint addresses
• Solana Explorer deep links — every tx signature and wallet address links to Solana Explorer with correct cluster
• Mobile responsive layout — tested on iOS (safe area insets, h-dvh, 16px input zoom prevention)

MCP Server (Model Context Protocol)

Expose all wallet and agent management tools to Claude Desktop, Cursor, or any MCP-compatible client.

# Start the MCP server
WALLET_ENCRYPTION_KEY=<key> pnpm mcp

Claude Desktop config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agentlili": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/agentlili",
      "env": {
        "WALLET_ENCRYPTION_KEY": "<your-key>",
        "SOLANA_RPC_URL": "https://api.devnet.solana.com"
      }
    }
  }
}

Tools across wallet operations, agent lifecycle management, spending & security controls, and portfolio analytics.

Guided prompts: portfolio overview, security audit, agent creation, fleet health check, and wallet investigation.

API Reference

All write/delete endpoints verify HMAC-SHA256 signatures when X-Signature header is present. All endpoints are rate-limited per-IP.

Interactive docs: GET /api/openapi returns the full OpenAPI 3.0 spec. Open /api-docs in the browser for Swagger UI (try any endpoint with one click).

Infrastructure

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/health | RPC status, wallet count, LLM provider info | | GET | /api/events | SSE stream of agent events (?walletId= for per-wallet filter) | | GET | /api/auth/signing-key | Fetch derived HMAC signing key for request authentication | | GET | /api/openapi | OpenAPI 3.0 specification (JSON) — import into Postman/Insomnia |

Wallets

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/wallet | List all wallets with labels | | POST | /api/wallet | Create wallet. Body: { "label": "name" } — auto-airdrops devnet SOL | | GET | /api/wallet/:id | Wallet details: SOL balance, SPL token list | | DELETE | /api/wallet/:id | Delete wallet and all associated data | | POST | /api/wallet/:id?action=airdrop | Request devnet SOL. Body: { "amount": 1 } | | GET | /api/wallet/:id/history | Paginated transaction history | | GET | /api/wallet/:id/limits | Get spending limits (maxPerTx, maxPerDay, dailySpent) | | PUT | /api/wallet/:id/limits | Update spending limits. Body: { "maxPerTx": 0.5, "maxPerDay": 2 } | | POST | /api/wallet/:id/backup | Export password-protected encrypted backup | | PUT | /api/wallet/:id/backup | Restore wallet from backup file + password | | POST | /api/wallet/:id?action=rekey | Re-encrypt wallet with fresh salt + IV (forward secrecy) |

Agents

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/agents | List all agents with SOL balances | | POST | /api/agents | Spawn agent. Body: { "label": "Bot Name" } — auto-airdrops | | POST | /api/agents/bulk | Batch-create up to 20 agents. Body: { "labels": ["Bot1", "Bot2"] } — returns array of walletIds | | GET | /api/agents/monitor | Full monitoring data. Params: ?status=active&limit=10 | | POST | /api/agents/transfer | Agent-to-agent transfer. Body: { "fromAgent", "toAgent", "amount", "mint?" } | | GET | /api/agents/:id/lifecycle | Get lifecycle state and transition history | | PUT | /api/agents/:id/lifecycle | Transition state. Body: { "state": "paused" \| "active" \| "terminated" } | | POST | /api/agents/:id/run | Trigger one autonomous execution cycle — no human prompt needed | | GET | /api/agents/health-summary | Aggregate security health across all agents: avg score, grade distribution, attention list |

Kora Gasless Transactions

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/kora/status | Kora paymaster status: enabled/disabled, fee mode, payer address, supported tokens | | POST | /api/kora/estimate | Estimate transaction fee. Body: { "transaction": "<base64>", "feeToken?": "<mint>" } |

Scheduler

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/cron/tick | Trigger scheduler tick. Auth: Bearer CRON_SECRET. Body: { "walletIds?": [...], "cluster?": "devnet", "dryRun?": false } |

Call this from any external scheduler (cron-job.org, GitHub Actions, systemd timer, etc.) to process scheduled payments and subscriptions. Supports wallet filtering and dry-run mode.

Chat & Operations

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/chat | Streaming chat (SSE). Body: { "messages": [...], "walletId": "abc" } | | GET | /api/demo | List available demo scenarios | | POST | /api/demo | Launch demo. Body: { "scenarioId": "defi-explorer" } | | GET | /api/portfolio | Aggregate portfolio: total USD value, per-wallet holdings, allocation | | GET | /api/analytics | Usage analytics. Params: ?walletId=&hours=24 | | GET | /api/audit | Audit log. Params: ?action=&walletId=&verify=true&limit=50&offset=0 |

Multi-Agent Example

# Spawn two independent agents
curl -X POST localhost:3000/api/agents \
  -H 'Content-Type: application/json' \
  -d '{"label": "Trading Bot"}'
# → { "walletId": "abc123", "publicKey": "..." }

curl -X POST localhost:3000/api/agents \
  -H 'Content-Type: application/json' \
  -d '{"label": "LP Manager"}'
# → { "walletId": "def456", "publicKey": "..." }

# Each agent operates independently with full isolation
curl -X POST localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"walletId": "abc123", "messages": [{"role":"user","content":"Check my balance and swap 0.05 SOL for USDC"}]}'

curl -X POST localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"walletId": "def456", "messages": [{"role":"user","content":"Stake 0.1 SOL via Jupiter"}]}'

# Agent-to-agent transfer
curl -X POST localhost:3000/api/agents/transfer \
  -H 'Content-Type: application/json' \
  -d '{"fromAgent": "abc123", "toAgent": "def456", "amount": 0.01}'

# Pause a misbehaving agent
curl -X PUT localhost:3000/api/agents/abc123/lifecycle \
  -H 'Content-Type: application/json' \
  -d '{"state": "paused"}'

# Monitor all agents
curl localhost:3000/api/agents/monitor

Demo Mode

Three pre-built autonomous scenarios launch with one click (UI or API):

| Scenario | Description | |----------|-------------| | defi-explorer | Check balance, fetch SOL price, swap to USDC, summarize portfolio | | multi-protocol | Diversify across staking, swaps, and liquidity provision | | trading-bot | Market analysis, conditional trades, position reporting |

# List scenarios
curl localhost:3000/api/demo

# Launch a scenario (creates wallet, airdrops, returns prompt)
curl -X POST localhost:3000/api/demo \
  -H 'Content-Type: application/json' \
  -d '{"scenarioId": "trading-bot"}'

Test Suite

# Unit tests
pnpm test

# On-chain tests against Surfpool (requires Surfpool on localhost:8899)
pnpm test:surfpool

# Integration tests against devnet (requires RUN_INTEGRATION=1)
pnpm test:integration

# Type check only
pnpm typecheck

# Production build
pnpm build

Tests run via pnpm test (unit) and pnpm test:surfpool (on-chain). See CLAUDE.md for full test runner details and Surfpool cheatcodes.

Security

See Security & Threat Model for the full threat model. Key properties:

| Property | Implementation | |----------|----------------| | Key custody | Turnkey secure enclave — hardware-backed, keys never in application memory | | Wallet derivation | BIP-32 HD wallet; per-agent sub-accounts at m/44'/501'/{unixSeconds}'/0' | | On-chain enforcement | PDA vault (Anchor program) — spending limits, program allowlists, cooldowns | | Gasless transactions | Kora paymaster co-signs as fee payer; agents don't need SOL for gas | | API authentication | HMAC-SHA256 + 5-minute replay window | | Rate limiting | Per-IP sliding window, 12 per-bucket presets | | Spending controls | Configurable per-tx + per-day SOL caps, enforced server-side + on-chain | | Audit trail | HMAC-SHA256 integrity chain, append-only JSONL | | Agent isolation | Separate wallet sub-account, RPC context, ledger, lifecycle state per agent | | Path traversal | Wallet IDs validated as 8-char hex by strict regex before any file I/O | | XSS prevention | HTML stripped from all user-supplied labels |

Tech Stack

| Layer | Technology | |-------|-----------| | Framework | Next.js 15 (App Router) | | AI | Vercel AI SDK 4 (streamText, useChat, maxSteps: 10) | | Solana | solana-agent-kit 2.0 — TokenPlugin (26 tools) + DefiPlugin (70 tools) | | Key Custody | Turnkey secure enclave — hardware-backed HD wallet, BIP-32 sub-accounts | | Gasless Txs | Kora paymaster — fee payer co-signing, token fee abstraction | | On-chain | Anchor program — agent_vault (PDA vault: spending limits, program allowlists) | | UI | React 19, Tailwind CSS 4, pure SVG charts | | Testing | Vitest (unit), Playwright (E2E), @vitest/coverage-v8 | | CI/CD | GitHub Actions — lint, test, typecheck, build, E2E | | Runtime | Node.js 22, pnpm 9 |

Documentation

| File | Contents | |------|----------| | DEMO.md | Judge-friendly demo walkthrough (start here) | | Docs set | 11-chapter architecture deep dive with diagrams | | Threat Model | Threat model, cryptographic inventory, attack surface map | | BENCHMARK.md | Stress test: 12 agents, 76 ops, 0% errors, 1.8s, isolation proof | | SKILLS.md | Complete agent capability catalog (93 tools, for agents to read) | | VIDEO_SCRIPT.md | 7-scene, 5-minute demo recording script | | /api/openapi | OpenAPI 3.0 JSON spec — import into Postman/Insomnia | | /api-docs | Interactive Swagger UI — try all 18 endpoints in the browser |