Orca Whirlpool Integration

Learn how to interact with Orca Whirlpools for concentrated liquidity

Interact with Orca’s Whirlpool protocol for concentrated liquidity positions. Manage positions, provide liquidity, and create pools with customizable price ranges.

1. Position Management

   • Create centered positions

   • Create single-sided positions

   • Close positions

   • Fetch position data

2. Liquidity Provision

   • Symmetric ranges

   • Custom price ranges

   • Single-token deposits

   • Multiple fee tiers

Copy

const result = await agent.methods.orcaOpenCenteredPositionWithLiquidity(
  new PublicKey("whirlpool-address"),
  500,                 // 5% range (±2.5%)
  new PublicKey("token-mint"),
  new Decimal(100)     // Amount to deposit
);

Copy

const result = await agent.methods.orcaOpenSingleSidedPosition(
  new PublicKey("whirlpool-address"),
  250,                 // 2.5% from current price
  500,                 // 5% width
  new PublicKey("token-mint"),
  new Decimal(100)     // Amount to deposit
);

Copy

const signature = await agent.methods.orcaClosePosition(
  new PublicKey("position-mint-address")
);

Copy

const positions = await agent.methods.orcaFetchPositions();

Copy

"Create a centered liquidity position with 5% range in SOL/USDC pool"

"Open a single-sided USDC position 2.5% above current price"

"Close my whirlpool position"

"Check all my active liquidity positions"

Copy

{
  "whirlpoolAddress": "whirlpool_address",
  "priceOffsetBps": 500,
  "inputTokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "inputAmount": 1000
}

Copy

{
  "whirlpoolAddress": "whirlpool_address",
  "distanceFromCurrentPriceBps": 250,
  "widthBps": 500,
  "inputTokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "inputAmount": 1000
}

Copy

const FEE_TIERS = {
  1: 1,    // 0.01% fee
  2: 2,    // 0.02% fee
  4: 4,    // 0.04% fee
  5: 8,    // 0.05% fee
  16: 16,  // 0.16% fee
  30: 64,  // 0.30% fee
  65: 96,  // 0.65% fee
  100: 128 // 1.00% fee
};

Copy

interface CenteredPositionParams {
  whirlpoolAddress: PublicKey;     // Pool address
  priceOffsetBps: number;          // Range width (one side)
  inputTokenMint: PublicKey;       // Deposit token
  inputAmount: Decimal;            // Amount to deposit
}

// Features
- Symmetric ranges around current price
- Automatic price calculation
- Slippage protection (1%)
- Token extension support

Copy

interface SingleSidedParams {
  whirlpoolAddress: PublicKey;     // Pool address
  distanceFromCurrentPriceBps: number; // Starting point
  widthBps: number;                // Range width
  inputTokenMint: PublicKey;       // Deposit token
  inputAmount: Decimal;            // Amount to deposit
}

// Features
- Custom price ranges
- Direction detection
- Tick initialization
- Automatic calculations

Copy

interface PositionInfo {
  whirlpoolAddress: string;
  positionInRange: boolean;
  distanceFromCenterBps: number;
}

// Available data
- Pool identification
- Range status
- Price metrics

Copy

try {
  const position = await agent.methods.orcaOpenCenteredPositionWithLiquidity(...);
} catch (error) {
  if (error.message.includes("slippage")) {
    // Handle price movement
  } else if (error.message.includes("liquidity")) {
    // Handle liquidity issues
  }
}

1. Position Creation

   • Monitor price ranges

   • Consider fee tiers

   • Verify token amounts

   • Check slippage

2. Range Selection

   • Analyze volatility

   • Consider trading volume

   • Monitor price trends

   • Balance risk/reward

3. Position Management

   • Monitor in-range status

   • Track fee earnings

   • Rebalance when needed

   • Plan exit strategy

4. Performance

   • Use price oracles

   • Batch transactions

   • Monitor gas costs

   • Handle timeouts

1. Price Range

   • Out of bounds

   • Too narrow

   • Asymmetric ranges

   • Price movement

2. Liquidity

   • Insufficient funds

   • Unbalanced tokens

   • High slippage

   • Pool constraints

3. Technical

   • Invalid addresses

   • Tick spacing

   • Transaction failure

   • RPC errors

• USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

• SOL: So11111111111111111111111111111111111111112

• ORCA: orcaEKTdK7LKz57vaAYr9QeNsVEPfiu6QeMU1kektZE

• USDT: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB

• orcaFetchPositions: Get position data

• orcaClosePosition: Close positions

• getBalance: Check token balances

• getTokenData: Get token information