🤖 Agentic Wallet SDK

A fully autonomous, AI-controlled Solana wallet — built for the DeFi Developer Challenge: Agentic Wallets for AI Agents on Superteam Earn.

Overview

The Agentic Wallet SDK is a production-grade Python library that enables an AI agent to autonomously control a Solana wallet with zero human intervention. The agent interprets natural language instructions, selects appropriate on-chain actions, validates them against configurable safety limits, executes transactions, and logs every decision — all in a tight ReAct (Reason → Act → Observe) loop.

User Instruction → LLM Brain → Safety Guard → Solana RPC / Jupiter DEX → Audit Log

---

Features

Category	Capabilities
Wallet Ops	Balance check, SOL transfers, token portfolio, transaction history, devnet airdrops
DeFi	Token swaps via Jupiter v6, real-time price feeds, slippage control
AI Brain	OpenRouter LLM (any model), ReAct multi-step reasoning, 8 native tools
Safety	Per-tx limits, daily caps, min balance floor, rate limiting, emergency stop, blacklists
Logging	Structured JSONL audit trail (actions, transactions, errors), color console output
Interface	Natural language CLI, REPL mode, Python SDK API, headless daemon

---

Architecture

agentic_wallet/
├── wallet.py        # Solana RPC: balances, transfers, airdrop, history
├── safety.py        # SafetyGuard: limits, blacklists, rate limits, emergency stop
├── logger.py        # Structured JSONL + color console logging
├── jupiter.py       # Jupiter DEX v6: quotes, swaps, price feeds
├── agent.py         # AgenticWallet: LLM ReAct brain + tool orchestration
├── cli.py           # Headless CLI + interactive REPL
├── demo.py          # Runnable demos (wallet / safety / prices / agent / full)
└── logs/            # Persistent JSONL audit logs

ReAct Loop

┌─────────────────────────────────────────────────┐
│              AgenticWallet.run(task)             │
│                                                  │
│  ┌──────────┐   tool_call    ┌────────────────┐  │
│  │  LLM     │ ─────────────► │  SafetyGuard   │  │
│  │ (OpenAI  │                │  check(action) │  │
│  │  compat) │ ◄── observe ── │       │        │  │
│  └──────────┘                │  ALLOW / DENY  │  │
│       │                      └───────┬────────┘  │
│       │ reasoning                   │ ALLOW      │
│       ▼                             ▼            │
│  ┌──────────┐                ┌────────────────┐  │
│  │  done()  │                │  Execute       │  │
│  └──────────┘                │  wallet.py /   │  │
│                              │  jupiter.py    │  │
│                              └────────────────┘  │
└─────────────────────────────────────────────────┘

---

Quick Start

1. Install dependencies

git clone https://github.com/TechnologicSingularity/agentic-wallet
cd agentic-wallet
pip install -r requirements.txt

2. Configure environment

cp .env.example .env
# Edit .env — set OPENROUTER_API_KEY at minimum

OPENROUTER_API_KEY=sk-or-your-key-here
SOLANA_NETWORK=devnet
KEYPAIR_PATH=/path/to/keypair.json   # optional: auto-generated if omitted
LLM_MODEL=anthropic/claude-3.5-haiku
MAX_SINGLE_TX_SOL=0.1
MAX_DAILY_SPEND_SOL=0.5

3. Run demos

# Demo wallet operations (no API key needed)
python demo.py --mode wallet

# Demo safety guardrails (no API key needed)
python demo.py --mode safety

# Demo Jupiter price feeds (no API key needed)
python demo.py --mode prices

# Demo full AI agent (requires OPENROUTER_API_KEY)
python demo.py --mode agent

# Run everything
python demo.py --mode full

4. CLI usage

# Single command
python cli.py "Check my balance and report SOL amount"
python cli.py "Get the current price of SOL and USDC"
python cli.py "Request a devnet airdrop of 1 SOL"

# Interactive REPL
python cli.py --interactive

# Custom network/model
python cli.py --network devnet --model openai/gpt-4o "Check safety status"

5. Python SDK

import asyncio
from agent import create_agent
from safety import SafetyConfig

