Why Add Solana Tools to OpenClaw?
OpenClaw is an extensible AI agent gateway that lets you give your agents superpowers through plugins. By registering custom tools, you can let an agent interact with external systems — databases, APIs, blockchains — using structured JSON calls.
Adding Solana tools means your agent can check wallet balances, send SOL transfers, read on-chain accounts, and even call Anchor programs — all from natural language prompts. This turns OpenClaw into a powerful Web3 copilot.
Prerequisites
- Node.js 18+
- OpenClaw Gateway installed and running
- A Solana RPC endpoint (Helius, QuickNode, or
https://api.devnet.solana.com) @solana/web3.jsfor blockchain interactions
1. Project Structure
solana-openclaw-plugin/
├── openclaw.plugin.json
├── index.js
└── tools/
├── getBalance.js
└── sendTransfer.js
The plugin follows the standard OpenClaw layout: a manifest, an entry point, and a tools/ directory for each tool definition.
2. Plugin Manifest
Create openclaw.plugin.json in the plugin root:
{
"id": "solana-tools",
"name": "Solana Tools for OpenClaw",
"version": "1.0.0",
"description": "Gives agents the ability to interact with the Solana blockchain — check balances, send transfers, and read accounts."
}OpenClaw discovers and loads your plugin using this manifest.
3. Define the Balance Tool
Create tools/getBalance.js:
import { Connection, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";
const connection = new Connection(
process.env.SOLANA_RPC_URL || "https://api.devnet.solana.com"
);
export const getBalance = {
name: "get_sol_balance",
description: "Get the SOL balance of a Solana wallet address",
parameters: {
type: "object",
properties: {
address: {
type: "string",
description: "The Solana wallet public key (base58)"
}
},
Key points:
name— Unique identifier insnake_case. The agent uses this to call the tool.description— Tells the agent what the tool does and when to use it.parameters— JSON Schema that validates the agent's input beforeexecuteruns.execute— Async function that performs the actual work and returns structured content.
4. Define the Transfer Tool
Create tools/sendTransfer.js:
import {
Connection,
PublicKey,
Keypair,
SystemProgram,
Transaction,
sendAndConfirmTransaction,
LAMPORTS_PER_SOL
} from "@solana/web3.js";
import bs58 from "bs58";
const connection = new Connection(
process.env.SOLANA_RPC_URL || "https://api.devnet.solana.com"
);
export const sendTransfer = {
name: "send_sol_transfer",
description: "Send SOL from the agent wallet to a recipient address",
parameters: {
type: "object"
The transfer tool uses a server-side keypair (AGENT_WALLET_SECRET_KEY). Never expose this key to the client. In production, use a dedicated hot wallet with limited funds and enforce transfer caps inside the execute function.
5. Plugin Entry Point
Wire everything together in index.js:
import { getBalance } from "./tools/getBalance.js";
import { sendTransfer } from "./tools/sendTransfer.js";
export default function register(api) {
// Always available — read-only, no risk
api.registerTool({
name: getBalance.name,
description: getBalance.description,
parameters: getBalance.parameters,
async execute(id, params) {
return getBalance.execute(id, params);
}
The balance tool is always enabled. The transfer tool is registered as optional because it moves funds — it must be explicitly allowed in the agent configuration.
Register read-only tools as always-on and write/transfer tools as optional. This follows the principle of least privilege and prevents accidental transactions.
6. Install the Plugin
# Install the plugin from your local directory
openclaw plugins install ./solana-openclaw-plugin
# Restart the gateway to pick up the new plugin
openclaw gateway restart7. Configure the Agent
Update your OpenClaw config to allow the Solana tools:
{
"agents": {
"list": [
{
"id": "main",
"tools": {
"allow": [
"get_sol_balance",
"send_sol_transfer"
]
}
}
]
}
}Since send_sol_transfer was registered as optional, it must appear in the tools.allow list or the agent will not be able to call it.
8. Environment Variables
Make sure the gateway has access to these environment variables:
SOLANA_RPC_URL=https://api.devnet.solana.com
AGENT_WALLET_SECRET_KEY=<base58-encoded-secret-key>For development, use Devnet and airdrop test SOL with solana airdrop 2. Never use Mainnet keys in a development or staging environment.
How It Works
User prompt → OpenClaw Agent → calls get_sol_balance tool
↓
Plugin execute()
↓
@solana/web3.js → Solana RPC
↓
Returns balance to Agent
↓
Agent responds to User
- OpenClaw loads plugins based on
openclaw.plugin.json. - Tools registered via
api.registerTool()are injected into the agent's toolset. - During a session, the agent decides which tool to call based on the user's prompt and the tool descriptions.
- The tool's
executefunction runs, interacts with Solana, and returns structured content. - The agent uses the result to formulate its response.
Going Further: Anchor Program Tools
You can extend this pattern to call any Anchor program. Here is a skeleton tool that reads a PDA account:
import { Connection, PublicKey } from "@solana/web3.js";
import { Program, AnchorProvider } from "@coral-xyz/anchor";
import idl from "./idl/my_program.json" assert { type: "json" };
const PROGRAM_ID = new PublicKey("YOUR_PROGRAM_ID");
export const readAccount = {
name: "read_program_account",
description: "Read data from an on-chain Anchor program account",
parameters: {
type: "object",
properties: {
seed: {
type
Register it the same way — api.registerTool() in your index.js.
Best Practices
| Concern | Recommendation |
|---|---|
| Security | Register transfer/write tools as optional. Enforce allowlists. |
| Key management | Use a dedicated hot wallet with limited funds. Rotate keys regularly. |
| Error handling | Always return { isError: true } on failure so the agent can retry or inform the user. |
| Rate limiting | Throttle RPC calls inside execute to avoid hitting provider limits. |
| Tool naming | Use snake_case. Avoid conflicts with built-in OpenClaw tools. |
| Idempotency | Read tools are safe to retry. For write tools, consider deduplication by tracking recent signatures. |
Wrapping Up
With a single OpenClaw plugin you can give AI agents full access to the Solana blockchain. The pattern is always the same: define a tool with a JSON Schema, implement execute, and register it with api.registerTool(). Start with read-only tools like balance checks, then graduate to transfers and program interactions as you build confidence in the security model.
Check out the Solana Web3.js docs and the Anchor documentation for more on the blockchain side, and the OpenClaw plugin docs for advanced registration patterns like middleware and tool chaining.