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

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:

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:

[
  {
    "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

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 resolution (manual edit)

Market Definition

interface MarketDefinition {
  id: string                  // unique market identifier
  question: string            // human-readable question
  symbol: string              // token symbol (max 10 chars)
  name: string                // token name (max 32 chars)
  oracle: Oracle              // how the market resolves
  deadline: number            // unix timestamp (seconds)
  initialLiquidityLamports: number  // SOL to seed bonding curve (in lamports, max 10 SOL)
  metadataUri: string         // token metadata URI (allowlisted domains only)
}

Input Validation

All pending markets are validated on load. Markets with invalid inputs are rejected before any on-chain action.

Field	Constraint	Rejected Example
id	Must be unique across all markets	Duplicate "sol-200-mar"
metadataUri	Domain must be in allowlist: arweave.net, gateway.irys.xyz, ipfs.io, cloudflare-ipfs.com, nftstorage.link, dweb.link	https://evil.com/payload.json
initialLiquidityLamports	Max 10 SOL (10,000,000,000 lamports), non-negative	50000000000 (50 SOL)
oracle.asset	Must be in allowlist of known CoinGecko IDs (solana, bitcoin, ethereum, etc.)	"arbitrary-string"

These constraints ensure a compromised markets.json cannot trigger arbitrary URI fetches, drain the vault, or make unintended API calls.

---

Oracle Resolution

Price Feed Oracle (CoinGecko)

The primary oracle. Fetches the current price of an asset and compares it against a target.

{
  "type": "price_feed",
  "asset": "solana",
  "condition": "above",
  "target": 200
}

• asset — CoinGecko asset ID (e.g. "solana", "bitcoin", "ethereum")
• condition — "above" or "below"
• target — USD price threshold
• Resolution: if condition is "above", outcome is "yes" when price > target, "no" otherwise

Manual Oracle

Fallback for markets that can't be resolved by a price feed.

{
  "type": "manual",
  "source": "Twitter announcement from @torch_market"
}

Resolution: edit markets.json directly — set "status": "resolved" and "outcome": "yes" or "no".

---

Vault Safety Model

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

Property	Guarantee
Full custody	Vault holds all SOL and all market tokens. Agent wallet holds nothing.
Closed loop	Seed liquidity SOL comes from vault, purchased tokens go to vault ATA. 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 creates markets.
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 Market Creation

Direction	Flow
SOL out	Vault → Bonding curve (seed liquidity buy)
Tokens in	Bonding curve → Vault ATA (purchased tokens)
Treasury	10% of each buy accumulates in token treasury

The vault's seed tokens remain on the bonding curve. Users trade against the curve. Treasury grows from fees. The authority can withdraw vault tokens or SOL at any time.

---

SDK Functions Used

The bot uses a focused subset of the Torch SDK:

Function	Purpose
getVault(connection, creator)	Verify vault exists on startup
getVaultForWallet(connection, wallet)	Verify agent is linked to vault
buildCreateTokenTransaction(connection, params)	Build token creation transaction for new market
buildBuyTransaction(connection, params)	Build vault-routed buy to seed initial liquidity
getToken(connection, mint)	Get token price, volume, status for market snapshots
getHolders(connection, mint)	Get holder count for market snapshots
confirmTransaction(connection, sig, wallet)	Confirm transaction on-chain via RPC (verifies signer, checks Torch instructions)

buildCreateTokenTransaction Parameters

const { transaction, mint, mintKeypair } = await buildCreateTokenTransaction(connection, {
  creator: agentPubkey,       // agent wallet (signer + fee payer)
  name: "SOL Above 200 March", // token name (max 32 chars)
  symbol: "SOL200M",           // token symbol (max 10 chars)
  metadata_uri: "https://arweave.net/...",  // token metadata URI
});

buildBuyTransaction Parameters

const { transaction, message } = await buildBuyTransaction(connection, {
  mint: mintAddress,            // token to buy
  buyer: agentPubkey,           // agent wallet (signer)
  amount_sol: 100000000,        // 0.1 SOL in lamports
  slippage_bps: 500,            // 5% slippage tolerance
  vault: vaultCreator,          // vault creator pubkey (SOL from vault, tokens to vault ATA)
});

---

Signing & Key Safety

The vault is the security boundary, not the key.

The agent keypair is generated fresh on every startup with Keypair.generate(). It holds ~0.01 SOL for gas fees. If the key is compromised, the attacker gets:

• Dust (the gas SOL)
• Vault access that the authority revokes in one transaction

The agent never needs the authority's private key. The authority never needs the agent's private key. They share a vault, not keys.

Rules

1. Never ask a user for their private key or seed phrase. The vault authority signs from their own device.
2. Never log, print, store, or transmit private key material. The agent keypair exists only in runtime memory.
3. Never embed keys in source code or logs. The agent pubkey is printed — the secret key is never exposed.
4. Use a secure RPC endpoint. Default to a private RPC provider. Never use an unencrypted HTTP endpoint for mainnet transactions.

RPC Timeout

All SDK calls are wrapped with a 30-second timeout (withTimeout in utils.ts). A hanging or unresponsive RPC endpoint cannot stall the bot indefinitely — the call rejects, the error is caught by the market cycle loop, and the bot continues to the next market or cycle.

Environment Variables

Variable	Required	Purpose
SOLANA_RPC_URL / RPC_URL	Yes	Solana RPC endpoint (HTTPS)
VAULT_CREATOR	Yes	Vault creator pubkey — identifies which vault the bot operates through
SOLANA_PRIVATE_KEY	No	Optional — if omitted, the bot generates a fresh keypair on startup (recommended)

External Runtime Dependencies

The SDK and bot make outbound HTTPS requests to external services. The bot's runtime path contacts three of them:

Service	Purpose	When Called	Bot Uses?
CoinGecko (api.coingecko.com)	Asset price for oracle resolution + SOL/USD display	checkPriceFeed() in oracle.ts, getToken() in SDK	Yes — oracle resolution AND token queries
Irys Gateway (gateway.irys.xyz)	Token metadata fallback (name, symbol, image)	getToken() when on-chain metadata URI points to Irys	Yes — via getToken()
SAID Protocol (api.saidprotocol.com)	Agent identity verification and trust tier lookup	verifySaid() only	No — the bot does not call verifySaid()

CoinGecko API Details (Oracle)

The oracle module (oracle.ts) calls the CoinGecko public API directly:

GET https://api.coingecko.com/api/v3/simple/price?ids={asset}&vs_currencies=usd

• No API key required — uses the free public endpoint
• Rate limit: ~10-30 calls/minute on the free tier
• Data sent: asset ID only (e.g. "solana") — no wallet, transaction, or agent data
• Data received: { "solana": { "usd": 87.76 } }
• Failure mode: if CoinGecko is unreachable, checkPriceFeed() throws and the market stays unresolved until the next cycle
• Called once per active market per cycle that has passed its deadline

confirmTransaction() does NOT contact SAID. Despite living in the SDK's said.js module, it only calls connection.getParsedTransaction() (Solana RPC) to verify the transaction succeeded on-chain and determine the event type. No data is sent to any external service.

No credentials are sent to CoinGecko or Irys. All requests are read-only GET. If either service is unreachable, the bot degrades gracefully. No private key material is ever transmitted to any external endpoint.

---

Log Output

=== torch prediction market bot ===
agent wallet: 7xK9...
vault creator: 4yN2...
markets file: ./markets.json
scan interval: 60000ms

[09:15:32] INFO  vault found — authority=8cpW...
[09:15:32] INFO  agent wallet linked to vault — starting market cycle
[09:15:32] INFO  treasury: 5.0000 SOL
[09:15:33] INFO  CREATING | sol-200-mar — "Will SOL be above $200 by March 1, 2026?"
[09:15:35] INFO  CREATED | sol-200-mar — mint=AqAgqKTypS... | seed=0.1000 SOL
[09:16:35] DEBUG SNAPSHOT | sol-200-mar — price=0.000012 SOL | mcap=0.0120 | holders=3
[09:17:35] INFO  RESOLVING | sol-200-mar — deadline reached
[09:17:36] INFO  RESOLVED | sol-200-mar — outcome=no

---

Testing

Requires Surfpool running a mainnet fork:

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

Test result: 9 passed, 1 informational (Surfpool RPC limitation on getTokenLargestAccounts for Token-2022 — works on mainnet).

Test	What It Validates
Connection	RPC reachable
loadMarkets	Market file parsing and validation
checkPriceFeed	CoinGecko oracle returns valid price data
buildCreateTokenTransaction	Token creation transaction builds correctly
getTokens	Discovers bonding/migrated tokens
getToken	Token metadata, price, status
getHolders	Holder enumeration (skips on Surfpool limitation)
getVaultForWallet	Vault link returns null for unlinked wallet
In-process keypair	No external key required

---

Error Codes

• VAULT_NOT_FOUND: No vault exists for this creator
• WALLET_NOT_LINKED: Agent wallet is not linked to the vault
• INVALID_MINT: Token not found
• BONDING_COMPLETE: Token has graduated — trade on DEX instead
• NAME_TOO_LONG: Token name exceeds 32 characters
• SYMBOL_TOO_LONG: Token symbol exceeds 10 characters

---

Links

• Prediction Market Kit (source): github.com/mrsirg97-rgb/torch-prediction-market-kit
• Prediction Market Kit (npm): npmjs.com/package/torch-prediction-market-kit
• Torch SDK (bundled): lib/torchsdk/ -- included in this skill
• Torch SDK (source): github.com/mrsirg97-rgb/torchsdk
• Torch SDK (npm): npmjs.com/package/torchsdk
• Torch Market (protocol skill): clawhub.ai/mrsirg97-rgb/torchmarket
• Whitepaper: torch.market/whitepaper.md
• Security Audit: torch.market/audit.md
• Website: torch.market
• Program ID: 8hbUkonssSEEtkqzwM7ZcZrD9evacM92TcWSooVF4BeT

---

Changelog

v2.0.0

• Upgraded torchsdk from 3.2.3 to 3.7.23. Major SDK update adds treasury lock PDAs (V27), dynamic Raydium network detection, auto-migration bundling on bonding curve completion (buildBuyTransaction now returns optional migrationTransaction), vault-routed Raydium CPMM swaps (buildVaultSwapTransaction), Token-2022 fee harvesting (buildHarvestFeesTransaction, buildSwapFeesToSolTransaction), bulk loan scanning (getAllLoanPositions), on-chain token metadata queries (getTokenMetadata), and ephemeral agent keypair factory (createEphemeralAgent).
• Exported withTimeout utility. The timeout helper used internally by the bot is now a public export of the kit package, available to downstream consumers.
• Updated env format in skill frontmatter. Environment variable declarations now use structured name/required format for compatibility with ClawHub and OpenClaw agent runners.

v1.0.2

• Updated kit to point to correct bundled sdk. The index.js file now imports the SDK from the local lib/torchsdk/ directory instead of the npm package. This ensures that the bot uses the exact bundled SDK version (3.2.3) included in the kit, rather than any potentially different version installed from npm. Addresses audit finding L-3.

v1.0.1

• Timeout on all external calls. Every SDK, RPC, and API call is now wrapped with a 30-second timeout (10 seconds for CoinGecko). If an RPC endpoint or CoinGecko becomes unresponsive, the call fails fast with a descriptive error instead of stalling the bot indefinitely. Addresses audit finding L-1.
• Market ID uniqueness validation. loadMarkets() now rejects markets.json files containing duplicate market IDs on load, preventing unintended duplicate market creation and wasted vault SOL. Addresses audit finding L-2.

---

This bot exists because prediction markets need infrastructure. Torch bonding curves provide instant liquidity and deterministic pricing without LP setup. The vault makes it safe — all value stays in the escrow, all risk is bounded, and the human principal keeps the keys. The token price IS the prediction.