Wheelman

Wheelman, the Rekt trading bot and CLI: a bot, a command line and a local MCP server for Rekt Knockout and Minute. You run it on your own machine, with your own wallet and your own RPC endpoint. It uses the Rekt SDK, @rekt-trading/1000x from npm, for both games, and it sends nothing the risk limits have not allowed.

Status: 1.0.0, on mainnet. Wheelman runs from a clone of this repository. It is not an npm package.

• Documentation: https://docs.rekt.money

• Contact: support@asymmetra.xyz

• License: Apache-2.0 (see LICENSE)

Start in two minutes

Node 22.18 or later. There is no build step: Node runs the TypeScript directly. npm link puts wheelman on your path; without it, run node src/cli.ts in its place. Run it from a clone: npx and npm install -g from a git URL do not work, because Node does not run TypeScript from node_modules.

git clone <this repository's URL> wheelman && cd wheelman
npm install && npm link
wheelman setup                           # wallet, RPC, strategy, risk limits; writes .env (mode 600)
wheelman markets                         # every market, its stake bounds and fees
wheelman preview BTC long 1 --target 2   # what an open costs and pays, after every fee
wheelman open BTC long 1 --paper         # a paper position: simulated, nothing sent
wheelman run --paper                     # the bot on paper
wheelman run --dry-run                   # builds and simulates the real transactions; sends nothing
wheelman run                             # the bot, trading

The wallet needs SOL for fees and rent (0.01 SOL is enough to start) and USDC for stakes.

Related MCP server: xmatters-mcp

The CLI

• --paper on open, close, positions and run: simulated fills on a paper account in .wheelman/paper.json. Nothing is sent.

• --dry-run on open, close, run and session: builds the real transaction, simulates it on mainnet, prints its compute units and bytes, and sends nothing. With no key, set OWNER.

• -o json prints one line: {"ok": true, "data": ...} or {"ok": false, "error": {"category", "code", "message", "retryable"}}. retryable is true only where sending the same request again cannot open a second position. The exit code is 0 on ok, 1 on an error, 2 on a bad flag.

Every open, from the CLI, an agent or the bot, passes the same risk limits. Amounts in the output are USDC with 6 decimals; ids are text.

Agents

Users bring their own agent (Claude Code, Codex, Cursor, or any MCP client). Wheelman hosts no agent and holds no model key.

• Session keys. wheelman session start --allowance 20 --expires 24h (signed by the owner, once) authorises a freshly generated key to trade for the owner's wallet: at most the allowance in USDC, until the expiry. It also creates the owner's book when there is none and sends the key 0.01 SOL for its own fees (--fuel). The key is written to wallets/session-keypair.json (mode 600) before the transaction is sent. The command prints the two settings the agent needs: OWNER and SESSION_KEYPAIR_PATH. wheelman session end (the owner) ends it, drops the allowance and returns the key's SOL. The owner's key never goes to the agent.

• MCP. wheelman mcp --env agent.env serves markets, preview, positions and session_status. With a session key configured it adds open and close, signed by the session key; with --paper it adds them as paper-only. It never signs with the owner's key.

  client	how to add it
  Claude Code	claude mcp add wheelman -- node /path/to/wheelman/src/cli.ts mcp --env /path/to/agent.env
  Codex	in ~/.codex/config.toml: [mcp_servers.wheelman], command = "node", args = ["/path/to/wheelman/src/cli.ts", "mcp", "--env", "/path/to/agent.env"]
  Cursor	in .cursor/mcp.json: {"mcpServers": {"wheelman": {"command": "node", "args": ["/path/to/wheelman/src/cli.ts", "mcp", "--env", "/path/to/agent.env"]}}}

  agent.env holds RPC_URL, OWNER, SESSION_KEYPAIR_PATH and the risk limits, and no owner key.

• Skill. skills/wheelman/SKILL.md teaches an agent the CLI: copy the folder into your agent's skills folder.

How it works

• An open is an order. The venue fills it at its own next price, after a short delay, or returns the whole stake. Wheelman needs prices only for a strategy's signal and for paper fills.

• The venue closes positions. A position ends at its barrier (the stake is gone), at its take-profit, at its timer, or after a close request. The venue's keepers send every close. A Minute round runs on Minute's clock and has no early close.

• The chain is the state. Positions, balances and today's settled results are read from the chain, so a restart or a fresh container is safe. .wheelman/ holds the log, the paper account and a cache of settled transactions (they never change, so each is fetched once).

• One loop. Once a second the strategy reads the latest price and its own positions and returns intents. The risk guard checks each one. Each transaction is simulated first and sent only when it simulated clean. The result is read from the chain (the opened seq, the settlement).

• One code path. The CLI, the MCP server and the bot call the same functions. The venue layer (src/client.ts) has the shape of the SDK's Knockout client: market, preview, open, positions, close, settlement, history, build.

Strategies

The bot runs one strategy. Pick one with STRATEGY, and set its parameters with PARAM_<NAME>. Every parameter has a default and a bound, and the bot refuses a value outside the bound. The defaults are starting points, not recommendations.

