solana-agent-kit

Solana Agent Kit Development Guide

Build AI agents that autonomously execute 60+ Solana blockchain operations using SendAI's open-source toolkit. Compatible with LangChain, Vercel AI SDK, and Claude via MCP.

Overview

The Solana Agent Kit enables any AI model to:

• Deploy and manage tokens (SPL & Token-2022)
• Create and trade NFTs via Metaplex
• Execute DeFi operations (Jupiter, Raydium, Orca, Meteora)
• Stake SOL, bridge tokens, register domains
• Run in interactive or fully autonomous modes

Key Features

| Feature | Description | |---------|-------------| | 60+ Actions | Token, NFT, DeFi, staking, bridging operations | | Plugin Architecture | Modular - use only what you need | | Multi-Framework | LangChain, Vercel AI SDK, MCP, Eliza | | Model Agnostic | Works with OpenAI, Claude, Llama, Gemini | | Autonomous Mode | Hands-off execution with error recovery |

Quick Start

Installation

# Core package
npm install solana-agent-kit

# With plugins (recommended)
npm install solana-agent-kit \
  @solana-agent-kit/plugin-token \
  @solana-agent-kit/plugin-nft \
  @solana-agent-kit/plugin-defi \
  @solana-agent-kit/plugin-misc \
  @solana-agent-kit/plugin-blinks

Environment Setup

# .env file
OPENAI_API_KEY=your_openai_api_key
RPC_URL=https://api.mainnet-beta.solana.com  # or devnet
SOLANA_PRIVATE_KEY=your_base58_private_key

# Optional API keys for enhanced features
COINGECKO_API_KEY=your_coingecko_key
HELIUS_API_KEY=your_helius_key

Basic Agent Setup

import {
  SolanaAgentKit,
  createVercelAITools,
  KeypairWallet,
} from "solana-agent-kit";
import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";

// Import plugins
import TokenPlugin from "@solana-agent-kit/plugin-token";
import NFTPlugin from "@solana-agent-kit/plugin-nft";
import DefiPlugin from "@solana-agent-kit/plugin-defi";
import MiscPlugin from "@solana-agent-kit/plugin-misc";
import BlinksPlugin from "@solana-agent-kit/plugin-blinks";

// Create wallet from private key
const privateKey = bs58.decode(process.env.SOLANA_PRIVATE_KEY!);
const keypair = Keypair.fromSecretKey(privateKey);
const wallet = new KeypairWallet(keypair);

// Initialize agent with plugins
const agent = new SolanaAgentKit(
  wallet,
  process.env.RPC_URL!,
  {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
  }
)
  .use(TokenPlugin)
  .use(NFTPlugin)
  .use(DefiPlugin)
  .use(MiscPlugin)
  .use(BlinksPlugin);

// Create tools for AI framework
const tools = createVercelAITools(agent, agent.actions);

Plugins & Actions

Token Plugin (@solana-agent-kit/plugin-token)

| Action | Description | |--------|-------------| | deployToken | Deploy new SPL token or Token-2022 | | transfer | Transfer SOL or SPL tokens | | getBalance | Check token balances | | stake | Stake SOL via Jupiter/Solayer | | bridge | Bridge tokens via Wormhole | | rugCheck | Analyze token safety |

// Deploy a new token
const result = await agent.methods.deployToken({
  name: "My Token",
  symbol: "MTK",
  decimals: 9,
  initialSupply: 1000000,
});

// Transfer tokens
await agent.methods.transfer({
  to: "recipient_address",
  amount: 100,
  mint: "token_mint_address", // optional, defaults to SOL
});

// Check balance
const balance = await agent.methods.getBalance({
  tokenAddress: "token_mint_address", // optional
});

NFT Plugin (@solana-agent-kit/plugin-nft)

| Action | Description | |--------|-------------| | createCollection | Create NFT collection via Metaplex | | mintNFT | Mint NFT to collection | | listNFT | List NFT on marketplaces | | updateMetadata | Update NFT metadata |

// Create collection
const collection = await agent.methods.createCollection({
  name: "My Collection",
  symbol: "MYCOL",
  uri: "https://arweave.net/metadata.json",
});

// Mint NFT to collection
const nft = await agent.methods.mintNFT({
  collectionMint: collection.collectionAddress,
  name: "NFT #1",
  uri: "https://arweave.net/nft1.json",
});

DeFi Plugin (@solana-agent-kit/plugin-defi)

| Action | Description | |--------|-------------| | trade | Swap tokens via Jupiter | | createRaydiumPool | Create Raydium AMM pool | | createOrcaPool | Create Orca Whirlpool | | createMeteoraPool | Create Meteora DLMM pool | | limitOrder | Place limit order via Manifest | | lend | Lend assets via Lulo | | perpetualTrade | Trade perps via Adrena/Drift |

// Swap tokens via Jupiter
const swap = await agent.methods.trade({
  outputMint: "target_token_mint",
  inputAmount: 1.0,
  inputMint: "So11111111111111111111111111111111111111112", // SOL
  slippageBps: 50, // 0.5%
});

