Torch Prediction Market Kit

Autonomous vault-based prediction market bot for Torch Market on Solana. Creates binary prediction markets as Torch tokens — the bonding curve provides price discovery, the treasury accumulates value from trading fees, and the vault manages positions. Each market has an oracle (price feed or manual) and resolves at a deadline. The agent keypair is generated in-process -- disposable, holds nothing of value. All SOL routes through the vault. The human principal creates the vault, funds it, links the agent, and retains full control. Built on torchsdk v3.7.23 and the Torch Market protocol.

# Torch Prediction Market Kit

You're here because you want to run prediction markets on Torch Market -- and you want to do it safely.

Every prediction market is a Torch token. The bonding curve is the AMM -- no LP setup, deterministic pricing, instant liquidity. The 10% treasury accumulates fees from every buy. Users buy the token to bet YES (price goes up), sell to bet NO (price goes down). At the deadline, the oracle checks the outcome and the bot records it.

**Settlement model: token-as-signal.** No payout mechanism. The token price IS the prediction. The bonding curve and treasury do the work.

That's where this bot comes in.

It reads your `markets.json` file, creates Torch tokens for pending markets, seeds them with initial liquidity from your vault, monitors price and volume, and resolves them at the deadline using an oracle (CoinGecko price feed or manual). All value routes through your vault. The agent wallet that signs transactions holds nothing.

**This is not a read-only scanner.** This is a fully operational market maker that generates its own keypair, verifies vault linkage, creates tokens, seeds liquidity, and resolves markets autonomously in a continuous loop.

---

## How It Works

```
┌─────────────────────────────────────────────────────────┐
│                   MARKET CYCLE LOOP                       │
│                                                          │
│  1. Load market definitions from markets.json            │
│  2. For each pending market:                             │
│     → buildCreateTokenTransaction(name, symbol, uri)     │
│     → sign + submit + confirm                            │
│     → buildBuyTransaction(vault, mint, seed SOL)         │
│     → sign + submit + confirm                            │
│     → update status to 'active', save mint address       │
│  3. For each active market:                              │
│     → getToken(mint) — snapshot price, volume, holders   │
│     → if deadline passed:                                │
│        → checkOracle(oracle) — price feed or manual      │
│        → update status to 'resolved', record outcome     │
│  4. Save updated markets.json                            │
│  5. Sleep SCAN_INTERVAL_MS, repeat                       │
│                                                          │
│  All SOL comes from 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 creates and seeds a market:
- **Token creation** — agent signs as creator, no SOL cost beyond gas
- **Seed liquidity** — SOL comes from the vault via `buildBuyTransaction(vault=creator)`
- **Tokens purchased** — go to the vault's associated token account (ATA)

The human principal retains full control:
- `withdrawVault()` — pull SOL at any time
- `withdrawTokens(mint)` — pull market 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

```bash
npm install torch-prediction-market-kit@2.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:

```typescript
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 market creation + seed liquidity
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. Define Markets

Create `markets.json`:

```json
[
  {
    "id": "sol-200-mar",
    "question": "Will SOL be above $200 by March 1, 2026?",
    "symbol": "SOL200M",
    "name": "SOL Above 200 March",
    "oracle": {
      "type": "price_feed",
      "asset": "solana",
      "condition": "above",
      "target": 200
    },
    "deadline": 1740787200,
    "initialLiquidityLamports": 100000000,
    "metadataUri": "https://arweave.net/placeholder"
  }
]
```

### 4. Run the Bot

```bash
VAULT_CREATOR=<your-vault-creator-pubkey> SOLANA_RPC_URL=<rpc-url> npx torch-prediction-market-bot
```

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

### 5. 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 | `60000` | Milliseconds between market cycles (min 5000) |
| `LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error` |
| `MARKETS_PATH` | No | `./markets.json` | Path to market definitions file |

---

## Architecture

```
packages/kit/src/
├── index.ts      — entry point: keypair generation, vault verification, market cycle loop
├── config.ts     — loadConfig(): validates SOLANA_RPC_URL, VAULT_CREATOR, MARKETS_PATH, etc.
├── types.ts      — Market, Oracle, MarketSnapshot, BotConfig interfaces
├── markets.ts    — loadMarkets(), saveMarkets(), createMarket(), snapshotMarket(), resolveMarket()
├── oracle.ts     — checkPriceFeed(), checkOracle() — CoinGecko price resolution
└── utils.ts      — sol(), createLogger(), decodeBase58(), withTimeout()
```

The bot is ~280 lines of TypeScript across 6 modules. It does three things: create markets, monitor them, and resolve them through the vault.

### Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `@solana/web3.js` | 1.98.4 | Solana RPC, keypair, transaction |
| `torchsdk` | 3.7.23 | Token queries, token creation, buy builder, vault queries |

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

---

## Market Lifecycle

```
pending ──→ active ──→ resolved
              │
              └──→ cancelled
```

| Status | Description |
|--------|-------------|
| **pending** | Market defined in `markets.json`, no token created yet |
| **active** | Torch token created on bonding curve, users can trade |
| **resolved** | Deadline passed, oracle checked, outcome recorded (yes/no) |
| **cancelled** | Market removed before reso