knockout-momentum (Knockout). Open in the direction of a move larger than trigger_bps over lookback_s.

knockout-fade (Knockout). Open against a sharp move; close when the price is back where the move started.

knockout-straddle (Knockout). In a quiet market, open a long and a short of the same stake together, in one transaction. A knockout ends one side; the other side runs to its take-profit or its timer. One wallet may hold both sides of a market.

minute-trend (Minute). Each round, take the side of the move over lookback_s; skip a move below min_bps.

minute-schedule (Minute). Play every Nth minute at a fixed stake and side rule, inside a daily UTC window.

template (Knockout). A skeleton that never trades: copy src/strategies/template.ts to write your own. A strategy is { id, game, params, onTick(ctx) }; onTick returns intents and sends nothing. Add it to registry() in src/strategies/index.ts, or load it with EXTRA_STRATEGIES.

The venue's own bounds also apply: the stake must be inside the venue's limits (Minute's for a round), which Wheelman reads from the chain.

Configuration

Environment variables only: .env on your machine (or --env <file>), the host's settings elsewhere. .env.example lists every variable with one line on each. The ones you set:

Wheelman checks every variable before its first RPC call and refuses a bad value with the reason.

Risk limits

The risk guard sits between every intent and the venue: the bot's, open's and an agent's. It never blocks a close. It counts the worst case, every open stake lost, so no limit is passed after the fact.

Wheelman refuses to trade without a daily loss stop. Today's loss is read from the chain, so a restart does not reset it. A session key adds the owner's own ceiling: its allowance and expiry.

Paper mode

Paper results are priced by the SDK's own settlement arithmetic, with the terms a real position freezes at open: the barrier, the target, the exit fee and the market's fee terms (the share of a gain the venue keeps). A Minute round also pays Minute's own fees. Two things differ from live: the fill is the next price Wheelman sees, not the venue's, and a one-shot command checks the barrier only at the prices it reads (run --paper sees every tick). The borrow fee is not modelled; it is 0 today. A paper result tests what Wheelman does; it does not say what live trading pays.

RPC: any provider

Drop in any endpoint: Helius, Triton, QuickNode, or your own node. Wheelman uses little:

• Stream first, poll last. The bot subscribes to its own accounts (websocket, or Yellowstone gRPC with GRPC_URL), reads once after every reconnect, and reads at least every 30 s as a fallback.

• Only its own accounts. One getMultipleAccounts reads the venue, a market and the wallet's book. When a position ends, it reads its own book's latest transactions once to learn what it paid. It never scans a program's accounts.

• One rate limit and one backoff per endpoint. On HTTP 429 or JSON-RPC -32005 it waits 1 s, doubles to 30 s with jitter, and stops loudly after 5 attempts. RPC_FALLBACK_URL takes over only while RPC_URL fails.

• confirmed on every call. The blockhash and the priority fee are cached for a few seconds.

• One send, one bounded rebroadcast. It simulates first, sends with maxRetries: 0, sends the same bytes again every 2 s, and stops when the transaction confirms or its blockhash expires. On a Helius endpoint it asks Helius for the priority fee; elsewhere it uses recent fees. SEND_URL may point at a send-only endpoint.

• No key in a log. Every log line names the host only and redacts keys from URLs and errors.

• It refuses early: a non-mainnet endpoint, an unlisted market or a stake the venue does not take stops it before any spend.

Prices

A price is needed only for a strategy's signal and for paper fills. PRICE_SOURCE=coinbase reads Coinbase's public ticker (no key, no account) for BTC, ETH, SOL and XRP. PRICE_SOURCE=replay reads a tape for paper mode: one JSON line a price, {"time": 1767225600000, "market": "BTC", "price": 100000}. To add a source, write one function in src/prices.ts that returns a PriceSource.

Hosting

The same variables work everywhere. One process, no database, no web server. A fatal error exits non-zero, so every host restarts it. Dockerfile and render.yaml are templates for your own host: you run Wheelman, with your own wallet; nobody hosts it for you.

• Any server: npm ci --omit=dev && npm start (that is wheelman run), under your process manager.

• Docker: docker build -t wheelman . then docker run --env-file .env -v "$PWD/wallets:/app/wallets:ro" wheelman.

• Render: render.yaml describes one background worker. Set RPC_URL and DAILY_LOSS_USDC in the dashboard and put the keypair in a Secret File named bot-keypair.json (or set WALLET_SECRET_KEY).

Safety

• Wallet and session key files are written with mode 600 and never printed, logged or sent. Back up the wallet.

• Use a wallet for Wheelman alone, and fund it with what you are ready to lose. At the barrier a position pays nothing.

• Give an agent a session key, never the wallet. Size its allowance for one session and end it when you are done: a token allowance has no clock of its own.

• Never commit .env, wallets/ or a keypair file; .gitignore excludes them.

• Use --paper and --dry-run before trading, and after every change you make.

Development

npm run check runs the type check and the tests (Node's own test runner, no network).