orca-lp

Orca LP

Read-only analysis of Orca Whirlpool pools on Solana, plus on-chain management of concentrated liquidity positions. Generates TypeScript that queries public APIs and (when given a keypair) can submit transactions through @orca-so/whirlpools-sdk.

Default workflow: run analytics and planning without a wallet. For writes, use a small dedicated wallet, the pinned dependencies from this package, a quote preview, and a --confirm run after checking pool/mint addresses, token amounts, and slippage.

APIs:

Use / Do Not Use

Use when:

Do not use when:

Triggers: find pools, scan pools, rank pools, compare pools, stable pools, pool stability, pool APR, pool fees, fee tier, fee tier comparison, best pool, ATR, LP range, tick range, range sizing, price range, range projection, Monte Carlo, yield, yield analysis, retrospective yield, consistency, price consistency, which pool should I LP in, is this pool safe, add liquidity, provide liquidity, remove liquidity, withdraw LP, LP position, open position, close position, increase liquidity, decrease liquidity, rebalance, concentrated liquidity, CLMM, collect fees, collect rewards, claim rewards, swap, quote, exit position, exit everything, sweep to SOL

Requirements

| Variable | Required for | Default | |----------|--------------|---------| | KEYPAIR_PATH | Any on-chain write (open / increase / decrease / collect / close / swap) | — | | SOLANA_RPC_URL | All write ops | https://api.mainnet-beta.solana.com |

Analytics and planning playbooks do not need a wallet. KEYPAIR_PATH points to a keypair that can sign transactions, so use a small dedicated wallet for write operations. Reserve ≥ 0.02 SOL in the wallet for rent + priority fees before any write operation. See Reserve math.

Write Workflow

For every write playbook:

Intent Router (first step)

| User intent | Playbook | First action | |---|---|---| | "Find / scan / rank pools" | Quick Ranking | GET /pools?orderBy=tvlUsdc | | "Compare fee tiers for X/Y" | Fee Tier Comparison | GET /pools/search?query=X/Y | | "Is this pool stable?" / "Which pools are safest?" | Stability Analysis | 6mo Beachhouse TVL + volume | | "What range should I use?" | Range Sizing | ATR(14d) on 6mo A/B price | | "Where could the price go?" / "Simulate the range" | Monte Carlo Projection | GBM sim from realized vol | | "What would I earn?" / "How much would $X have made?" | Retrospective Yield | Stable periods × feeRate × volume | | "Should I LP in X/Y?" (broad) | Start with Quick Ranking, escalate | See Escalation rules | | "Swap X for Y" / "Get a quote" | Swap (single-pool) or Swap (multi-hop) | Quote → preview → execute | | "Open an LP position on X/Y" | Open Position | Compute ticks, build quote, send | | "Open with only one token (usually SOL)" | Open from Single Token | Detect SOL side, probe LP, exact-output swap, then open | | "Add to my position" | Increase Liquidity | Refresh pool, re-quote, send | | "Take out some liquidity" | Decrease Liquidity | Partial-liquidity quote, send | | "Collect fees" / "Claim rewards" | Collect Fees + Rewards | Sync + collect in one tx | | "Close my position" | Close Position | Collect → drain → close (burns NFT) | | "My position is out of range" | Rebalance | Plan close + reopen; execute phases separately | | "Show my positions" | Fetch Positions | Scan both SPL programs for position NFTs | | "Exit everything and convert to SOL" | Exit Planning | Plan close/swap phases; execute separately |

Playbooks

Each playbook is standalone. Chain them as the user's question deepens — don't pre-run everything. Read-only playbooks (analytics + planning) need no wallet. Write playbooks (Swap, Open / Increase / Decrease / Collect / Close) require KEYPAIR_PATH and follow the Write Workflow.

Quick Ranking

Fee Tier Comparison

Stability Analysis

Range Sizing

Monte Carlo Projection

Retrospective Yield