// Create Raydium CPMM pool
const pool = await agent.methods.createRaydiumCpmm({
  mintA: "token_a_mint",
  mintB: "token_b_mint",
  configId: "config_id",
  mintAAmount: 1000,
  mintBAmount: 1000,
});

Misc Plugin (@solana-agent-kit/plugin-misc)

| Action | Description | |--------|-------------| | airdrop | ZK-compressed airdrop via Helius | | getPrice | Get token price via CoinGecko | | registerDomain | Register .sol domain | | resolveDomain | Resolve domain to address | | getTPS | Get network TPS |

// Compressed airdrop (cost-efficient)
const airdrop = await agent.methods.sendCompressedAirdrop({
  mintAddress: "token_mint",
  amount: 100,
  recipients: ["addr1", "addr2", "addr3"],
  priorityFeeInLamports: 10000,
});

// Get token price
const price = await agent.methods.getPrice({
  tokenId: "solana", // CoinGecko ID
});

Blinks Plugin (@solana-agent-kit/plugin-blinks)

Execute Solana Actions/Blinks directly:

// Execute a Blink
const result = await agent.methods.executeBlink({
  blinkUrl: "https://example.com/blink",
  params: { /* blink-specific params */ },
});

Integration Patterns

LangChain Integration

import { SolanaAgentKit, createSolanaTools } from "solana-agent-kit";
import { ChatOpenAI } from "@langchain/openai";
import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { MemorySaver } from "@langchain/langgraph";
import { HumanMessage } from "@langchain/core/messages";

async function createLangChainAgent() {
  // Initialize LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo-preview",
    temperature: 0.7,
  });

  // Initialize Solana Agent Kit
  const solanaKit = new SolanaAgentKit(
    wallet,
    process.env.RPC_URL!,
    { OPENAI_API_KEY: process.env.OPENAI_API_KEY! }
  )
    .use(TokenPlugin)
    .use(DefiPlugin);

  // Create LangChain tools
  const tools = createSolanaTools(solanaKit);

  // Create agent with memory
  const memory = new MemorySaver();
  const agent = createReactAgent({
    llm,
    tools,
    checkpointSaver: memory,
  });

  return agent;
}

// Run agent
async function chat(agent: any, message: string) {
  const config = { configurable: { thread_id: "solana-agent" } };

  const stream = await agent.stream(
    { messages: [new HumanMessage(message)] },
    config
  );

  for await (const chunk of stream) {
    if ("agent" in chunk) {
      console.log(chunk.agent.messages[0].content);
    }
  }
}

Vercel AI SDK Integration

import { SolanaAgentKit, createVercelAITools } from "solana-agent-kit";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

async function runVercelAgent(prompt: string) {
  const agent = new SolanaAgentKit(wallet, rpcUrl, options)
    .use(TokenPlugin)
    .use(DefiPlugin);

  const tools = createVercelAITools(agent, agent.actions);

  const result = await generateText({
    model: openai("gpt-4-turbo"),
    tools,
    maxSteps: 10,
    prompt,
  });

  return result.text;
}

// Usage
const response = await runVercelAgent(
  "Swap 0.1 SOL for USDC using the best rate"
);

MCP Server for Claude

Install and configure the MCP server for Claude Desktop:

# Install globally
npm install -g solana-mcp

# Or run directly
npx solana-mcp

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "solana": {
      "command": "npx",
      "args": ["solana-mcp"],
      "env": {
        "RPC_URL": "https://api.mainnet-beta.solana.com",
        "SOLANA_PRIVATE_KEY": "your_base58_private_key",
        "OPENAI_API_KEY": "your_openai_key"
      }
    }
  }
}

Available MCP tools:

• GET_ASSET - Get token/asset info
• DEPLOY_TOKEN - Create new token
• GET_PRICE - Fetch token price
• WALLET_ADDRESS - Get wallet address
• BALANCE - Check balance
• TRANSFER - Send tokens
• MINT_NFT - Create NFT
• TRADE - Execute swap
• REQUEST_FUNDS - Get devnet SOL
• RESOLVE_DOMAIN - Lookup .sol domain
• GET_TPS - Network throughput

Autonomous Mode

Run agent in fully autonomous mode:

import { SolanaAgentKit } from "solana-agent-kit";

const agent = new SolanaAgentKit(wallet, rpcUrl, options)
  .use(TokenPlugin)
  .use(DefiPlugin);

// Configure autonomous behavior
const autonomousConfig = {
  intervalMs: 60000,        // Check every minute
  maxActions: 100,          // Max actions per session
  errorRecovery: true,      // Auto-retry on failures
  dryRun: false,            // Set true for testing
};

