Torch Liquidation Bot

Autonomous vault-based liquidation keeper for Torch Market lending on Solana. Scans all migrated tokens for underwater loan positions using the SDK's bulk loan scanner (getAllLoanPositions), builds and executes liquidation transactions through a Torch Vault, and collects a 10% collateral bonus.

Autonomous vault-based liquidation keeper for Torch Market lending on Solana.

Every migrated token on Torch has a built-in lending market. Holders lock tokens as collateral and borrow SOL from the community treasury (depth-adaptive LTV 25-50%, 2% weekly interest). When a loan's LTV crosses 65%, it becomes liquidatable. Anyone can liquidate it and collect a 10% bonus on the collateral value.

This bot scans every migrated token's lending market using the SDK's bulk loan scanner (getAllLoanPositions) -- one RPC call per token returns all active positions pre-sorted by health. When it finds one that's underwater, it liquidates it through your vault.

This is not a read-only scanner. This is a fully operational keeper that generates its own keypair, verifies vault linkage, and executes liquidation transactions autonomously in a continuous loop.

How It Works

text

┌──────────────────────────────────────────────────────────┐
│                  LIQUIDATION LOOP                        │
│                                                          │
│  1. Discover migrated tokens (getTokens)                 │
│  2. For each token, scan all loans (getAllLoanPositions)  │
│     -- single RPC call, positions sorted by health       │
│     -- liquidatable -> at_risk -> healthy                │
│  3. Skip tokens with no active loans                     │
│  4. For each liquidatable position:                      │
│     -> buildLiquidateTransaction(vault=creator)          │
│     -> sign with agent keypair                           │
│     -> submit and confirm                                │
│     -> break when health != 'liquidatable' (pre-sorted)  │
│  5. Sleep SCAN_INTERVAL_MS, repeat                       │
│                                                          │
│  All SOL comes from vault. All collateral goes to vault. │
│  Agent wallet holds nothing. Vault is the boundary.      │
└──────────────────────────────────────────────────────────┘

The Agent Keypair

The bot generates a fresh Keypair in-process on every startup. No private key file. No environment variable (unless you want to provide one). The keypair is disposable -- it signs transactions but holds nothing of value.

On first run, the bot checks if this keypair is linked to your vault. If not, it prints the exact SDK call you need to link it. Link it from your authority wallet, then restart.

The Vault

text

Human (authority)                   Agent (controller, ~0.01 SOL gas)
  ├── createVault()                  ├── liquidate(vault) -> SOL from vault
  ├── depositVault(SOL)              └── collateral tokens -> vault ATA
  ├── linkWallet(agent)
  ├── withdrawVault()  <- auth only
  ├── withdrawTokens() <- auth only
  └── unlinkWallet()   <- instant

Guarantee	Mechanism
Full custody	Vault holds all SOL and tokens. Controller holds nothing.
Closed loop	SOL from vault pays debt, collateral tokens to vault. No leakage.
Authority separation	Creator (immutable) / Authority (transferable) / Controller (disposable)
Instant revocation	Authority unlinks controller in one tx
No extraction	Controllers cannot withdraw. Period.

Getting Started

1. Install

bash

npm install torch-liquidation-bot

Or use the bundled source from ClawHub -- the Torch SDK is included in lib/torchsdk/ and the bot source is in lib/kit/.

2. Create and Fund a Vault (Human Principal)

From your authority wallet:

typescript

import { Connection } from "@solana/web3.js";
import {
  buildCreateVaultTransaction,
  buildDepositVaultTransaction,
} from "torchsdk";

const connection = new Connection(process.env.SOLANA_RPC_URL);

// Create vault
const { transaction: createTx } = await buildCreateVaultTransaction(connection, {
  creator: authorityPubkey,
});
// sign and submit with authority wallet...

// Fund vault with SOL for liquidations
const { transaction: depositTx } = await buildDepositVaultTransaction(connection, {
  depositor: authorityPubkey,
  vault_creator: authorityPubkey,
  amount_sol: 5_000_000_000, // 5 SOL
});
// sign and submit with authority wallet...

3. Run the Bot

bash

VAULT_CREATOR=<your-vault-creator-pubkey> SOLANA_RPC_URL=<rpc-url> npx torch-liquidation-bot