Swap (single-pool) {#swap-single-pool}

const pool = await client.getPool(poolAddress);
await pool.refreshData(); // freshen cached state before quoting
const quote = await swapQuoteByInputToken(
  pool,
  inputMint,                         // e.g. SOL mint
  new BN(amountInBaseUnits),
  Percentage.fromFraction(1, 100),   // 1% slippage
  ORCA_WHIRLPOOL_PROGRAM_ID,
  ctx.fetcher,
);
console.log(Quote: ${quote.estimatedAmountIn} → ${quote.estimatedAmountOut});
const tx = await pool.swap(quote);
const sig = await sendWithRetry(tx, connection);

Swap (multi-hop via bridge token) {#swap-multi-hop}

// Leg 1: TOKEN → USDC
const leg1Pool = await client.getPool(tokenUsdcPool);
await leg1Pool.refreshData();
const leg1Quote = await swapQuoteByInputToken(
  leg1Pool, tokenMint, new BN(tokenAmount),
  Percentage.fromFraction(1, 100), ORCA_WHIRLPOOL_PROGRAM_ID, ctx.fetcher,
);
await sendWithRetry(await leg1Pool.swap(leg1Quote), connection);
// Leg 2: USDC → SOL (after leg 1 lands)
const leg2Pool = await client.getPool(solUsdcPool);
await leg2Pool.refreshData();
const usdcReceived = leg1Quote.estimatedAmountOut;
const leg2Quote = await swapQuoteByInputToken(
  leg2Pool, USDC_MINT, usdcReceived,
  Percentage.fromFraction(1, 100), ORCA_WHIRLPOOL_PROGRAM_ID, ctx.fetcher,
);
await sendWithRetry(await leg2Pool.swap(leg2Quote), connection);

Open Position

const pool = await client.getPool(poolAddress);
await pool.refreshData();
const data = pool.getData();
const decA = pool.getTokenAInfo().decimals;
const decB = pool.getTokenBInfo().decimals;
const price = PriceMath.sqrtPriceX64ToPrice(data.sqrtPrice, decA, decB);
const rangePct = 0.05; // ±5%
const ts = data.tickSpacing;
const rawLower = PriceMath.priceToTickIndex(new Decimal(price.toNumber() * (1 - rangePct)), decA, decB);
const rawUpper = PriceMath.priceToTickIndex(new Decimal(price.toNumber() * (1 + rangePct)), decA, decB);
const tickLower = Math.floor(rawLower / ts) * ts;
const tickUpper = Math.ceil(rawUpper / ts) * ts;
const tokenExtCtx = await TokenExtensionUtil.buildTokenExtensionContextForPool(
  ctx.fetcher, data.tokenMintA, data.tokenMintB,
);
// PriceDeviation returns matched tokenMaxA/B + minSqrtPrice/maxSqrtPrice bounds.
// Pass the quote directly to openPositionWithMetadata — no manual sqrt fields.
const quote = increaseLiquidityQuoteByInputTokenUsingPriceDeviation(
  data.tokenMintA,                    // input token
  new Decimal(depositAmount),
  tickLower, tickUpper,
  Percentage.fromFraction(1, 100),
  pool, tokenExtCtx,
);
const { positionMint, tx } = await pool.openPositionWithMetadata(tickLower, tickUpper, quote);
const sig = await sendWithRetry(tx, connection);
console.log(Position opened: ${positionMint.toBase58()} — tx ${sig});

Save positionMint for future operations.

Open Position from Single Token (swap-half-first) {#open-from-single-token}

import { swapQuoteByOutputToken } from "@orca-so/whirlpools-sdk";
const SOL_MINT = new PublicKey("So11111111111111111111111111111111111111112");
// 1. Detect which side SOL is on
const data = pool.getData();
const solIsA = data.tokenMintA.equals(SOL_MINT);
const solMint    = solIsA ? data.tokenMintA : data.tokenMintB;
const otherMint  = solIsA ? data.tokenMintB : data.tokenMintA;
const decSol     = solIsA ? decA : decB;
const decOther   = solIsA ? decB : decA;
// 2. Reserve gas + rent, split the rest half-to-A / half-to-B
const solBalance = await connection.getBalance(wallet.publicKey);
const solForDeposit = solBalance - 25_000_000;   // leave 0.025 SOL for rent + fees
const halfSolHuman = new Decimal(solForDeposit).div(10 ** decSol).div(2);
// 3. Probe: what does the LP quote want on the other side if we put half our SOL in?
const probe = increaseLiquidityQuoteByInputTokenUsingPriceDeviation(
  solMint, halfSolHuman,
  tickLower, tickUpper,
  Percentage.fromFraction(1, 100),
  pool, tokenExtCtx,
);
// Wallet must hold tokenMax (not tokenEst) — pick the Max on the non-SOL side.
const needOther = solIsA ? probe.tokenMaxB : probe.tokenMaxA;
// 4. Exact-output swap: get exactly needOther of the other token
const swapQuote = await swapQuoteByOutputToken(
  pool, otherMint, needOther,
  Percentage.fromFraction(1, 100),
  ORCA_WHIRLPOOL_PROGRAM_ID, ctx.fetcher,
);
// Budget check
const solNeededForSwap = swapQuote.otherAmountThreshold.toNumber();
const solForLPSide = (solIsA ? probe.tokenMaxA : probe.tokenMaxB).toNumber();
if (solNeededForSwap + solForLPSide + 20_000_000 > solBalance) {
  throw new Error(Not enough SOL: need ${(solNeededForSwap + solForLPSide) / 1e9} + ~0.02 for rent);
}
await sendWithRetry(await pool.swap(swapQuote), connection, 300_000);
// 5. Re-quote using the OTHER token as input — with 0.90× buffer
await pool.refreshData();
const receivedOther = DecimalUtil.fromBN(swapQuote.estimatedAmountOut, decOther);
const finalQuote = increaseLiquidityQuoteByInputTokenUsingPriceDeviation(
  otherMint, receivedOther.mul(0.90),
  tickLower, tickUpper,
  Percentage.fromFraction(1, 100),
  pool, tokenExtCtx,
);
const { positionMint, tx } = await pool.openPositionWithMetadata(tickLower, tickUpper, finalQuote);
await sendWithRetry(tx, connection, 600_000);

Increase Liquidity

const posPda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, positionMint).publicKey;
const position = await client.getPosition(posPda);
const pool = await client.getPool(position.getData().whirlpool);
await pool.refreshData();
const tokenExtCtx = await TokenExtensionUtil.buildTokenExtensionContextForPool(
  ctx.fetcher, pool.getData().tokenMintA, pool.getData().tokenMintB,
);
const quote = increaseLiquidityQuoteByInputTokenUsingPriceDeviation(
  pool.getData().tokenMintA,
  new Decimal(additionalAmount),
  position.getData().tickLowerIndex,
  position.getData().tickUpperIndex,
  Percentage.fromFraction(1, 100),
  pool, tokenExtCtx,
);
await sendWithRetry(await position.increaseLiquidity(quote), connection);

Decrease Liquidity

const posPda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, positionMint).publicKey;
const position = await client.getPosition(posPda);
const pool = await client.getPool(position.getData().whirlpool);
await pool.refreshData();
const tokenExtCtx = await TokenExtensionUtil.buildTokenExtensionContextForPool(
  ctx.fetcher, pool.getData().tokenMintA, pool.getData().tokenMintB,
);
const liquidity = position.getData().liquidity;
const amountToRemove = liquidity.muln(50).divn(100); // 50%
const quote = decreaseLiquidityQuoteByLiquidityWithParams({
  liquidity: amountToRemove,
  tickLowerIndex: position.getData().tickLowerIndex,
  tickUpperIndex: position.getData().tickUpperIndex,
  slippageTolerance: Percentage.fromFraction(1, 100),
  sqrtPrice: pool.getData().sqrtPrice,
  tickCurrentIndex: pool.getData().tickCurrentIndex,
  tokenExtensionCtx: tokenExtCtx,
});
await sendWithRetry(await position.decreaseLiquidity(quote), connection);

Collect Fees + Rewards

const posPda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, positionMint).publicKey;
const position = await client.getPosition(posPda);
// collectFees(true) syncs fee accounting and collects in one tx
await sendWithRetry(await position.collectFees(true), connection);
// collectRewards returns TransactionBuilder[] — iterate
const rewardTxs = await position.collectRewards(undefined, true);
for (const rtx of rewardTxs) await sendWithRetry(rtx, connection);

