Liquidating on Pluribus

Anyone can liquidate. No registration or allow-list exists. The only deployment is on Solana devnet, with mock tokens. Prices are written by the admin key, except for JitoSOL and JupSOL, which read live Pyth feeds.

Every figure below is a setting. The values in force are in Numbers on devnet.

When an account can be liquidated

An account can be liquidated when its debt is above its liquidation limit. The limit is the account's value in its worst crash scenario, after each asset's liquidation shock and liquidation cost.

The program's health view returns both numbers. The SDK simulates it, so nothing is sent or signed:

const health = await fetchHealth(program, d, owner);
const liquidatable = health.debt.gt(health.liquidationLimit);
FieldMeaning
debtwhat the account owes, with interest to now
liquidationLimitdebt above this can be liquidated
creditLimitthe most the owner may draw to
collateralValuesum of the positions at the oracle price, no shock
positionValue[5], positionPrice[5]per slot, in the order of credit.positions
positionUnclear[5]true while that position cannot be taken

Amounts are USDC with 6 decimals. fetchAllCredits(program) lists every credit account.

The four instructions

CollateralInstructionYou payYou receive
A token other than USDCliquidate(repay_amount)USDC, up to the close factor × debttokens worth your payment × (1 + bonus)
An Orca or Raydium liquidity positionliquidate_lp()its value ÷ (1 + bonus), in one paymentthe position NFT
A Meteora DLMM positiondlmm_liquidate(repay_amount)USDC, up to the close factor × debtthat share of every bin, worth your payment × (1 + bonus)
USDC in the accountrepay_from_collateral(amount)nothingnothing

The bonus is the collateral's own: liq_bonus_bps on a token's asset account, and lp_liq_bonus_bps on the base token's asset account for a liquidity position. Where that is 0, and wherever it is above the pool's liq_bonus_bps, the pool's applies.

The order

The program takes an account's positions in its own order. An instruction for a position that is not first fails with NotFirstInOrder, so simulate, and try the account's other positions when you get it.

  • Each position has a key: its value in the scenario that sets the account's liquidation limit ÷ its market value × (1 + its bonus). The lowest key goes first, since that sale costs the limit least per dollar of debt repaid.
  • Keys within 0.0001 of each other count as level, and either position can go.
  • USDC is outside the order: repay_from_collateral works at any point.
  • A position that cannot be handed over is stepped over: a tokenized stock around a split, a paused mint, a frozen or short vault. So is one worth nothing.
  • With the debt more than 10% above the liquidation limit there is no order, and any position can be taken.

liquidate

  • repay_amount is in USDC base units. Anything above the close factor × debt is cut down to it, so u64::MAX is valid.
  • You receive repay × (1 + bonus) ÷ price tokens, rounded down. The price is the one the health check used: the low end of the oracle's band.
  • When the position holds fewer tokens than that, you receive all of it and pay its value ÷ (1 + bonus), rounded up.
  • A position priced at 0 is handed over whole for no payment. This happens when a Token-2022 issuer has emptied the vault.
  • When a Token-2022 vault holds fewer tokens than the program's books, you receive your share: seized × vault ÷ booked. The price already reflects that.
  • SOL arrives as wSOL.
  • The USDC mint is refused with InvalidParams. Use repay_from_collateral.

liquidate_lp

  • It takes no amount. A position NFT cannot be split.
  • The payment is the position's value at the oracle price ÷ (1 + bonus), rounded up.
  • Up to the close factor × debt of it repays debt. The rest is deposited into the borrower's account as USDC collateral. You pay both parts.
  • You receive the NFT. Closing the position on Orca or Raydium is up to you.
  • The rent of the NFT's vault account goes to the borrower.
  • Raydium's admin can turn off decrease_liquidity for a pool, which would leave you holding an NFT you cannot redeem.

dlmm_liquidate

A Meteora position has no NFT and is sold in part, like a token.

  • repay_amount is in USDC base units and is cut down to the close factor × debt, so u64::MAX is valid.
  • The share taken is repay × (1 + bonus) ÷ value, at most 100%. You pay value × share ÷ (1 + bonus), rounded up.
  • The pool removes that share of every bin straight into your two token accounts. You receive the pair's real mix of tokens, which at the oracle price is worth at least what the position was valued at.
  • Sold whole, the position's unclaimed fees go with it, the position is closed and its rent returns to the borrower.
  • A position valued at nothing is handed over whole for no payment, so an empty one cannot keep bad debt from being written off.
  • A pair Meteora has disabled still lets liquidity out.
  • It needs a raised compute limit. The SDK builder sets one.

repay_from_collateral

  • It moves the account's own USDC collateral onto its debt, one for one.
  • Anyone can call it while the account is liquidatable, up to the close factor × debt per call.
  • It pays no bonus and costs only the transaction fee.

The health rule

