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:

Fetch pool state       → current price, tick index, fee rate
Fetch wallet positions → in-range status, fees owed
Decide                 → harvest if fees > threshold; rebalance if out of range
Execute                → call harvest, close, and/or open position
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, deployment)`	Every loop iteration
Harvest fees	`harvestPosition(positionMint, config)`	When fees exceed threshold
Rebalance	`closePosition` → `openConcentratedPosition`	When position goes out of range

TypeScript Example (Kit SDK)

import {
  setRpc,
  setPayerFromBytes,
  setDefaultFunder,
  fetchWhirlpool,
  fetchPositionsForOwner,
  harvestPosition,
  closePosition,
  openConcentratedPosition,
  WhirlpoolDeployment,
} from '@orca-so/whirlpools';
import { createSolanaRpc, address } from '@solana/kit';
import secret from "wallet.json";

await setRpc('https://api.mainnet-beta.solana.com');
const signer = await setPayerFromBytes(new Uint8Array(secret));
setDefaultFunder(signer.address);
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'), WhirlpoolDeployment.mainnet);

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(
    position.positionMint,
    { whirlpoolDeployment: WhirlpoolDeployment.mainnet },
  );
  if (feesQuote.feeOwedA + feesQuote.feeOwedB > FEE_THRESHOLD) {
    await harvest();
  }

  // 4. Rebalance if out of range
  if (!isInRange) {
    const { callback: close } = await closePosition(
      position.positionMint,
      {
        slippageToleranceBps: 100,
        whirlpoolDeployment: WhirlpoolDeployment.mainnet,
      },
    );
    await close();
    // Open a new position centered on current price
    const { callback: open } = await openConcentratedPosition(
      address('YOUR_POOL_ADDRESS'),
      { liquidity: TARGET_LIQUIDITY },
      NEW_LOWER_PRICE,
      NEW_UPPER_PRICE,
      {
        slippageToleranceBps: 100,
        withTokenMetadataExtension: true,
        whirlpoolDeployment: WhirlpoolDeployment.mainnet,
      },
    );
    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)

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, openConcentratedPosition, closePosition) to verify expected outcomes before calling sendTx()
Set slippage limits — always pass a slippageToleranceBps 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

General

Help & Support

Eclipse

AI & LLMs

Reference

AI Agents on Orca

AI Agents on Orca

Why Orca for Agents

Using the Orca MCP Server

The Minimal Agent Loop

TypeScript Example (Kit SDK)

Python (REST API + whirlpool-essentials)

Agent Framework Integrations

LangChain / LangGraph

CrewAI

Eliza (ai16z)

Vercel AI SDK

Key SDK Pages

Security Considerations

​AI Agents on Orca

​Why Orca for Agents

​Using the Orca MCP Server

​The Minimal Agent Loop

​TypeScript Example (Kit SDK)

​Python (REST API + whirlpool-essentials)

​Agent Framework Integrations

LangChain / LangGraph

CrewAI

Eliza (ai16z)

Vercel AI SDK

​Key SDK Pages

​Security Considerations

AI Agents on Orca

Why Orca for Agents

Using the Orca MCP Server

The Minimal Agent Loop

TypeScript Example (Kit SDK)

Python (REST API + whirlpool-essentials)

Agent Framework Integrations

Key SDK Pages

Security Considerations