// Start autonomous loop
async function runAutonomous() {
  while (true) {
    try {
      // Agent decides what to do based on market conditions
      const decision = await agent.analyze({
        context: "Monitor my portfolio and rebalance if needed",
        constraints: [
          "Keep at least 1 SOL for gas",
          "Max 10% allocation per token",
        ],
      });

      if (decision.shouldAct) {
        await agent.execute(decision.action);
      }

      await sleep(autonomousConfig.intervalMs);
    } catch (error) {
      if (autonomousConfig.errorRecovery) {
        console.error("Error, recovering:", error);
        await sleep(5000);
      } else {
        throw error;
      }
    }
  }
}

Creating Custom Actions

Extend the agent with custom actions:

import { Action, Tool, SolanaAgentKit } from "solana-agent-kit";

// Define the Tool (tells LLM HOW to use it)
const myCustomTool: Tool = {
  name: "my_custom_action",
  description: "Does something custom on Solana",
  parameters: {
    type: "object",
    properties: {
      param1: {
        type: "string",
        description: "First parameter",
      },
      param2: {
        type: "number",
        description: "Second parameter",
      },
    },
    required: ["param1"],
  },
};

// Define the Action (tells agent WHEN and WHY to use it)
const myCustomAction: Action = {
  name: "my_custom_action",
  description: "Use this when you need to do something custom",
  similes: ["custom thing", "special operation"],
  examples: [
    {
      input: "Do the custom thing with value X",
      output: "Custom action executed with param1=X",
    },
  ],
  handler: async (agent: SolanaAgentKit, params: any) => {
    const { param1, param2 } = params;

    // Your custom logic here
    const connection = agent.connection;
    const wallet = agent.wallet;

    // Execute Solana operations...

    return {
      success: true,
      result: `Executed with ${param1}`,
    };
  },
};

// Register custom action
agent.registerAction(myCustomAction);
agent.registerTool(myCustomTool);

Best Practices

Security

1. Never expose private keys - Use environment variables
2. Use dedicated wallets - Separate agent wallet from main funds
3. Set spending limits - Implement max transaction amounts
4. Test on devnet first - Always test before mainnet
5. Audit agent actions - Log all operations

Performance

1. Use appropriate RPC - Helius, Triton for production
2. Batch operations - Combine related transactions
3. Handle rate limits - Implement backoff strategies
4. Cache when possible - Price feeds, token metadata

Agent Design

1. Limit plugin scope - Only load needed plugins (reduces hallucinations)
2. Provide clear context - Detailed prompts improve accuracy
3. Add constraints - Prevent unwanted actions
4. Monitor and iterate - Review agent decisions

Guidelines

• Always test on devnet before mainnet
• Set maximum transaction limits
• Monitor agent activity logs
• Use dedicated wallets for agents
• Implement proper error handling
• Keep private keys secure

Files in This Skill

solana-agent-kit/
├── SKILL.md                           # This file
├── resources/
│   ├── actions-reference.md           # Complete actions list
│   ├── plugins-guide.md               # Plugin deep dive
│   └── security-checklist.md          # Security best practices
├── examples/
│   ├── langchain/                     # LangChain integration
│   ├── vercel-ai/                     # Vercel AI SDK
│   ├── mcp-server/                    # Claude MCP setup
│   └── autonomous-agent/              # Autonomous patterns
├── templates/
│   └── agent-template.ts              # Starter template
└── docs/
    ├── custom-actions.md              # Creating custom actions
    └── troubleshooting.md             # Common issues

V2 Highlights

Version 2 represents a complete evolution of the toolkit with key improvements:

Plugin Architecture

V2 directly addresses two major V1 challenges:

1. Security: Input private key method wasn't 100% secure
2. Hallucinations: 100+ aggregate tools caused LLM confusion

The modular plugin system lets you install only what you need, reducing context bloat and hallucinations.

Embedded Wallet Support (New)

V2 integrates with secure wallet providers for enhanced security:

import { TurnkeyWallet, PrivyWallet } from "solana-agent-kit/wallets";

// Turnkey - fine-grained rules and policies
const turnkeyWallet = new TurnkeyWallet({
  organizationId: process.env.TURNKEY_ORG_ID,
  privateKeyId: process.env.TURNKEY_PRIVATE_KEY_ID,
});

// Privy - human-in-the-loop confirmation
const privyWallet = new PrivyWallet({
  appId: process.env.PRIVY_APP_ID,
  requireConfirmation: true,
});

// Initialize agent with secure wallet
const agent = new SolanaAgentKit(turnkeyWallet, rpcUrl, options)
  .use(TokenPlugin)
  .use(DefiPlugin);

Key V2 Benefits

| Feature | V1 | V2 | |---------|----|----| | Wallet Security | Private key input | Embedded wallets (Turnkey, Privy) | | Tool Loading | All 100+ tools | Plugin-based, load what you need | | LLM Context | Large, caused hallucinations | Minimal, focused context | | Human-in-loop | Not supported | Native with Privy |

Notes

• Solana Agent Kit is actively maintained (1,400+ commits, 800+ forks)
• V2 introduced plugin architecture (migration guide available)
• Python version available: solana-agent-kit-py
• MCP server enables Claude Desktop integration
• 100,000+ downloads, 1.6k+ GitHub stars
• Apache-2.0 licensed