Close Position

const posPda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, positionMint).publicKey;
const position = await client.getPosition(posPda);
const pool = await client.getPool(position.getData().whirlpool);
await pool.refreshData();
// 1. Collect fees and rewards
await sendWithRetry(await position.collectFees(true), connection);
for (const rtx of await position.collectRewards(undefined, true)) await sendWithRetry(rtx, connection);
// 2. Drain liquidity to zero
if (!position.getData().liquidity.isZero()) {
  const tokenExtCtx = await TokenExtensionUtil.buildTokenExtensionContextForPool(
    ctx.fetcher, pool.getData().tokenMintA, pool.getData().tokenMintB,
  );
  const drainQuote = decreaseLiquidityQuoteByLiquidityWithParams({
    liquidity: position.getData().liquidity,
    tickLowerIndex: position.getData().tickLowerIndex,
    tickUpperIndex: position.getData().tickUpperIndex,
    slippageTolerance: Percentage.fromFraction(1, 100),
    sqrtPrice: pool.getData().sqrtPrice,
    tickCurrentIndex: pool.getData().tickCurrentIndex,
    tokenExtensionCtx: tokenExtCtx,
  });
  await sendWithRetry(await position.decreaseLiquidity(drainQuote), connection);
}
// 3. Close (burns NFT, refunds rent)
const closeTxs = await pool.closePosition(posPda, Percentage.fromFraction(1, 100));
for (const tx of closeTxs) await sendWithRetry(tx, connection);

Rebalance

Fetch Positions

import { TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID } from "@solana/spl-token";
// Scan both token programs — position NFTs can be minted under either
const [classic, t2022] = await Promise.all([
  connection.getParsedTokenAccountsByOwner(wallet.publicKey, { programId: TOKEN_PROGRAM_ID }),
  connection.getParsedTokenAccountsByOwner(wallet.publicKey, { programId: TOKEN_2022_PROGRAM_ID }),
]);
const nftMints = [...classic.value, ...t2022.value]
  .map(a => a.account.data.parsed.info)
  .filter(i => i.tokenAmount.decimals === 0 && i.tokenAmount.amount === "1")
  .map(i => new PublicKey(i.mint));
// PDAUtil.getPosition works for both classic and Token-2022 positions —
// the PDA seeds use the mint only, not the token program.
for (const mint of nftMints) {
  const pda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, mint).publicKey;
  try {
    const position = await client.getPosition(pda);
    // ... it's ours
  } catch {
    // not an Orca position; skip
  }
}

Exit Planning

Escalation & Reporting Rules

Escalation — save cycles:

Reporting — never skip:

Summary recommendations (when the user asks "so what should I do?"):

Dependencies

Use these package versions for the TypeScript examples. The SDK's API has changed shape across versions, and different releases may not export the functions used below (e.g. WhirlpoolContext.from signature changed; …UsingPriceDeviation only exists in @orca-so/whirlpools-sdk@>=0.18; @orca-so/whirlpools-sdk@0.20 requires @coral-xyz/anchor@~0.32.1).

Pinned versions:

| Package | Version | |---|---| | @solana/web3.js | 1.98.4 | | @coral-xyz/anchor | 0.32.1 | | bn.js | 5.2.3 | | decimal.js | 10.6.0 | | @orca-so/whirlpools-sdk | 0.20.0 | | @orca-so/common-sdk | 0.7.0 | | @solana/spl-token | 0.4.14 |

Sanity-check scripts before sending any tx: npx tsc --noEmit your-script.ts catches wrong API signatures and missing exports for free.

Whirlpool program ID: whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc (same on mainnet + devnet).

Setup

Every write operation starts with this block:

import { Connection, Keypair, PublicKey, ComputeBudgetProgram } from "@solana/web3.js";
import { Wallet } from "@coral-xyz/anchor";
import BN from "bn.js";
import { Decimal } from "decimal.js";
import {
  WhirlpoolContext, buildWhirlpoolClient, buildDefaultAccountFetcher,
  ORCA_WHIRLPOOL_PROGRAM_ID, PDAUtil, PriceMath, TokenExtensionUtil,
  swapQuoteByInputToken,
  increaseLiquidityQuoteByInputTokenUsingPriceDeviation,
  decreaseLiquidityQuoteByLiquidityWithParams,
} from "@orca-so/whirlpools-sdk";
import { Percentage, DecimalUtil } from "@orca-so/common-sdk";
import * as fs from "fs";
const KEYPAIR_PATH = process.env.KEYPAIR_PATH ?? (() => {
  throw new Error("KEYPAIR_PATH environment variable is required.");
})();
const CONFIRM = process.argv.includes("--confirm"); // require --confirm to broadcast
const connection = new Connection(process.env.SOLANA_RPC_URL!, "confirmed");
const keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(fs.readFileSync(KEYPAIR_PATH, "utf-8"))));
const wallet = new Wallet(keypair);
const fetcher = buildDefaultAccountFetcher(connection);
const ctx = WhirlpoolContext.from(connection, wallet, fetcher);
const client = buildWhirlpoolClient(ctx);

Reserve math

Keep ≥ 0.02 SOL in the wallet for rent + fees when opening or rebalancing positions (openPositionWithMetadata costs ~0.015 SOL rent before it's reclaimed on close; ATA creation is ~0.002 SOL each). Any write operation also needs SOL upfront even if rent is refunded after — refunds arrive when the tx lands.

Transaction Send Pattern

Every write operation uses this wrapper. It adapts the priority fee to current network load, retries on blockhash expiry, and verifies landing via signature status (because confirmTransaction can throw while the tx still lands):

import type { TransactionBuilder } from "@orca-so/common-sdk";
async function recommendedPriorityFee(conn: Connection): Promise {
  // p75 of recent prioritization fees; floor at 10k microLamports
  const recent = await conn.getRecentPrioritizationFees();
  if (recent.length === 0) return 10_000;
  const fees = recent.map(x => x.prioritizationFee).sort((a, b) => a - b);
  const p75 = fees[Math.floor(fees.length * 0.75)];
  return Math.max(10_000, p75);
}
async function sendWithRetry(
  txBuilder: TransactionBuilder,
  conn: Connection,
  computeUnits = 400_000,
): Promise {
  const microLamports = await recommendedPriorityFee(conn);
  txBuilder.prependInstruction({
    instructions: [
      ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnits }),
      ComputeBudgetProgram.setComputeUnitPrice({ microLamports }),
    ],
    cleanupInstructions: [],
    signers: [],
  });
  for (let attempt = 1; attempt <= 3; attempt++) {
    let sig: string;
    try {
      sig = await txBuilder.buildAndExecute();
    } catch (e: any) {
      if (attempt < 3 && /Blockhash|expired|BlockheightExceeded/i.test(e.message)) continue;
      throw e;
    }
    for (let i = 0; i < 30; i++) {
      const status = (await conn.getSignatureStatus(sig)).value;
      if (status?.err) throw new Error(Tx ${sig} failed: ${JSON.stringify(status.err)});
      if (status?.confirmationStatus === "confirmed" || status?.confirmationStatus === "finalized") return sig;
      await new Promise(r => setTimeout(r, 1000));
    }
    throw new Error(Tx ${sig} did not confirm within 30s);
  }
  throw new Error("unreachable");
}

Compute unit sizing per operation

| Operation | CU | |-----------|-----| | Swap (single-pool) | 300,000 | | Open position (with metadata) | 600,000 | | Increase / decrease liquidity | 400,000 | | Collect fees | 200,000 | | Close position (drain + close) | 500,000 | | Multi-instruction bundle (V2 close) | 800,000 |

Address Lookup Tables (ALTs)

Multi-hop swaps with 3+ pools can exceed the 1232-byte legacy transaction limit. Pool detail responses include addressLookupTable — fetch each ALT with connection.getAddressLookupTable(key), then compile the tx as V0:

import { TransactionMessage, VersionedTransaction } from "@solana/web3.js";
const alt = (await connection.getAddressLookupTable(altKey)).value!;
const { blockhash } = await connection.getLatestBlockhash();
const msg = new TransactionMessage({
  payerKey: wallet.publicKey,
  recentBlockhash: blockhash,
  instructions,
}).compileToV0Message([alt]);                  // single arg: ALT array
const tx = new VersionedTransaction(msg);
tx.sign([keypair]);
await connection.sendTransaction(tx);