async def main():
    # Create agent with devnet testing config
    agent = await create_agent(
        network="devnet",
        openrouter_api_key="sk-or-...",
    )

    # Natural language control — fully autonomous
    result = await agent.run("Check my balance then get SOL price in USD")
    print(result["summary"])

    # Custom safety limits for production
    from safety import SafetyConfig, SafetyGuard
    config = SafetyConfig(
        max_single_tx_sol=0.05,       # max 0.05 SOL per transfer
        max_single_swap_sol=0.1,      # max 0.1 SOL per swap
        max_daily_spend_sol=0.5,      # hard daily cap
        min_balance_floor_sol=0.05,   # always keep 0.05 SOL
        max_txns_per_hour=10,
        allow_transfers=True,
        allow_swaps=True,
        address_whitelist=set(),      # empty = all addresses allowed
        address_blacklist=set(),
    )

    await agent.close()

asyncio.run(main())

---

Safety Model

All transactions pass through SafetyGuard before execution. The LLM cannot bypass these checks.

Guard	Default (devnet)	Description
max_single_tx_sol	1.0 SOL	Per-transfer ceiling
max_single_swap_sol	0.5 SOL	Per-swap ceiling
max_daily_spend_sol	5.0 SOL	Rolling 24h cap
min_balance_floor_sol	0.01 SOL	Never drain wallet
max_txns_per_hour	20	Rate limiter
Address blacklist	—	Blocked destinations
Address whitelist	—	Allowlist-only mode
Emergency stop	Off	Kill switch

# Emergency kill switch
agent.safety.emergency_stop_activate()   # halt all transactions
agent.safety.emergency_stop_clear()      # resume

# Runtime blacklist update
agent.safety.add_to_blacklist("<address>")
agent.safety.remove_from_blacklist("<address>")

---

Agent Tools

The LLM selects from 8 native tools via OpenAI-compatible function calling:

Tool	Description
get_balance	SOL balance + full token portfolio
transfer_sol	Send SOL (safety-checked)
swap_tokens	Swap SOL → token via Jupiter v6
get_token_price	Live USD price from Jupiter Price API
get_transaction_history	Recent on-chain transactions
get_safety_status	Current limits, daily spend, rate counter
request_devnet_airdrop	Free devnet SOL for testing
done	Signal task completion with summary

---

Audit Logging

Every autonomous action is persisted to logs/:

logs/
├── actions.jsonl      # all agent actions + LLM decisions
├── transactions.jsonl # all on-chain transactions (success + failure)
└── errors.jsonl       # exceptions and safety denials

Sample transaction log entry:

{
  "timestamp": "2026-02-20T22:00:01Z",
  "agent_id": "agentic-wallet-v1",
  "level": "TX",
  "tx_type": "transfer",
  "from": "FgvkPMxK4iCddyBMEh2aZm3k1tgxu1B4Kah1AEGAQbru",
  "to": "GD9Dx84Rzr6qLJKoZqQFZn2Yzf1NyPFbQeSRZqU56f8z",
  "amount": 0.001,
  "token": "SOL",
  "signature": "4xK7...",
  "success": true
}

---

Supported Models (via OpenRouter)

Any OpenAI-compatible model with function calling support:

• anthropic/claude-3.5-haiku ← recommended (fast + cheap)
• anthropic/claude-3.5-sonnet
• openai/gpt-4o-mini
• openai/gpt-4o
• google/gemini-flash-1.5

---

Requirements

• Python 3.11+
• solana>=0.34.0 — Solana RPC client
• solders>=0.21.0 — Rust-based Solana primitives
• httpx>=0.27.0 — async HTTP (Jupiter API)
• openai>=1.40.0 — OpenRouter/OpenAI-compatible LLM
• python-dotenv>=1.0.0 — env config

---

License

MIT © 2026 Jordan Desilets (TechnologicSingularity)

---

Submission

Built for the Superteam Earn — DeFi Developer Challenge: Agentic Wallets for AI Agents
💰 Prize: $5,000 USDC
📅 Deadline: March 9, 2026
🔗 https://earn.superteam.fun