Quickstart

Get from zero to a running autonomous agent in 5 minutes. This guide will:

Create a Solana wallet
Fund it with devnet SOL
Create an AI agent with a trading strategy
Start the agent and watch it operate

This quickstart assumes you’ve already installed Karen. If not, see Installation first.

Step 1: Create a Wallet

Every agent needs a wallet to hold funds and sign transactions. Create one:

npx tsx src/cli/index.ts wallet create --name "my-agent-wallet"

Output:

✅ Wallet created:
   Name:    my-agent-wallet
   ID:      a1b2c3d4-e5f6-7890-abcd-ef1234567890
   Address: 7xKzL8QyJ9X3NpRqW5vU2TbM4cA6hF8sD1eG9oP2iB3k

Your wallet address will be different. Copy it - you’ll need it to view transactions on Solana Explorer.

How Wallets Work

Karen creates HD (Hierarchical Deterministic) wallets using BIP-44 derivation:

// src/core/wallet/wallet-manager.ts:72-77
if (opts.mnemonic) {
  info = await walletManager.createDerivedWallet(
    opts.name,
    opts.mnemonic,
    Number(opts.index),
  )

Wallets are encrypted with AES-256-GCM and stored in data/keystores/.

Step 2: Fund Your Wallet

Request devnet SOL from the faucet (up to 2 SOL per request):

npx tsx src/cli/index.ts wallet airdrop --name "my-agent-wallet" --amount 2

Output:

⏳ Requesting 2 SOL airdrop...
✅ Airdropped 2 SOL
   Signature: 5KzX9mP2wQ7vN3jL8sR4tB6yH1cF9eD2gT8oA5iU3kW7v...

Airdrops sometimes fail due to rate limiting. If it fails, wait 30 seconds and try again. Devnet faucets are free but rate-limited.

Check Your Balance

Verify the funds arrived:

npx tsx src/cli/index.ts wallet balance --name "my-agent-wallet"

Output:

💰 my-agent-wallet (7xKzL8QyJ9X3NpRqW5vU2TbM4cA6hF8sD1eG9oP2iB3k):

  SOL: 2.0000

Step 3: Create an AI Agent

Now create an autonomous agent with a trading strategy. The agent will:

Run every 30 seconds (configurable)
Observe wallet state and market conditions
Use an LLM (GPT-4o or Claude) to decide actions
Execute one skill per cycle (swap, transfer, stake, etc.)

npx tsx src/cli/index.ts agent create \
  --name "DCA-Bot" \
  --strategy "Buy USDC with 0.5 SOL every cycle when balance > 1 SOL. If balance drops below 0.5 SOL, request airdrop." \
  --llm openai \
  --max-per-tx 1 \
  --daily-limit 5

Command Options

Option	Description	Default
`--name`	Agent name (must be unique)	Required
`--strategy`	Natural language trading strategy	Required
`--llm`	LLM provider (`openai`, `anthropic`, `grok`, `gemini`)	`openai`
`--model`	Specific model (e.g., `gpt-4o`, `claude-3-5-sonnet-20241022`)	Provider default
`--interval`	Loop interval in milliseconds	`30000` (30s)
`--max-per-tx`	Max SOL per transaction	`2`
`--daily-limit`	Daily spending limit in SOL	`10`

Output:

✅ Agent created:
   Name:     DCA-Bot
   ID:       b2c3d4e5-f6a7-8901-bcde-f12345678901
   Wallet:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
   LLM:      openai (gpt-4o)
   Strategy: Buy USDC with 0.5 SOL every cycle when balance > 1 SOL...

   Start with: karen agent start --name DCA-Bot

How Agent Creation Works

The orchestrator creates the agent config and runtime:

// src/agent/orchestrator.ts:92-163
async createAgent(options: CreateAgentOptions): Promise<AgentConfig> {
  const agentId = uuidv4()

  // Create a wallet for this agent
  let walletInfo
  if (options.mnemonic && options.derivationIndex !== undefined) {
    walletInfo = await this.walletManager.createDerivedWallet(
      options.walletName || `${options.name}-wallet`,
      options.mnemonic,
      options.derivationIndex,
      ['agent', agentId],
    )
  } else {
    walletInfo = await this.walletManager.createWallet(
      options.walletName || `${options.name}-wallet`,
      ['agent', agentId],
    )
  }

  const config: AgentConfig = {
    id: agentId,
    name: options.name,
    walletId: walletInfo.id,
    llmProvider: rawProvider,
    llmModel: options.llmModel || defaultModel,
    strategy: options.strategy,
    guardrails: {
      ...DEFAULT_GUARDRAIL_CONFIG,
      maxSolPerTransaction: options.maxSolPerTransaction ?? DEFAULT_GUARDRAIL_CONFIG.maxSolPerTransaction,
      maxTransactionsPerMinute: options.maxTransactionsPerMinute ?? DEFAULT_GUARDRAIL_CONFIG.maxTransactionsPerMinute,
      dailySpendingLimitSol: options.dailySpendingLimitSol ?? DEFAULT_GUARDRAIL_CONFIG.dailySpendingLimitSol,
    },
    loopIntervalMs: options.loopIntervalMs || Number(process.env.AGENT_LOOP_INTERVAL_MS) || 30000,
    status: 'idle',
    createdAt: new Date().toISOString(),
  }

  // Create runtime with skills
  const skills = createDefaultSkillRegistry()
  const runtime = new AgentRuntime(config, this.walletManager, this.transactionEngine, this.logger, skills, this.memory)

  this.agents.set(agentId, runtime)
  this.configs.set(agentId, config)
  this.saveAgents()

  return config
}

Step 4: Start the Agent

Launch your agent. It will run continuously until you stop it:

npx tsx src/cli/index.ts agent start --name "DCA-Bot"

Output:

✅ Agent "DCA-Bot" started. It is now running autonomously.
   Loop interval: 30000ms
   Press Ctrl+C to stop.

The agent now enters its observe-think-act-remember loop:

Observe

Agent checks wallet balance, recent transactions, and on-chain state:

// src/agent/runtime.ts:227-266
private async observe(): Promise<Record<string, unknown>> {
  const balances = await this.walletManager.getBalances(this.config.walletId)
  const wallet = this.walletManager.getWallet(this.config.walletId)
  const recentTxs = this.transactionEngine.getTransactionHistory(
    this.config.walletId,
    5,
  )

  return {
    wallet: {
      name: wallet?.name,
      address: wallet?.publicKey,
    },
    balances: {
      sol: balances.sol,
      tokens: balances.tokens.map((t) => ({
        mint: t.mint,
        balance: t.uiBalance,
      })),
    },
    recentTransactions: recentTxs,
    cycle: this.cycle,
    timestamp: new Date().toISOString(),
  }
}

Think

LLM receives observations and strategy, then decides on an action:

// src/agent/runtime.ts:270-302
private async think(observations: Record<string, unknown>) {
  const systemPrompt = this.buildSystemPrompt()
  const recentMemory = this.memory.formatForContext(this.config.id, 10)

  const userMessage = `CURRENT STATE:\n${JSON.stringify(observations, null, 2)}\n\nRECENT MEMORY:\n${recentMemory}\n\nBased on your strategy and the current state, what would you like to do?`

  const messages: LLMMessage[] = [
    { role: 'system', content: systemPrompt },
    { role: 'user', content: userMessage },
  ]

  const tools = this.skills.getToolDefinitions()
  const response = await this.getLlm().chat(
    messages,
    tools,
    this.config.llmModel,
  )

  const action = response.toolCalls && response.toolCalls.length > 0
    ? response.toolCalls[0]
    : null

  return {
    reasoning: response.content || 'No explicit reasoning provided.',
    action,
    rawResponse: response.content,
  }
}

Act

Agent executes the chosen skill (e.g., swap, transfer, airdrop):

// src/agent/runtime.ts:306-320
private async act(action: SkillInvocation): Promise<string> {
  const context: SkillContext = {
    walletId: this.config.walletId,
    agentId: this.config.id,
    walletManager: this.walletManager,
    transactionEngine: this.transactionEngine,
    jupiter: this.jupiter,
    splToken: this.splToken,
    tokenLauncher: this.tokenLauncher,
    staking: this.staking,
    wrappedSol: this.wrappedSol,
  }

  return this.skills.execute(action.skill, action.params, context)
}

Remember

Decision is persisted to memory for future cycles:

// src/agent/runtime.ts:202-223
const decision: AgentDecision = {
  agentId: this.config.id,
  cycle: this.cycle,
  observations,
  reasoning,
  action,
  outcome,
  timestamp: new Date().toISOString(),
}

this.logger.logDecision(decision)
this.logger.logEvent({ type: 'agent:decision', data: decision })
this.memory.addMemory(this.config.id, {
  cycle: this.cycle,
  reasoning,
  action: action
    ? `${action.skill}(${JSON.stringify(action.params)})`
    : null,
  outcome,
  timestamp: new Date().toISOString(),
})

What to Expect

Your agent will:

First cycle: Check balance (2 SOL), decide to swap 0.5 SOL for USDC
Execute swap: Call Jupiter DEX, sign transaction, confirm on-chain
Log decision: Store reasoning and outcome in memory
Wait 30 seconds: Sleep until next cycle
Repeat: Continue trading based on strategy and market conditions

First swap may take 60-90 seconds due to:

Jupiter quote API response time
Transaction confirmation on devnet
RPC node latency

Subsequent cycles will be faster as connections warm up.

Step 5: Monitor Your Agent

While the agent runs, open a new terminal and check activity:

View Agent Status

npx tsx src/cli/index.ts agent list

Output:

🤖 Agents (1):

  DCA-Bot (b2c3d4e5...)
    Status:   running
    Wallet:   a1b2c3d4...
    LLM:      openai (gpt-4o)
    Strategy: Buy USDC with 0.5 SOL every cycle when balance > 1 SOL...
    Created:  2026-03-03T10:30:45.123Z

View Transaction History

npx tsx src/cli/index.ts tx list --wallet "my-agent-wallet" --limit 10

Output:

📋 Transactions (3):

  ✅ swap (5a1b2c3d...)
     Wallet: a1b2c3d4...
     Tx: 3kL9mN5pQ2wX7rV8tY4uB6hC1dE9fG2sA3oI5kW7v...
     Time: 2026-03-03T10:31:15.456Z

  ✅ airdrop (4z9y8x7w...)
     Wallet: a1b2c3d4...
     Tx: 2jH8lM4oP1vW6qT7sX3zA5gB9cD8eF1rA2nH4jV6u...
     Time: 2026-03-03T10:30:50.789Z

Check Wallet Balance

npx tsx src/cli/index.ts wallet balance --name "my-agent-wallet"

Output:

💰 my-agent-wallet (7xKzL8QyJ9X3NpRqW5vU2TbM4cA6hF8sD1eG9oP2iB3k):

  SOL: 1.4982

  Tokens:
    EPjFWdd5Au...USDC: 0.5 (6 decimals)

Stop the Agent

Press Ctrl+C in the agent terminal:

^C
🛑 All agents stopped.

Or stop from another terminal:

npx tsx src/cli/index.ts agent stop --name "DCA-Bot"

What’s Next?

Agent Skills

Explore all 17 skills your agent can use

API Integration

Connect external agents via REST API or MCP

Security Guardrails

Configure spending limits and program allowlists

Advanced Strategies

Write sophisticated trading strategies

Troubleshooting

Airdrop failed with 'rate limit exceeded'

Devnet faucets rate-limit requests. Wait 30 seconds and try again, or use a different RPC endpoint in .env:

SOLANA_RPC_URL=https://api.devnet.solana.com

Agent stuck on 'wait' skill

Check your LLM API key is valid and has credits. Enable debug logging:

DEBUG=karen:* npx tsx src/cli/index.ts agent start --name "DCA-Bot"

Swap failed with 'insufficient liquidity'

Not all tokens have devnet liquidity. Stick to major tokens:

SOL (native)
USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
USDT: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

Transaction blocked by guardrails

Check transaction logs for reason:

npx tsx src/cli/index.ts tx list --wallet "my-agent-wallet"

Adjust guardrails when creating agent:

--max-per-tx 5 --daily-limit 20

Get Started

Core Concepts

Integration

Agent Skills

Development

Quickstart

Quickstart

Step 1: Create a Wallet

How Wallets Work

Step 2: Fund Your Wallet

Check Your Balance

Step 3: Create an AI Agent

Command Options

How Agent Creation Works

Step 4: Start the Agent

What to Expect

Step 5: Monitor Your Agent

View Agent Status

View Transaction History

Check Wallet Balance

Stop the Agent

What’s Next?

Agent Skills

API Integration

Security Guardrails

Advanced Strategies

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Integration

Agent Skills

Development

​Quickstart

​Step 1: Create a Wallet

​How Wallets Work

​Step 2: Fund Your Wallet

​Check Your Balance

​Step 3: Create an AI Agent

​Command Options

​How Agent Creation Works

​Step 4: Start the Agent

​What to Expect

​Step 5: Monitor Your Agent

​View Agent Status

​View Transaction History

​Check Wallet Balance

​Stop the Agent

​What’s Next?

Agent Skills

API Integration

Security Guardrails

Advanced Strategies

​Troubleshooting

Build docs developers (and LLMs) love

Quickstart

Step 1: Create a Wallet

How Wallets Work

Step 2: Fund Your Wallet

Check Your Balance

Step 3: Create an AI Agent

Command Options

How Agent Creation Works

Step 4: Start the Agent

What to Expect

Step 5: Monitor Your Agent

View Agent Status

View Transaction History

Check Wallet Balance

Stop the Agent

What’s Next?

Troubleshooting