CLMM Concepts

Tick spacing by fee tier

| Fee rate | Fee % | Tick spacing | Typical use | |----------|-------|-------------|-------------| | 1 | 0.0001% | 1 | Stablecoin pairs | | 100 | 0.01% | 1 | Tight stablecoin | | 400 | 0.04% | 4 | Major pairs (SOL/USDC) | | 3000 | 0.30% | 64 | Standard pairs | | 10000 | 1.00% | 128 | Volatile / exotic pairs |

Range strategies

| Strategy | Width | Best for | Rebalance | |----------|-------|----------|-----------| | Tight | ±2% | Stablecoin pairs | Rarely | | Medium | ±5% | Correlated (SOL/JitoSOL) | Weekly | | Wide | ±10% | Volatile (SOL/USDC) | Bi-weekly | | Full range | -443636 → 443636 | Set-and-forget | Never |

Tick conversion uses the SDK: PriceMath.priceToTickIndex(price, decA, decB) and PriceMath.tickIndexToPrice(tick, decA, decB). Align ticks: Math.floor(raw / tickSpacing) * tickSpacing for lower, Math.ceil(...) for upper.

Canonical bridge pools

For multi-hop routes and dust swaps, these are the deepest pools for common bridge pairs:

| Pair | Fee | Pool | |------|-----|------| | SOL/USDC | 0.04% | Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE | | USDC/USDT | 0.01% | 4fuUiYxTQ6QCrdSq9ouBYcTM7bqSwYTSyLueGZLTy4T4 | | SOL/JitoSOL | 0.01% | Hp53XEtt4S8SvPCXarsLSdGfZBuUr5mMmZmX2DRNXQKp | | SOL/USDT | 0.02% | FwewVm8u6tFPGewAyHmWAqad9hmF7mvqxK4mJ7iNqqGC | | cbBTC/WBTC | 0.01% | 4v8ufj8Hj7UvFgtofQJAtzUud5xomwZfEqfCTHZ4wM72 | | PYUSD/USDC | 0.01% | 9tXiuRRw7kbejLhZXtxDxYs2REe43uH2e7k1kocgdM9B | | USDG/USDC | 0.01% | 9RqDTfwCx2SgxsvKpspQHc38HUo3B6hRd3oR9JR966Ps |

For other pairs, discover via /pools/search?query=TOKEN/USDC.

Token-2022 Pools

Pools where at least one side (or the position NFT) uses the Token-2022 program need V2 instructions. The high-level SDK methods (pool.swap, position.collectFees, pool.closePosition, etc.) handle this internally — use them and it just works. Drop to raw instructions only if bundling custom flows.

Detect a mint's program:

const prog = (await connection.getAccountInfo(mint))!.owner;
// equals TOKEN_PROGRAM_ID or TOKEN_2022_PROGRAM_ID

V1 → V2 instruction map (raw-Anchor flows only):

| V1 | V2 (mixed / Token-2022) | |----|-------------------------| | collectFees | collectFeesV2 | | collectReward | collectRewardV2 | | increaseLiquidity | increaseLiquidityV2 | | decreaseLiquidity | decreaseLiquidityV2 | | swap | swapV2 |

V2 instructions take tokenProgramA, tokenProgramB, tokenMintA, tokenMintB, and memoProgram (MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr) accounts. ATA creation: pass the correct program per mint — createAssociatedTokenAccountIdempotentInstruction(payer, ata, owner, mint, tokenProgram).

Raw Anchor Fallback

The high-level helpers cover nearly everything. Drop to raw Anchor when:

Fetch accounts and build instructions directly:

const posPda = PDAUtil.getPosition(ORCA_WHIRLPOOL_PROGRAM_ID, positionMint).publicKey;
const position = await (ctx.program.account as any).position.fetch(posPda);
const pool = await (ctx.program.account as any).whirlpool.fetch(position.whirlpool);
const tokenProgA = (await connection.getAccountInfo(pool.tokenMintA))!.owner;
const tokenProgB = (await connection.getAccountInfo(pool.tokenMintB))!.owner;
// whirlpool (relations:[position]) and memoProgram (address-constrained)
// are auto-resolved by Anchor's typed builder — omit them from .accounts().
const ix = await ctx.program.methods
  .collectFeesV2(null)
  .accounts({
    positionAuthority: wallet.publicKey,
    position: posPda,
    positionTokenAccount,
    tokenMintA: pool.tokenMintA, tokenMintB: pool.tokenMintB,
    tokenOwnerAccountA, tokenOwnerAccountB,
    tokenVaultA: pool.tokenVaultA, tokenVaultB: pool.tokenVaultB,
    tokenProgramA: tokenProgA, tokenProgramB: tokenProgB,
  })
  .remainingAccounts([])
  .instruction();

Decode a program error code from the IDL:

import idl from "@orca-so/whirlpools-sdk/dist/artifacts/whirlpool.json" with { type: "json" };
const err = idl.errors.find((e: any) => e.code === parseInt("17b5", 16));
// { code: 6069, name: "PriceSlippageOutOfBounds", msg: "Price outside slippage bounds" }

