AI Agents on Orca

How to build autonomous agents that manage liquidity positions and execute swaps on Orca using the Whirlpools SDK.

AI Agents on Orca

Orca’s Whirlpools SDK is designed for programmatic use — making it well-suited for autonomous agents that manage LP positions, execute swaps, or monitor pool conditions without human intervention.

This page covers the key patterns for building an agent on top of Orca.

Why Orca for Agents

• MCP server — native tool-use access to all Orca docs at https://docs.orca.so/mcp
• Full SDK coverage — open, monitor, harvest, and close positions in a single SDK call each
• REST API — read pool and token data without a wallet or on-chain connection
• Deterministic quoting — get exact expected output amounts before submitting any transaction
• Multi-network — works on Solana Mainnet and Solana Devnet

Using the Orca MCP Server

Orca exposes a live MCP server that any agent framework can connect to for real-time documentation search. The server provides a SearchOrcaDocumentation tool — useful for grounding agent decisions with protocol knowledge at runtime.

MCP server URL: https://docs.orca.so/mcp

Add it to Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "orca-docs": {
      "url": "https://docs.orca.so/mcp"
    }
  }
}

Or call it programmatically from inside an agent:

// Example: agent queries Orca docs before executing a swap decision
const response = await fetch('https://docs.orca.so/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'SearchOrcaDocumentation',
      arguments: { query: 'what fee tier should I use for a SOL-USDC pool' }
    },
    id: 1
  })
});
const { result } = await response.json();
// result.content[] contains title, link, and content excerpts

See LLM & AI Access for full MCP setup instructions.

The Minimal Agent Loop

A minimal autonomous LP management agent:

1. Fetch pool state       → current price, tick index, fee rate
2. Fetch wallet positions → in-range status, fees owed
3. Decide                 → harvest if fees > threshold; rebalance if out of range
4. Execute                → call harvest, close, and/or open position
5. Submit + repeat        → send transaction, wait for confirmation, loop on interval

The four SDK operations that power this loop:

Operation	SDK function	When to use
Read pool state	fetchWhirlpool(rpc, poolAddress)	Every loop iteration
Read positions	fetchPositionsForOwner(rpc, ownerAddress)	Every loop iteration
Harvest fees	harvestPosition(rpc, positionMint, wallet)	When fees exceed threshold
Rebalance	closePosition → openPosition	When position goes out of range

TypeScript Example (Kit SDK)

import {
  setWhirlpoolsConfig,
  fetchWhirlpool,
  fetchPositionsForOwner,
  harvestPosition,
  closePosition,
  openPosition,
} from '@orca-so/whirlpools';
import { createSolanaRpc, address } from '@solana/kit';

await setWhirlpoolsConfig('solanaMainnet');
const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');

// 1. Fetch pool state
const pool = await fetchWhirlpool(rpc, address('YOUR_POOL_ADDRESS'));

// 2. Fetch all positions for this wallet
const positions = await fetchPositionsForOwner(rpc, address('YOUR_WALLET_ADDRESS'));

for (const position of positions) {
  const isInRange =
    pool.data.tickCurrentIndex >= position.data.tickLowerIndex &&
    pool.data.tickCurrentIndex < position.data.tickUpperIndex;

  // 3. Harvest if fees exceed threshold
  const { feesQuote, callback: harvest } = await harvestPosition(
    rpc, position.positionMint, wallet
  );
  if (feesQuote.feeOwedA + feesQuote.feeOwedB > FEE_THRESHOLD) {
    await harvest();
  }

  // 4. Rebalance if out of range
  if (!isInRange) {
    const { callback: close } = await closePosition(rpc, position.positionMint, 100, wallet);
    await close();
    // Open a new position centered on current price
    const { callback: open } = await openPosition(
      rpc, address('YOUR_POOL_ADDRESS'), { liquidity: TARGET_LIQUIDITY },
      NEW_LOWER_PRICE, NEW_UPPER_PRICE, 100, wallet
    );
    await open();
  }
}

Python (REST API + whirlpool-essentials)

For Python-based agent frameworks (LangChain, CrewAI, custom loops):

import requests
from orca_whirlpool.context import WhirlpoolContext
from orca_whirlpool.utils import PriceMath, DecimalUtil

# Read-only pool monitoring — no wallet needed
def get_pool_state(pool_address: str) -> dict:
    response = requests.get(
        "https://api.orca.so/v2/solana/pools/search",
        params={"q": pool_address}
    )
    return response.json()

# On-chain execution — requires wallet
# See /developers/resources/python-devs for whirlpool-essentials setup

See Python Integration for the full on-chain execution pattern.

Agent Framework Integrations

Orca SDK functions are straightforward to wrap as tools in any agent framework:

LangChain / LangGraph

Wrap fetchWhirlpool and swap as @tool functions. Use the REST API for read-only tools that don’t require a wallet.

CrewAI

Define a WhirlpoolMonitorTool and SwapExecutorTool as CrewAI tools. Assign them to specialist agents in your crew.

Eliza (ai16z)

Register Orca SDK calls as Eliza actions. The REST API /pools/search endpoint works well for on-demand pool lookups.

Vercel AI SDK

Use tool() to define Orca operations as typed tools. Pair with streamText or generateText for natural language LP management.

Key SDK Pages

• Monitor Positions — fetch all positions, check in-range status and fees owed
• Execute a Swap — swap tokens programmatically
• Open Position — open a new CLMM or Splash Pool position
• Harvest Fees — collect accumulated fees without closing
• Close Position — collect fees, remove liquidity, burn NFT
• Monitor Pools — fetch pool state including current price
• Python Integration — Python patterns for agents and ML pipelines

Security Considerations

Never expose private keys in agent prompts, logs, environment variables visible to external services, or LLM context. Use a dedicated, isolated keypair for any automated agent with only the funds it needs to operate.

Additional recommendations:

• Simulate before submitting — use quote functions (swap, openPosition, closePosition) to verify expected outcomes before calling sendTx()
• Set slippage limits — always pass a slippageBps value; 100 (1%) is a reasonable default for most LP operations
• Use devnet first — the devnet test pool (SOL/devUSDC, tick spacing 8) is safe for end-to-end agent testing
• Handle errors gracefully — catch InvalidTickIndex (0x177a) and NotRentExempt (0x0); see the error reference