On first run, the bot prints the agent keypair and instructions to link it. Link it from your authority wallet, then restart.

4. Configuration

Variable	Required	Default	Description
SOLANA_RPC_URL	Yes	--	Solana RPC endpoint (HTTPS). Fallback: RPC_URL
VAULT_CREATOR	Yes	--	Vault creator pubkey
SOLANA_PRIVATE_KEY	No	--	Disposable controller keypair (base58 or JSON byte array). If omitted, generates fresh keypair on startup (recommended)
SCAN_INTERVAL_MS	No	30000	Milliseconds between scan cycles (min 5000)
SCAN_LIMIT	No	50	Max tokens scanned per cycle (0 = unlimited)
MIN_AGENT_BALANCE_SOL	No	0.01	Pause liquidations when agent gas balance drops below this
LOG_LEVEL	No	info	debug, info, warn, error
LOG_FORMAT	No	text	text (human-readable) or json (structured, one record per line)

SDK Functions Used

Function	Returns
getTokens(connection, params?)	Token list (filterable, sortable)
getToken(connection, mint)	Full detail: price, treasury, status
getLendingInfo(connection, mint)	Lending parameters and pool state
getAllLoanPositions(connection, mint)	All loans sorted by liquidation risk
getLoanPosition(connection, mint, wallet)	Loan: collateral, debt, LTV, health
getVault(connection, creator)	Vault state
getVaultForWallet(connection, wallet)	Reverse vault lookup
buildLiquidateTransaction(connection, params)	VersionedTransaction (sign with [keypair])
confirmTransaction(connection, sig, wallet)	On-chain confirmation via RPC

Scan and Liquidate Pattern

typescript

import { getTokens, getAllLoanPositions, buildLiquidateTransaction } from 'torchsdk'

const { tokens } = await getTokens(connection, { status: 'migrated', sort: 'volume', limit: 50 })

for (const token of tokens) {
  const { positions } = await getAllLoanPositions(connection, token.mint)

  for (const pos of positions) {
    if (pos.health !== 'liquidatable') break  // pre-sorted, done

    const { transaction, message } = await buildLiquidateTransaction(connection, {
      mint: token.mint,
      liquidator: agentPubkey,
      borrower: pos.borrower,
      vault: vaultCreator,
    })
    transaction.sign([agentKeypair])
    await connection.sendRawTransaction(transaction.serialize())
  }
}

Constants

text

MAX_LTV         25-50% (depth-adaptive: 25% <50 SOL, 35% 50-200, 45% 200-500, 50% 500+)
LIQ_THRESHOLD   65%
INTEREST        2% per epoch (~7 days)
LIQ_BONUS       10%
UTIL_CAP        80%
MIN_BORROW      0.1 SOL
MIN_POOL_SOL    5 SOL (below this: margin ops blocked)
PROGRAM_ID      8hbUkonssSEEtkqzwM7ZcZrD9evacM92TcWSooVF4BeT

Key Safety

If SOLANA_PRIVATE_KEY is provided: must be a fresh disposable keypair (~0.01 SOL gas). All capital lives in vault. If compromised: attacker gets dust, authority revokes in one tx. Key never leaves the runtime.

If not provided: the bot generates a fresh keypair on startup (recommended).

Rules:

1. Never ask for a private key or seed phrase.
2. Never log, print, store, or transmit key material.
3. Use a secure HTTPS RPC endpoint.

External Runtime Dependencies

Service	Purpose	When Called
CoinGecko (api.coingecko.com)	SOL/USD price for display	Token queries via getTokens()
Creator-controlled metadata URI (typically arweave.net)	Token metadata JSON	getTokens() / getToken() — 10s fetch timeout, failure is non-fatal

No credentials sent. All requests are read-only GET. No private key material is ever transmitted.

Testing

Requires Surfpool running a mainnet fork:

bash

surfpool start --network mainnet --no-tui
pnpm test

Links

• Liquidation Kit (source): github.com/mrsirg97-rgb/torch-liquidation-kit
• Liquidation Bot (npm): npmjs.com/package/torch-liquidation-bot
• Torch SDK: lib/torchsdk/ | npm | source
• torch.market | Whitepaper | Risk Model
• Program: 8hbUkonssSEEtkqzwM7ZcZrD9evacM92TcWSooVF4BeT