See examples/close-position-anchor.md for a complete multi-instruction close using raw Anchor + V2.

Gotchas

Read before writing code. These bite agents who don't.

1. All numeric fields are strings

Both REST and Beachhouse return numeric values as JSON strings. Cast with Number() (TypeScript) or float() (Python) before math or comparisons.

2. A/B pool price ≠ USD price of base

For LP range analysis, use the pool ratio volumeQuote / volumeBase (B per A), not volumeBaseUsd / volumeBase (which is base-token USD price). Identical for USDC-quoted pools; divergent for LST pairs (SOL/JitoSOL), BTC pairs (cbBTC/WBTC), etc. See Two Different "Prices".

3. Beachhouse blocks default Python urllib User-Agent

Cloudflare returns 403 for the default urllib UA. Set a browser-like header:

import urllib.request
req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
data = json.loads(urllib.request.urlopen(req).read())

curl and Node fetch work without extra headers.

4. Beachhouse response is double-nested

response.data.data[] — outer data wraps the payload; inner data is the timeseries array. REST is single-nested: response.data[] or response.data..

5. priceDelta is NOT volatility

It's the net price change over the period. A choppy week ending flat shows priceDelta ≈ 0 despite high realized volatility. For actual volatility, use log returns on the A/B price from Beachhouse: stddev(ln(price[i]/price[i-1])).

6. Cross-asset USD conversion: divide, don't multiply

Pool price P = quote / base. For a pair like SOL/whETH where A=SOL, B=whETH, P ≈ 0.037 means "0.037 whETH per SOL". If you know SOL_USD, then whETH_USD = SOL_USD / P, NOT SOL_USD * P. Multiplying gives ~$3 for whETH instead of ~$2,275. Bites anyone doing HODL comparisons or USD-denominated MC projections on non-USDC pools.

7. Concentrated liquidity fee share scales with range width

A narrower position earns proportionally more fees per in-range day. Rough approximation: relative_fee_share ∝ 1 / width. Do NOT model concentrated LP fees as deposit/TVL × pool_fees — that's the full-range approximation and severely underestimates tight-range earnings (and overestimates if you assume a tight range earns the same as full-range). Calibrate against a baseline width (e.g. ±20% ≈ pool average) and scale from there.

8. This skill deliberately does not project LP yield

Retrospective Yield reports actual historical fee earnings during stable periods. Full LP-vs-HODL Monte Carlo with fee attribution requires deep CLMM math (liquidity-from-deposit inversion, active-liquidity attribution, concentration scaling) and is high-variance even when done correctly. If you build one, verify against a known baseline (e.g. the retrospective yield on a stablecoin pair) before reporting numbers.

Orca REST API Reference

Base: https://api.orca.so/v2/solana

Endpoints

| Path | Purpose | Response shape | |------|---------|----------------| | GET /pools | List pools. Params: orderBy=tvlUsdc\|volume24hUsdc, orderDirection=asc\|desc, limit | { data: [...pools] } | | GET /pools/search?query= | Search by pair or address | { data: [...pools] } | | GET /pools/{address} | Single pool detail | { data: {...pool} } | | GET /protocol | Protocol-wide stats (flat, no data wrapper) | { volume24hUsdc, fees24hUsdc, tvl } | | GET /tokens/search?query= | Token lookup | { data: [...tokens] } |

Pool Response Key Fields

address           - Pool address (string)
feeRate           - Fee in basis points × 100 (e.g. 300 = 0.03%)
price             - Current price as string
tvlUsdc           - TVL in USD as string
tickSpacing       - 1 (stables), 4 (majors), 64 (standard), 128 (volatile)
tokenA / tokenB   - { symbol, name, decimals, address }
tokenBalanceA/B   - Raw integer token balance (÷ 10^decimals)

Pool Stats (available on every pool)

Each pool has stats.24h, stats.7d, stats.30d:

volume             - Total volume in USD (string)
fees               - Total fees generated (string)
rewards            - Total reward emissions in USD (string)
yieldOverTvl       - Fee yield as fraction of TVL (e.g. 0.0019 = 0.19%)
volumeDelta        - Volume change vs previous period (24h and 7d only)
feesDelta          - Fees change rate (24h and 7d only)
tvlDelta           - TVL change rate (24h and 7d only)
priceDelta         - Price change rate (24h and 7d only)
yieldOverTvlDelta  - Yield change rate (24h and 7d only)

Beachhouse API Reference

Base: https://stats-api.mainnet.orca.so

Daily timeseries for up to 6 months. Coverage: top 50 pools by TVL. Use for realized volatility (VWAP log returns), ATR, historical range analysis, and retrospective yield.

Endpoints

GET /api/pools/{address}/tvl?time_from=&time_to=&type=1D

{ "data": { "data": [
  { "tvl": "1234567.89", "baseAmount": "500.5", "quoteAmount": "75000.0", "unixTime": 1700000000 }
] } }

GET /api/pools/{address}/volume?time_from=&time_to=&type=1D

