REST API - Karen

Overview

Karen exposes a REST API that allows external applications and AI agents to manage Solana wallets, execute transactions, and interact with DeFi protocols over HTTP. The API is built with Express.js and includes:

API key management for secure access
Wallet operations (create, balance, transfer, swap)
DeFi integrations (token launch, staking, wrapped SOL)
Agent management (create, start/stop, chat with AI agents)
Transaction history and audit logs

Base URL: http://localhost:3001 (configurable via API_PORT env var)

Quick Start

Start the API server

karen server start --port 3001

Or using npm:

npm run server

You should see:

🚀 Karen API server running on http://localhost:3001
   Health: http://localhost:3001/api/v1/health

Set your API secret

The admin API secret is used to create API keys and manage agents.

.env

API_SECRET=your-secure-secret-here

Default: karen-dev-secret (change this in production!)

Test the health endpoint

curl http://localhost:3001/api/v1/health

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "solana": {
    "healthy": true,
    "network": "devnet",
    "slot": 123456789
  },
  "agents": {
    "total": 2,
    "running": 1
  }
}

Authentication

Karen uses two types of authentication:

Admin Authentication

Used for privileged operations (creating API keys, managing agents).

Authorization: Bearer YOUR_API_SECRET

Example:

curl -X POST http://localhost:3001/api/v1/keys \
  -H "Authorization: Bearer karen-dev-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "spendingLimitSol": 5}'

API Key Authentication

Used for wallet and transaction operations.

Authorization: Bearer sk-abc123...

Example:

curl http://localhost:3001/api/v1/wallets \
  -H "Authorization: Bearer sk-abc123..."

API keys are stored in memory. Restarting the server will invalidate all keys.

API Key Management

Create API Key

Generate a new API key with custom permissions and spending limits.

curl -X POST http://localhost:3001/api/v1/keys \
  -H "Authorization: Bearer karen-dev-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trading-bot",
    "permissions": ["read", "write"],
    "rateLimit": 10,
    "spendingLimitSol": 5
  }'

Request Body:

name

string

required

Human-readable name for the API key

permissions

array

default:"[\"read\", \"write\"]"

Array of permissions (currently not enforced)

rateLimit

number

default:"10"

Max requests per minute

spendingLimitSol

number

default:"5"

Max SOL spending per day

Response:

{
  "apiKey": "sk-550e8400e29b41d4a716446655440000",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "trading-bot"
}

List API Keys

curl http://localhost:3001/api/v1/keys \
  -H "Authorization: Bearer karen-dev-secret"

Response:

{
  "keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "trading-bot",
      "walletId": "660f9511-f3ac-52e5-b827-557766551111",
      "permissions": ["read", "write"],
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-15T12:45:00Z"
    }
  ]
}

Wallet Operations

Create Wallet

curl -X POST http://localhost:3001/api/v1/wallets \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-wallet"}'

Response:

{
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-wallet",
  "address": "7xKKzD8qHa...",
  "createdAt": "2024-01-15T10:30:00Z"
}

List Wallets

curl http://localhost:3001/api/v1/wallets \
  -H "Authorization: Bearer sk-abc123..."

Get Balance

curl http://localhost:3001/api/v1/wallets/550e8400-e29b-41d4-a716-446655440000/balance \
  -H "Authorization: Bearer sk-abc123..."

Response:

{
  "sol": 1.5,
  "tokens": [
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "uiBalance": "100.50",
      "rawBalance": "100500000"
    }
  ]
}

Transaction Operations

Transfer SOL

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/transfer \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "7xKKzD8qHa...",
    "amount": 0.5
  }'

Response:

{
  "id": "tx-550e8400-e29b-41d4-a716-446655440000",
  "type": "transfer_sol",
  "status": "confirmed",
  "signature": "5Kn8fGzXv...",
  "walletId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "to": "7xKKzD8qHa...",
    "amount": 0.5
  },
  "guardrailsApplied": ["spending_limit_check"],
  "timestamp": "2024-01-15T10:30:00Z"
}

Swap Tokens

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/swap \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "inputToken": "SOL",
    "outputToken": "USDC",
    "amount": 0.5,
    "slippageBps": 50
  }'

Response:

{
  "signature": "5Kn8fGzXv...",
  "inputAmount": 0.5,
  "outputAmount": 19.23,
  "priceImpact": 0.12
}

Request Airdrop (Devnet)

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/airdrop \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 2}'

Transaction History