Every liquidation must leave the margin between limit and debt no smaller:

debt_after + limit_before <= debt_before + limit_after

A liquidation that breaks it fails with HealthNotImproved.

What stops a liquidation

ErrorCause
NotLiquidatablethe debt is not above the liquidation limit
StalePricea price on any position of the account is older than that asset's liq_price_age_secs. One stale price blocks the whole account
PriceTooUncertainan oracle band is wider than the asset's max_conf_bps
PriceUnclearthe position is a tokenized stock around a split. The account's other positions can still be taken
NotFirstInOrderanother position of the account comes first, see The order
HealthNotImprovedthe health rule above
ZeroAmountthe repayment or the seized amount rounds to nothing
MissingAccount, AccountMismatchthe health-check accounts are incomplete or out of order
a token program errorthe collateral mint is paused or its vault frozen by the issuer

After a liquidation

  • The account returns to the base rate tier.
  • A Liquidated event carries account, liquidator, mint, kind (1 token, 2 liquidity position, 3 Meteora position), repaid, seized and the remaining debt. For a Meteora position seized is the share taken, in basis points of the position.
  • When no collateral is left and debt remains, the debt is written off at once. A BadDebt event shows how much the yield buffer, the reserve, the protocol fees and the junior tranche each absorbed.
  • An account whose debt is above the value of its collateral stays liquidatable after every step, until the collateral is gone.

Building the transaction

Each instruction takes the health-check accounts as remaining accounts, in the order of the account's position slots:

  • Token: its asset account. For a Token-2022 token, its mint and vault next. Then its price account, unless the asset is fixed at $1. For staked SOL, the SOL price account, and for a stake-pool backing the stake pool account.
  • Orca or Raydium liquidity position: the LP market, the position account on Orca or Raydium, the base asset, the base price account.
  • Meteora position: the LP market, the pair, the position account, the base asset, the base price account. The bin arrays the position covers come first, before all the health-check accounts.

The SDK builders ix.liquidate, ix.liquidateLp, ix.dlmmLiquidate and ix.repayFromCollateral add them, set a compute budget and create your token accounts. An account holds up to 16 positions, and the check walks every one: with all 16 full, a liquidation takes about 550k compute units, or about 1.06M for a Meteora position, so the builders ask for 1.4M.

Send a v0 transaction through the deployment's lookup table with buildTransaction. A legacy transaction for an account with several Token-2022, staking or liquidity positions passes the 1232-byte limit.

Example

Save as liquidate.ts in the repository root.

// takes one liquidation step on every account that is past its liquidation limit
import fs from "node:fs";
import { Connection, Keypair } from "@solana/web3.js";
import { type Deployment, KIND_DLMM, KIND_LP, MAX_U64, buildTransaction, decodeEvents, fetchAllCredits, fetchHealth, fetchPool, getProgram, ix } from "./sdk/index.ts";

const d: Deployment = JSON.parse(fs.readFileSync(`deployments/${process.env.CLUSTER ?? "devnet"}.json`, "utf8"));
const me = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(fs.readFileSync(process.env.KEYPAIR!, "utf8"))));
const connection = new Connection(process.env.RPC_URL ?? d.rpcUrl, "confirmed");
const program = getProgram(connection);
const pool = await fetchPool(program);

for (const { account: credit } of await fetchAllCredits(program)) {
  const owner = credit.owner;
  // one stale price fails the whole health check, and that account is skipped
  const health = await fetchHealth(program, d, owner).catch(() => null);
  if (!health || !health.debt.gt(health.liquidationLimit)) continue;

  // slots with kind 0 are empty, and a position with an unclear price cannot be taken yet
  const slot = credit.positions.findIndex((p, i) => p.kind !== 0 && !health.positionUnclear[i]);
  if (slot < 0) continue;
  const { kind, mint } = credit.positions[slot];
  const maxRepay = health.debt.muln(pool.params.closeFactorBps).divn(10_000);
  const ixs =
    kind === KIND_LP
      ? await ix.liquidateLp(program, d, me.publicKey, owner, mint)
      : kind === KIND_DLMM
        ? await ix.dlmmLiquidate(program, d, me.publicKey, owner, mint, maxRepay)
        : mint.toBase58() === d.usdcMint
            ? await ix.repayFromCollateral(program, d, me.publicKey, owner, MAX_U64)
            : await ix.liquidate(program, d, me.publicKey, owner, mint, maxRepay);

  const latest = await connection.getLatestBlockhash();
  const tx = await buildTransaction(connection, d, me.publicKey, ixs, latest.blockhash);
  tx.sign([me]);
  const signature = await connection.sendTransaction(tx);
  await connection.confirmTransaction({ signature, ...latest }, "confirmed");
  const sent = await connection.getTransaction(signature, { commitment: "confirmed", maxSupportedTransactionVersion: 0 });
  const events = decodeEvents(sent?.meta?.logMessages ?? []).map((e) => e.name);
  console.log(`${owner.toBase58()} ${signature} ${events.join(", ")}`);
}
CLUSTER=localnet KEYPAIR=~/.config/solana/id.json npx tsx liquidate.ts