{ "data": { "data": [
  { "totalVolumeUsd": "500000.0", "volumeBase": "3000.0", "volumeQuote": "450000.0",
    "volumeBaseUsd": "250000.0", "volumeQuoteUsd": "250000.0", "unixTime": 1700000000 }
] } }

Resolutions: 1H, 1D, 1W, 1M, 1Y. baseAmount and quoteAmount are human-readable (already decimal-adjusted). 6-month window: time_from = now - 180 * 86400, time_to = now.

Two Different "Prices" From Volume Data

| Formula | Meaning | Use when | |---------|---------|----------| | Number(volumeQuote) / Number(volumeBase) | A/B pool ratio — token B per token A (actual trade execution ratio) | Pool-internal price for in-range analysis, ATR of the pair, realized vol of the actual LP position. Correct for all pools, especially LST pairs (SOL/JitoSOL) and BTC wrapped pairs (cbBTC/WBTC). | | Number(volumeBaseUsd) / Number(volumeBase) | USD price of the base token | USD-denominated price context (e.g. "what was SOL worth each day"). For USDC-quoted pools these are identical; for LST/BTC pairs they diverge — USD price reflects the dollar value, not the pool ratio. |

For LP range sizing and in-range checking, always use volumeQuote / volumeBase. For "what was the price in USD" context, use volumeBaseUsd / volumeBase.

Snorkel API Reference

Base: https://pools-api.mainnet.orca.so

Read-only multi-hop swap quoting. Returns route splits across pools so you can pick the deepest path before executing each leg via the SDK.

GET /swap-quote?from=&to=&amount=&slippageBps=&amountIsInput=true

Required params: from (input mint), to (output mint), amount (base units), slippageBps, amountIsInput (true for exact-input, false for exact-output). Snorkel returns 400 missing field "from" if you use inputMint/outputMint — those are SDK names, not API names.

Response shape:

{ data: {
    request: { from, to, amount, amountIsInput, ... },
    swap:    { inputAmount, outputAmount, split: [ [ ...hops ] ] },
    num_measured, optimal_amount_deviation, price_impact
}, meta }

split is an array of routes; each route is an array of hops (pools chained sequentially). For single-route swaps, split.length === 1; for split routes (Snorkel sharded the input across pools), split.length > 1.

Rate limit: 429s on hot loops. Space iterated calls ≥ 200–500 ms. For single-pool quotes, swapQuoteByInputToken from the SDK avoids the API entirely.

Key Formulas

| Formula | Expression | |---------|------------| | Fee % | feeRate / 10000 (e.g. 400 → 0.04%) | | APR (7d) | Number(stats["7d"].yieldOverTvl) / 7 * 365 * 100 | | APR (30d) | Number(stats["30d"].yieldOverTvl) / 30 * 365 * 100 | | A/B pool price | Number(volumeQuote) / Number(volumeBase) | | USD price of base | Number(volumeBaseUsd) / Number(volumeBase) | | Realized volatility | stddev(ln(price[i]/price[i-1])) (A/B price for LP; USD price for market context) | | ATR (14d) | mean(|price[i] - price[i-1]|) over last 14 daily A/B prices | | Daily fees (pool) | Number(totalVolumeUsd) × (feeRate / 10000 / 100) | | Vol/TVL (24h) | Number(stats["24h"].volume) / Number(tvlUsdc) — higher = more active | | Daily earning (full-range approx) | deposit × Number(stats["7d"].yieldOverTvl) / 7 |

Common Token Mints

Token program is classic SPL (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA, shown as cls) unless marked T22 (TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb). For any mint not in this table, resolve dynamically with (await connection.getAccountInfo(mint))!.owner.

| Symbol | Decimals | Prog | Mint | |--------|----------|------|------| | SOL (wSOL) | 9 | cls | So11111111111111111111111111111111111111112 | | USDC | 6 | cls | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | | USDT | 6 | cls | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB | | ORCA | 6 | cls | orcaEKTdK7LKz57vaAYr9QeNsVEPfiu6QeMU1kektZE | | BONK | 5 | cls | DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 | | JitoSOL | 9 | cls | J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn | | JupSOL | 9 | cls | jupSoLaHXQiZZTSfEWMTRRgpnyFm8f6sZdosWBjx93v | | INF | 9 | cls | 5oVNBeEEQvYi1cX3ir8Dx5n1P7pdxydbGF2X4TxVusJm | | JUP | 6 | cls | JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN | | JLP | 6 | cls | 27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4 | | whETH | 8 | cls | 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs | | cbBTC | 8 | cls | cbbtcf3aa214zXHbiAZQwf4122FBYbraNdFqgw4iMij | | WBTC | 8 | cls | 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh | | xBTC | 8 | cls | CtzPWv73Sn1dMGVU3ZtLv9yWSyUAanBni19YWDaznnkn | | ZEC | 8 | cls | A7bdiYdS5GjqGFtxf17ppRHtDKPkkRqbKtR27dxvQXaS | | PYUSD | 6 | T22 | 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo | | USDG | 6 | T22 | 2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH | | CASH | 6 | T22 | CASHx9KJUStyftLFWGvEVf59SGeG9sh5FfcnZMVPCASH | | PUMP | 6 | T22 | pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn | | syrupUSDC | 6 | cls | AvZZF1YaZDziPY2RCK4oJrRVrbN3mTD9NL24hPeaZeUj | | hyUSD | 6 | cls | 5YMkXAYccHSGnHn9nob9xEvv6Pvka9DZWH7nTbotTu9E | | USX | 6 | cls | 6FrrzDk5mQARGc1TDYoyVnSyRdds1t4PbtohCD6p3tgG | | eUSX | 6 | cls | 3ThdFZQKM6kRyVGLG48kaPg5TRMhYMKY1iCRa9xop1WC | | ONyc | 9 | cls | 5Y8NV33Vv7WbnLfq3zBcKSdYPrk7g2KoiQoe7M2tcxp5 | | EURC | 6 | cls | HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr | | TRUMP | 6 | cls | 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN |

> Orca pools use the wSOL mint (So111…112) to represent SOL. Native SOL is the chain's native asset, not an SPL token — the SDK handles wrap/unwrap automatically.

Examples

| File | Description | |------|-------------| | scan-pools.md | Scan and rank top Orca pools by TVL | | pool-detail.md | Full breakdown of a single pool | | compare-fee-tiers.md | Compare fee tiers for a trading pair | | pair-discovery.md | Find all pools for a specific token | | stability-rankings.md | Rank pools by 6-month Beachhouse stability score | | lp-range-analysis.md | ATR-based LP range sizing from Beachhouse VWAP | | range-projection.md | Monte Carlo using Beachhouse realized volatility | | price-range-history.md | Historical price bands and containment | | yield-projection.md | Retrospective yield from Beachhouse volume and TVL | | monitor-pool.md | Real-time pool monitoring with price/TVL deltas | | open-position.md | Open a medium-range SOL/USDC position | | manage-position.md | Increase, decrease, close | | collect-fees.md | Collect fees and rewards | | close-position-anchor.md | Raw-Anchor close (Token-2022 safe) | | quote.md | Read-only swap quote via Snorkel | | swap.md | SDK-native swap |

Fresh Context

Treat referenced Orca docs, live API responses, and the pinned SDK's type definitions as the source of truth over this file. If the live response or SDK signatures diverge from examples here, follow live and surface the mismatch to the user. Re-fetch /pools/{address} or Beachhouse data per request — don't cache across unrelated queries. Re-fetch pool state with pool.refreshData() before any quote — never reuse cached sqrtPrice across unrelated operations.

| File | Description | |------|-------------| | scan-pools.md | Scan and rank top Orca pools by TVL | | pool-detail.md | Full breakdown of a single pool | | compare-fee-tiers.md | Compare fee tiers for a trading pair | | pair-discovery.md | Find all pools for a specific token | | stability-rankings.md | Rank pools by 6-month Beachhouse stability score | | lp-range-analysis.md | ATR-based LP range sizing from Beachhouse VWAP | | range-projection.md | Monte Carlo using Beachhouse realized volatility | | price-range-history.md | Historical price bands and containment | | yield-projection.md | Retrospective yield from Beachhouse volume and TVL | | monitor-pool.md | Real-time pool monitoring with price/TVL deltas | | open-position.md | Open a medium-range SOL/USDC position | | manage-position.md | Increase, decrease, close | | collect-fees.md | Collect fees and rewards | | close-position-anchor.md | Raw-Anchor close (Token-2022 safe) | | quote.md | Read-only swap quote via Snorkel | | swap.md | SDK-native swap |

Every write operation starts with this block:

import { Connection, Keypair, PublicKey, ComputeBudgetProgram } from "@solana/web3.js";
import { Wallet } from "@coral-xyz/anchor";
import BN from "bn.js";
import { Decimal } from "decimal.js";
import {
  WhirlpoolContext, buildWhirlpoolClient, buildDefaultAccountFetcher,
  ORCA_WHIRLPOOL_PROGRAM_ID, PDAUtil, PriceMath, TokenExtensionUtil,
  swapQuoteByInputToken,
  increaseLiquidityQuoteByInputTokenUsingPriceDeviation,
  decreaseLiquidityQuoteByLiquidityWithParams,
} from "@orca-so/whirlpools-sdk";
import { Percentage, DecimalUtil } from "@orca-so/common-sdk";
import * as fs from "fs";
const KEYPAIR_PATH = process.env.KEYPAIR_PATH ?? (() => {
  throw new Error("KEYPAIR_PATH environment variable is required.");
})();
const CONFIRM = process.argv.includes("--confirm"); // require --confirm to broadcast
const connection = new Connection(process.env.SOLANA_RPC_URL!, "confirmed");
const keypair = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(fs.readFileSync(KEYPAIR_PATH, "utf-8"))));
const wallet = new Wallet(keypair);
const fetcher = buildDefaultAccountFetcher(connection);
const ctx = WhirlpoolContext.from(connection, wallet, fetcher);
const client = buildWhirlpoolClient(ctx);

Reserve math

Keep ≥ 0.02 SOL in the wallet for rent + fees when opening or rebalancing positions (openPositionWithMetadata costs ~0.015 SOL rent before it's reclaimed on close; ATA creation is ~0.002 SOL each). Any write operation also needs SOL upfront even if rent is refunded after — refunds arrive when the tx lands.