curl "http://localhost:3001/api/v1/wallets/WALLET_ID/transactions?limit=20" \
  -H "Authorization: Bearer sk-abc123..."

DeFi Operations

Launch Token

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/launch-token \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Coin",
    "symbol": "AGT",
    "decimals": 9,
    "initialSupply": 1000000
  }'

Response:

{
  "name": "Agent Coin",
  "symbol": "AGT",
  "mint": "7xKKzD8qHa...",
  "decimals": 9,
  "supply": 1000000,
  "signature": "5Kn8fGzXv..."
}

Stake SOL

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/stake \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1.0,
    "validator": "BeachiopjxQxL7CaHNSZsynRdj6vY5vCeaTXGKqfCZTP"
  }'

List Stake Accounts

curl http://localhost:3001/api/v1/wallets/WALLET_ID/stakes \
  -H "Authorization: Bearer sk-abc123..."

Wrap/Unwrap SOL

curl -X POST http://localhost:3001/api/v1/wallets/WALLET_ID/wrap-sol \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 1.0}'

Agent Management

Create Agent

curl -X POST http://localhost:3001/api/v1/agents \
  -H "Authorization: Bearer karen-dev-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trader-bot",
    "strategy": "Buy low, sell high on SOL/USDC",
    "llmProvider": "openai",
    "loopIntervalMs": 30000,
    "maxSolPerTransaction": 2
  }'

List Agents

curl http://localhost:3001/api/v1/agents \
  -H "Authorization: Bearer sk-abc123..."

Start/Stop Agent

curl -X POST http://localhost:3001/api/v1/agents/AGENT_ID/start \
  -H "Authorization: Bearer karen-dev-secret"

Chat with Agent

curl -X POST http://localhost:3001/api/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer sk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your current balance?"}'

Response:

{
  "response": "I currently have 1.5 SOL and 100.50 USDC in my wallet."
}

Global Transaction Feed

Get all transactions across all wallets:

curl "http://localhost:3001/api/v1/transactions?limit=50" \
  -H "Authorization: Bearer sk-abc123..."

Error Handling

The API uses standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request (missing/invalid parameters)
`401`	Unauthorized (missing/invalid API key)
`404`	Resource not found (wallet/agent doesn’t exist)
`500`	Server error (transaction failed, guardrails blocked)

Error response format:

{
  "error": "Wallet not found"
}

Rate Limiting & Guardrails

All API requests are subject to:

API Key Rate Limit

Default: 10 requests per minute (configurable per key)

Transaction Guardrails

Max 2 SOL per transaction
Max 5 tx per minute
Daily spending limit (configurable per key)

Blocked transactions return status 500 with error message explaining the guardrail violation.

Full Endpoint Reference

For detailed parameter schemas and response formats, see:

API Reference

Complete endpoint documentation with request/response schemas

Next Steps

MCP Server

Integrate with Claude Desktop or OpenClaw

TypeScript SDK

Use Karen as a library in Node.js

Guardrails

Configure security policies

CLI

Command-line interface reference

Get Started

Core Concepts

Integration

Agent Skills

Development

​Overview

​Quick Start

​Authentication

​Admin Authentication

​API Key Authentication

​API Key Management

​Create API Key

​List API Keys

​Wallet Operations

​Create Wallet

​List Wallets

​Get Balance

​Transaction Operations

​Transfer SOL

​Swap Tokens

​Request Airdrop (Devnet)

​Transaction History

​DeFi Operations

​Launch Token

​Stake SOL

​List Stake Accounts

​Wrap/Unwrap SOL

​Agent Management

​Create Agent

​List Agents

​Start/Stop Agent

​Chat with Agent

​Global Transaction Feed

​Error Handling

​Rate Limiting & Guardrails

API Key Rate Limit

Transaction Guardrails

​Full Endpoint Reference

API Reference

​Next Steps

MCP Server

TypeScript SDK

Guardrails

CLI

Build docs developers (and LLMs) love

Overview

Quick Start

Authentication

Admin Authentication

API Key Authentication

API Key Management

Create API Key

List API Keys

Wallet Operations

Create Wallet

List Wallets

Get Balance

Transaction Operations

Transfer SOL

Swap Tokens

Request Airdrop (Devnet)

Transaction History

DeFi Operations

Launch Token

Stake SOL

List Stake Accounts

Wrap/Unwrap SOL

Agent Management

Create Agent

List Agents

Start/Stop Agent

Chat with Agent

Global Transaction Feed

Error Handling

Rate Limiting & Guardrails

Full Endpoint Reference

Next Steps