torch-liquidation-bot

Torch Liquidation Bot

You're here because you want to run a liquidation keeper on Torch Market -- and you want to do it safely.

Every migrated token on Torch has a built-in lending market. Holders lock tokens as collateral and borrow SOL from the community treasury (up to 50% LTV, 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.

That's where this bot comes in.

It 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. The collateral tokens go to your vault ATA. The SOL cost comes from your vault. The agent wallet that signs the transaction holds nothing.

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

┌──────────────────────────────────────────────────────────┐
│                  LIQUIDATION LOOP                          │
│                                                           │
│  1. Discover migrated tokens (getTokens)                  │
│  2. For each token, scan all loans (getAllLoanPositions)   │
│     — single RPC call, returns 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:

--- ACTION REQUIRED ---
agent wallet is NOT linked to the vault.
link it by running (from your authority wallet):

  buildLinkWalletTransaction(connection, {
    authority: "<your-authority-pubkey>",
    vault_creator: "<your-vault-creator>",
    wallet_to_link: "<agent-pubkey>"
  })

then restart the bot.
-----------------------

Link it from your authority wallet (hardware wallet, multisig, whatever you use). The agent never needs the authority's key. The authority never needs the agent's key. They share a vault, not keys.

The Vault

This is the same Torch Vault from the full Torch Market protocol. It holds all assets -- SOL and tokens. The agent is a disposable controller.

When the bot liquidates a position:

• SOL cost comes from the vault (the liquidation payment to cover the borrower's debt)
• Collateral tokens go to the vault's associated token account (ATA)
• 10% bonus means the collateral received is worth 10% more than the SOL spent

The human principal retains full control:

• withdrawVault() — pull SOL at any time
• withdrawTokens(mint) — pull collateral tokens at any time
• unlinkWallet(agent) — revoke agent access instantly

If the agent keypair is compromised, the attacker gets dust and vault access that you revoke in one transaction.

---

Getting Started

1. Install

npm install torch-liquidation-bot@4.0.2

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:

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

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

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)
LOG_LEVEL	No	info	debug, info, warn, error

---

Architecture

packages/bot/src/
├── index.ts    — entry point: keypair generation, vault verification, scan loop
├── config.ts   — loadConfig(): validates SOLANA_RPC_URL, VAULT_CREATOR, SOLANA_PRIVATE_KEY, SCAN_INTERVAL_MS, LOG_LEVEL
├── types.ts    — BotConfig, LogLevel interfaces
└── utils.ts    — sol(), bpsToPercent(), withTimeout(), createLogger()

The bot is ~192 lines of TypeScript. It does one thing: find underwater loans and liquidate them through the vault.

Dependencies

Package	Version	Purpose
@solana/web3.js	1.98.4	Solana RPC, keypair, transaction
torchsdk	3.7.22	Token queries, bulk loan scanning, liquidation builder, vault queries

Two runtime dependencies. Both pinned to exact versions. No ^ or ~ ranges.

---

Vault Safety Model

The same seven guarantees from the Torch Market vault apply here:

Property	Guarantee
Full custody	Vault holds all SOL and all collateral tokens. Agent wallet holds nothing.
Closed loop	Liquidation SOL comes from vault, collateral tokens go to vault. No leakage to agent.
Authority separation	Creator (immutable PDA seed) vs Authority (transferable admin) vs Controller (disposable signer).
One link per wallet	Agent can only belong to one vault. PDA uniqueness enforces this on-chain.
Permissionless deposits	Anyone can top up the vault. Hardware wallet deposits, agent liquidates.
Instant revocation	Authority can unlink the agent at any time. One transaction.
Authority-only withdrawals	Only the vault authority can withdraw SOL or tokens. The agent cannot extract value.

The Closed Economic Loop for Liquidations

Direction	Flow
SOL out	Vault → Borrower's treasury debt (covers the loan)
Tokens in	Borrower's collateral → Vault ATA (at 10% discount)
Net	Vault receives collateral worth 110% of SOL spent

The bot is profitable by design — every successful liquidation returns more value than it costs. The profit accumulates in the vault. The authority withdraws when ready.

---

Lending Parameters

Parameter	Value
Max LTV	50%
Liquidation Threshold	65%
Interest Rate	2% per epoch (~weekly)
Liquidation Bonus	10%
Utilization Cap	70% of treasury
Min Borrow	0.1 SOL

Collateral value is calculated from Raydium pool reserves. The 0.03% Token-2022 transfer fee (3 bps, immutable per mint) applies on collateral deposits and withdrawals.

When Liquidations Happen

A loan becomes liquidatable when its LTV exceeds 65%. This happens when:

• The token price drops (collateral value decreases relative to debt)
• Interest accrues (debt grows at 2% per epoch)
• A combination of both

The bot checks position.health === 'liquidatable' — the SDK calculates LTV from on-chain Raydium reserves and the loan's accrued debt.

---

SDK Functions Used

The bot uses a focused subset of the Torch SDK:

Function	Purpose
getTokens(connection, { status: 'migrated' })	Discover all tokens with active lending markets
getAllLoanPositions(connection, mint)	Bulk scan all active loans for a token — returns positions pre-sorted by health (liquidatable first), fetches pool price once
getVault(connection, creator)	Verify vault exists on startup
getVaultForWallet(connection, wallet)	Verify agent is linked to vault
buildLiquidateTransaction(connection, params)	Build the liquidation transaction (vault-routed)
confirmTransaction(connection, sig, wallet)	Confirm transaction on-chain via RPC (verifies signer, checks Torch instructions)

Scan and Liquidate Pattern

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

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

for (const token of tokens) {
  // 2. Bulk scan — one RPC call per token, positions sorted liquidatable-first
  const { positions } = await getAllLoanPositions(connection, token.mint)

  for (const pos of positions) {
    if (pos.health !== 'liquidatable') bre

---

*Content truncated.*