Run twice on a local chain on 18 Nov 2026, against a borrower holding 50 NVDAx with $5,000 drawn, after the stock price was set from $180 to $100:

DebtLiquidation limitBorrower's NVDAxLiquidator's USDCLiquidator's NVDAx
Before$5,000.00$3,375.00506,000.000
After run 1$2,500.00$1,603.1323.753,500.0026.25
After run 2$1,250.00$717.1910.6252,250.0039.375

The reference keeper

keeper/index.ts is a working liquidator. Start it with npm run keeper.

VariableDefaultMeaning
CLUSTERread from RPC_URL, else localnetwhich deployments/<cluster>.json to load
RPC_URLthe deployment's rpcUrlRPC endpoint
KEEPER_KEYPAIR~/.config/solana/id.jsonsigner, and the wallet whose USDC pays
INTERVAL_MS5000time between passes
PREMIUM_INTERVAL_MS600000time between refreshes of an account that pays a risk premium
DRY_RUNunset1 logs each action and sends nothing

On each pass, for every account past its limit, it takes one step at a time:

  1. It nets the account's own USDC against the debt.
  2. It tries the token positions, largest first, then Orca and Raydium positions whole and part of a Meteora position. When the program answers NotFirstInOrder it moves on to the next one.

It skips a step when its USDC balance is short of the payment, and logs that. It also refreshes rate tiers, records volatility samples and pays the head of the senior withdrawal queue once the pool's cash covers it. It leaves LP fees to whoever collects them for the bounty. On a demo deployment it re-sends prices when it holds the admin key.

Numbers on devnet

As read from devnet on 20 Nov 2026. doc_and_refs/TUNES.md lists every setting with its allowed range. If this page and that file disagree, the file is right.

SettingValue
Liquidation bonus (liq_bonus_bps)SOL 1%, SOL liquidity positions 2%, NVDAx and AAPLx 5%, everything else the pool's 5%, which an asset's own bonus can only lower
Close factor (close_factor_bps)50% of the debt per transaction
Liquidation cost (liq_cost_bps)SOL 5%, staked SOL 6%, stocks 10%, BONK 15%, USDC 0%, liquidity positions 5%
Oldest price for a liquidation (liq_price_age_secs)1 day for JitoSOL and JupSOL; the demo prices of SOL, NVDAx, AAPLx and BONK do not expire
Widest oracle band (max_conf_bps)2%
Liquidation shockssee the shock table in users.md

The liquidation cost is the haircut the program takes for the cost of selling an asset. For stocks it is twice the bonus.

Mock USDC on devnet comes only from the team's faucet wallet.

AccountAddress
ProgramA4UnuBwwBLbvxj3AnUtCDzkj11kp1wdPh8CydUn5quc7
Lookup tableA9KAGTcNirqiHQePpGe1pgvjdJrKAS62PemxoZeiiENS
USDC (mock)75bxZeFLwNKqezhQ2KHhUASsuxVBJN31g9D8EuSuRW5U
NVDAx (mock)3mGpn5jTL25imzYaSNwUtthQ7cJgpMsJnXmf1vJf4Gij
AAPLx (mock, Token-2022)HDgRzeChz6fKBY1P5Ytdie3JigAteiq2eqphD5xeMEcm
JitoSOL (mock)2FpbByvzXNwxQrq5cqDoGLf2bx8nHdMWx3dcugayk4er
JupSOL (mock)F1FZjjvG7DRRvF3tnUVp9N8y6a46i7rH2qfYLhnA1dK6
BONK (mock, priced per million tokens)CSAKKN1szfgwzr8KohREVtTB7GGdc9NdG4YCMU6KYZPM
Orca SOL/USDC poolEHXKciegvkuBAm2P2TUChpkTvRNm4ewwaBa6JmfN8357
Raydium SOL/USDC pool5ZnKViaNwjT2iCZsgAchihmUurnaKTau4MWPUj1MQSnP
Meteora SOL/USDC pairEm4nQAHyFnCpm4FoofwqUX7KLcFvaZac42HXybVmnNHi

deployments/devnet.json holds the full list, including each price account.

Test on a local chain

npm run localnet                                          # keep it running
npm run faucet -- --to <your address> --usdc 6000 --lp 0  # sends 20 SOL, 50 NVDAx and 6,000 mock USDC
npm run price -- --asset stock --price 100                # or --asset sol

npm run price moves the demo price of SOL or NVDAx. Lower it until a borrower's debt is above the liquidation limit, then run the example or the keeper with CLUSTER=localnet.