Torch Liquidation Bot

    - name: VAULT_CREATOR
      required: true
    - name: SOLANA_PRIVATE_KEY
      required: false
    - name: SCAN_INTERVAL_MS
      required: false
    - name: SCAN_LIMIT
      required: false
    - name: MIN_AGENT_BALANCE_SOL
      required: false
    - name: LOG_LEVEL
      required: false
    - name: LOG_FORMAT
      required: false
metadata:
  clawdbot:
    requires:
      env:
        - name: SOLANA_RPC_URL
          required: true
        - name: VAULT_CREATOR
          required: true
        - name: SOLANA_PRIVATE_KEY
          required: false
        - name: SCAN_INTERVAL_MS
          required: false
        - name: SCAN_LIMIT
          required: false
        - name: MIN_AGENT_BALANCE_SOL
          required: false
        - name: LOG_LEVEL
          required: false
        - name: LOG_FORMAT
          required: false
    primaryEnv: SOLANA_RPC_URL
  openclaw:
    requires:
      env:
        - name: SOLANA_RPC_URL
          required: true
        - name: VAULT_CREATOR
          required: true
        - name: SOLANA_PRIVATE_KEY
          required: false
        - name: SCAN_INTERVAL_MS
          required: false
        - name: SCAN_LIMIT
          required: false
        - name: MIN_AGENT_BALANCE_SOL
          required: false
        - name: LOG_LEVEL
          required: false
        - name: LOG_FORMAT
          required: false
    primaryEnv: SOLANA_RPC_URL
    install:
      - id: npm-torch-liquidation-bot
        kind: npm
        package: torch-liquidation-bot@^10.7.1
        flags: []
        label: "Install Torch Liquidation Bot (npm, optional -- SDK is bundled in lib/torchsdk/ and bot source is bundled under lib/kit on clawhub)"
  author: torch-market
  version: "10.7.1"
  clawhub: https://clawhub.ai/mrsirg97-rgb/torch-liquidation-bot
  kit-source: https://github.com/mrsirg97-rgb/torch-liquidation-kit
  sdk-source: https://github.com/mrsirg97-rgb/torchsdk
  website: https://torch.market
  program-id: 8hbUkonssSEEtkqzwM7ZcZrD9evacM92TcWSooVF4BeT
  keywords:
    - solana
    - defi
    - liquidation
    - liquidation-bot
    - liquidation-keeper
    - collateral-lending
    - vault-custody
    - ai-agents
    - agent-wallet
    - agent-safety
    - treasury-lending
    - bonding-curve
    - fair-launch
    - token-2022
    - raydium
    - community-treasury
    - protocol-rewards
    - solana-agent-kit
    - escrow
    - anchor
    - pda
    - on-chain
    - autonomous-agent
    - keeper-bot
    - torch-market
    - versioned-transactions
    - address-lookup-tables
  categories:
    - solana-protocols
    - defi-primitives
    - lending-markets
    - agent-infrastructure
    - custody-solutions
    - liquidation-keepers
compatibility: >-
  REQUIRED: SOLANA_RPC_URL (HTTPS Solana RPC endpoint).
  REQUIRED: VAULT_CREATOR (vault creator pubkey).
  OPTIONAL: SOLANA_PRIVATE_KEY (disposable controller keypair -- fresh key, ~0.01 SOL for gas, NEVER a vault authority key).
  Without SOLANA_PRIVATE_KEY, the bot generates a fresh disposable keypair in-process (recommended).
  All liquidation proceeds route to the vault. The vault can be created and funded entirely by the human principal.
  This skill sets disable-model-invocation: true -- it must not be invoked autonomously without explicit user initiation.
  SDK bundled in lib/torchsdk/. No API server dependency.
---

# Torch Liquidation Bot

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

```
┌──────────────────────────────────────────────────────────┐
│                  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

```
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

```
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](https://github.com/nicholasgasior/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](https://github.com/mrsirg97-rgb/torch-liquidation-kit)
- Liquidation Bot (npm): [npmjs.com/package/torch-liquidation-bot](https://www.npmjs.com/package/torch-liquidation-bot)
- Torch SDK: `lib/torchsdk/` | [npm](https://www.npmjs.com/package/torchsdk) | [source](https://github.com/mrsirg97-rgb/torchsdk)
- [torch.market](https://torch.market) | [Whitepaper](https://torch.market/whitepaper) | [Risk Model](https://torch.market/risk.md)
- Program: `8hbUkonssSEEtkqzwM7ZcZrD9evacM92TcWSooVF4BeT`