@rekt-trading/wheelman 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.env.example ADDED
@@ -0,0 +1,75 @@
1
+ # Every setting of Wheelman. `wheelman setup` writes .env for you; or copy this file to .env.
2
+ # Amounts are USDC, written like 1.50. An empty value means "not set". Never commit .env.
3
+
4
+ # --- RPC: any provider ---
5
+ # Required. Your HTTPS JSON-RPC endpoint: Helius, Triton, QuickNode, or your own node. No default.
6
+ RPC_URL=
7
+ # The websocket endpoint for account updates. Default: RPC_URL with wss://.
8
+ RPC_WS_URL=
9
+ # A Yellowstone gRPC endpoint (Triton, Helius LaserStream); it replaces the websocket. Run `npm install @triton-one/yellowstone-grpc` first.
10
+ GRPC_URL=
11
+ # The token for GRPC_URL.
12
+ GRPC_TOKEN=
13
+ # A send-only endpoint for transactions. Default: RPC_URL.
14
+ SEND_URL=
15
+ # A tip in lamports added to each transaction, for a SEND_URL that requires one. 0 is no tip.
16
+ SEND_TIP_LAMPORTS=0
17
+ # The address the tip goes to, as your send provider names it.
18
+ SEND_TIP_ACCOUNT=
19
+ # A standby endpoint. It takes over only while RPC_URL fails, never at the same time.
20
+ RPC_FALLBACK_URL=
21
+ # The most requests a second Wheelman sends to each endpoint (1 to 500).
22
+ RPC_MAX_RPS=10
23
+ # The largest priority fee Wheelman pays, in micro-lamports per compute unit.
24
+ MAX_PRIORITY_FEE=100000
25
+
26
+ # --- Keys: the owner's wallet, or a session key for an agent ---
27
+ # The owner's keypair file. `wheelman setup` writes wallets/bot-keypair.json with mode 600.
28
+ KEYPAIR_PATH=wallets/bot-keypair.json
29
+ # The owner's secret key itself (a JSON array of 64 numbers, or base58), for a host without secret files.
30
+ WALLET_SECRET_KEY=
31
+ # `wheelman setup --yes` only: a keypair file to copy into wallets/bot-keypair.json.
32
+ WALLET_IMPORT=
33
+ # The wallet's address, for a process that holds no key: an agent with a session key, or a dry run.
34
+ OWNER=
35
+ # A session key that trades for OWNER within its allowance and expiry (`wheelman session start` writes it).
36
+ SESSION_KEYPAIR_PATH=
37
+
38
+ # --- What to trade ---
39
+ # knockout-momentum, knockout-fade, knockout-straddle, minute-trend, minute-schedule or template.
40
+ STRATEGY=knockout-momentum
41
+ # BTC, ETH, SOL or XRP. XAU needs PRICE_SOURCE=pyth (your own Pyth key) or PRICE_SOURCE=replay.
42
+ MARKET=BTC
43
+ # Strategy parameters are PARAM_<NAME>. The names, defaults and bounds of each strategy are in README.md.
44
+ PARAM_STAKE_USDC=1
45
+ # More strategy modules to load, comma-separated paths. Each exports `strategies`.
46
+ EXTRA_STRATEGIES=
47
+
48
+ # --- Risk limits, checked before every trade (the bot's and every `open`) ---
49
+ # The largest stake of one position or round.
50
+ MAX_STAKE_USDC=1
51
+ # The most positions and live rounds open at once (1 to 12).
52
+ MAX_OPEN=2
53
+ # Required to trade, above 0. Nothing opens while today's loss (UTC), plus every open stake, would pass this.
54
+ DAILY_LOSS_USDC=
55
+ # Nothing opens that could leave the wallet below this, even if every open stake is lost.
56
+ MIN_BALANCE_USDC=0
57
+
58
+ # --- Prices for the strategy's signal and for paper fills ---
59
+ # coinbase (a public feed, no key; BTC, ETH, SOL, XRP), pyth (your own Pyth Pro key, below), auto (pyth when a key
60
+ # is set, coinbase when not) or replay (a recorded tape, paper mode only).
61
+ PRICE_SOURCE=coinbase
62
+ # Your Pyth Pro key, for PRICE_SOURCE=pyth or auto. It goes to Pyth and nowhere else, and no log line carries it.
63
+ # Set it here, or put it in a file and name the file in PYTH_API_KEY_FILE.
64
+ PYTH_API_KEY=
65
+ PYTH_API_KEY_FILE=
66
+ # Only for a market Pyth's public feed list cannot settle by itself: <market>=<Pyth feed id>, comma-separated.
67
+ PYTH_FEEDS=
68
+ # The tape for PRICE_SOURCE=replay: one JSON line a price, {"time": ms or ISO, "market": "BTC", "price": 1.23}.
69
+ REPLAY_FILE=
70
+
71
+ # --- Local state ---
72
+ # The folder for the log (journal.jsonl), the paper account (paper.json) and a cache of settled transactions.
73
+ STATE_DIR=.wheelman
74
+ # The USDC a paper account starts with.
75
+ PAPER_USDC=100
package/LICENSE ADDED
@@ -0,0 +1,191 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ Copyright 2026 Asymmetra Labs LTD
180
+
181
+ Licensed under the Apache License, Version 2.0 (the "License");
182
+ you may not use this file except in compliance with the License.
183
+ You may obtain a copy of the License at
184
+
185
+ http://www.apache.org/licenses/LICENSE-2.0
186
+
187
+ Unless required by applicable law or agreed to in writing, software
188
+ distributed under the License is distributed on an "AS IS" BASIS,
189
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
190
+ See the License for the specific language governing permissions and
191
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,288 @@
1
- # Temporary Holding Version
1
+ # Wheelman
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Wheelman, the Rekt trading bot and CLI: a bot, a command line and a local MCP server for Rekt
4
+ Knockout and Minute. You run it on your own machine, with your own wallet and your own RPC endpoint.
5
+ It uses the Rekt SDK, `@rekt-trading/1000x` from npm, for both games, and it sends nothing the risk
6
+ limits have not allowed.
7
+
8
+ **Status: 1.0.0, on mainnet.** Install it from npm as `@rekt-trading/wheelman`, or run it from a clone of this repository.
9
+
10
+ - Documentation: <https://docs.rekt.money>
11
+ - Contact: support@asymmetra.xyz
12
+ - License: Apache-2.0 (see `LICENSE`)
13
+
14
+ ## Start in two minutes
15
+
16
+ Node 22.18 or later.
17
+
18
+ ```sh
19
+ npm install -g @rekt-trading/wheelman
20
+ ```
21
+
22
+ Or run it from a clone: Node runs the TypeScript in `src/` directly there, with no build step. In a
23
+ clone, `npm link` puts `wheelman` on your path; without it, run `node src/cli.ts` in its place.
24
+
25
+ ```sh
26
+ git clone https://github.com/Asymmetra/rekt-wheelman wheelman && cd wheelman
27
+ npm install && npm link
28
+ ```
29
+
30
+ Then:
31
+
32
+ ```sh
33
+ wheelman setup # wallet, RPC, strategy, risk limits; writes .env (mode 600)
34
+ wheelman markets # every market, its stake bounds and fees
35
+ wheelman preview BTC long 1 --target 2 # what an open costs and pays, after every fee
36
+ wheelman open BTC long 1 --paper # a paper position: simulated, nothing sent
37
+ wheelman run --paper # the bot on paper
38
+ wheelman run --dry-run # builds and simulates the real transactions; sends nothing
39
+ wheelman run # the bot, trading
40
+ ```
41
+
42
+ The wallet needs SOL for fees and rent (0.01 SOL is enough to start) and USDC for stakes.
43
+
44
+ ## The CLI
45
+
46
+ | command | what it does |
47
+ |---|---|
48
+ | `markets` | every market: open or not and why, stake bounds, leverage, fees, room left on a side |
49
+ | `preview <market> <long\|short> <usd>` | the stake, the barrier, and the payout at the target and at the barrier, after every fee |
50
+ | `open <market> <long\|short> <usd>` | one Knockout position (`--target`, `--timer`), or a Minute round (`--minute`) |
51
+ | `close <id>` | asks the venue to close a position; the venue's keepers complete it |
52
+ | `positions` | open positions, live rounds, balances, today's result |
53
+ | `run [strategy]` | the bot |
54
+ | `setup` | onboarding; `--yes` takes every answer from the environment |
55
+ | `session start\|status\|end` | a session key for an agent (below) |
56
+ | `mcp` | a stdio MCP server with the same commands as tools (below) |
57
+
58
+ - `--paper` on `open`, `close`, `positions` and `run`: simulated fills on a paper account in
59
+ `.wheelman/paper.json`. Nothing is sent.
60
+ - `--dry-run` on `open`, `close`, `run` and `session`: builds the real transaction, simulates it on
61
+ mainnet, prints its compute units and bytes, and sends nothing. With no key, set `OWNER`.
62
+ - `-o json` prints one line: `{"ok": true, "data": ...}` or
63
+ `{"ok": false, "error": {"category", "code", "message", "retryable"}}`. `retryable` is true only
64
+ where sending the same request again cannot open a second position. The exit code is 0 on ok, 1 on
65
+ an error, 2 on a bad flag.
66
+
67
+ Every `open`, from the CLI, an agent or the bot, passes the same risk limits. Amounts in the output
68
+ are USDC with 6 decimals; ids are text.
69
+
70
+ ## Agents
71
+
72
+ Users bring their own agent (Claude Code, Codex, Cursor, or any MCP client). Wheelman hosts no agent
73
+ and holds no model key.
74
+
75
+ - **Session keys.** `wheelman session start --allowance 20 --expires 24h` (signed by the owner,
76
+ once) authorises a freshly generated key to trade for the owner's wallet: at most the allowance in USDC, until
77
+ the expiry. It also creates the owner's book when there is none and sends the key 0.01 SOL for its
78
+ own fees (`--fuel`). The key is written to `wallets/session-keypair.json` (mode 600) before the
79
+ transaction is sent. The command prints the two settings the agent needs: `OWNER` and
80
+ `SESSION_KEYPAIR_PATH`. `wheelman session end` (the owner) ends it, drops the allowance and
81
+ returns the key's SOL. The owner's key never goes to the agent.
82
+ - **MCP.** `wheelman mcp --env agent.env` serves `markets`, `preview`, `positions` and
83
+ `session_status`. With a session key configured it adds `open` and `close`, signed by the
84
+ session key; with `--paper` it adds them as paper-only. It never signs with the owner's key.
85
+
86
+ | client | how to add it |
87
+ |---|---|
88
+ | Claude Code | `claude mcp add wheelman -- node /path/to/wheelman/src/cli.ts mcp --env /path/to/agent.env` |
89
+ | Codex | in `~/.codex/config.toml`: `[mcp_servers.wheelman]`, `command = "node"`, `args = ["/path/to/wheelman/src/cli.ts", "mcp", "--env", "/path/to/agent.env"]` |
90
+ | Cursor | in `.cursor/mcp.json`: `{"mcpServers": {"wheelman": {"command": "node", "args": ["/path/to/wheelman/src/cli.ts", "mcp", "--env", "/path/to/agent.env"]}}}` |
91
+
92
+ `agent.env` holds `RPC_URL`, `OWNER`, `SESSION_KEYPAIR_PATH` and the risk limits, and no owner key.
93
+ - **Skill.** `skills/wheelman/SKILL.md` teaches an agent the CLI: copy the folder into your agent's
94
+ skills folder.
95
+
96
+ ## How it works
97
+
98
+ - **An open is an order.** The venue fills it at its own next price, after a short delay, or returns
99
+ the whole stake. Wheelman needs prices only for a strategy's signal and for paper fills.
100
+ - **The venue closes positions.** A position ends at its barrier (the stake is gone), at its
101
+ take-profit, at its timer, or after a close request. The venue's keepers send every close. A
102
+ Minute round runs on Minute's clock and has no early close.
103
+ - **The chain is the state.** Positions, balances and today's settled results are read from the
104
+ chain, so a restart or a fresh container is safe. `.wheelman/` holds the log, the paper account
105
+ and a cache of settled transactions (they never change, so each is fetched once).
106
+ - **One loop.** Once a second the strategy reads the latest price and its own positions and returns
107
+ intents. The risk guard checks each one. Each transaction is simulated first and sent only when it
108
+ simulated clean. The result is read from the chain (the opened `seq`, the settlement).
109
+ - **One code path.** The CLI, the MCP server and the bot call the same functions. The venue layer
110
+ (`src/client.ts`) has the shape of the SDK's Knockout client: `market`, `preview`, `open`,
111
+ `positions`, `close`, `settlement`, `history`, `build`.
112
+
113
+ ## Strategies
114
+
115
+ The bot runs one strategy. Pick one with `STRATEGY`, and set its parameters with `PARAM_<NAME>`. Every parameter has a default
116
+ and a bound, and the bot refuses a value outside the bound. The defaults are starting points, not
117
+ recommendations.
118
+
119
+ **`knockout-momentum`** (Knockout). Open in the direction of a move larger than trigger_bps over lookback_s.
120
+
121
+ | variable | default | bounds | meaning |
122
+ |---|---|---|---|
123
+ | `PARAM_STAKE_USDC` | 1 | 0.2 to 1000 | stake per position, in USDC |
124
+ | `PARAM_LOOKBACK_S` | 30 | 5 to 3600 | the window the move is measured over, in seconds |
125
+ | `PARAM_TRIGGER_BPS` | 5 | 1 to 1000 | the smallest move that opens a position, in basis points |
126
+ | `PARAM_TAKE_PROFIT_X` | 2 | 2 to 1000, or 0 | take-profit as a multiple of the stake, 0 for none |
127
+ | `PARAM_TIME_STOP_S` | 60 | 26 to 86400, or 0 | the position timer: the venue closes the position then; 0 for none |
128
+ | `PARAM_COOLDOWN_S` | 60 | 0 to 86400 | seconds to wait after a position ends |
129
+
130
+ **`knockout-fade`** (Knockout). Open against a sharp move; close when the price is back where the move started.
131
+
132
+ | variable | default | bounds | meaning |
133
+ |---|---|---|---|
134
+ | `PARAM_STAKE_USDC` | 1 | 0.2 to 1000 | stake per position, in USDC |
135
+ | `PARAM_LOOKBACK_S` | 20 | 5 to 3600 | the window the move is measured over, in seconds |
136
+ | `PARAM_TRIGGER_BPS` | 10 | 1 to 1000 | the smallest move that opens a position, in basis points |
137
+ | `PARAM_TAKE_PROFIT_X` | 2 | 2 to 1000, or 0 | take-profit as a multiple of the stake, 0 for none |
138
+ | `PARAM_TIME_STOP_S` | 30 | 26 to 86400, or 0 | the position timer: the venue closes the position then; 0 for none |
139
+ | `PARAM_COOLDOWN_S` | 60 | 0 to 86400 | seconds to wait after a position ends |
140
+ | `PARAM_CLOSE_ON_REVERT` | yes | yes, no | close when the price returns to where the move started |
141
+
142
+ **`knockout-straddle`** (Knockout). In a quiet market, open a long and a short of the same stake
143
+ together, in one transaction. A knockout ends one side; the other side runs to its take-profit or
144
+ its timer. One wallet may hold both sides of a market.
145
+
146
+ | variable | default | bounds | meaning |
147
+ |---|---|---|---|
148
+ | `PARAM_STAKE_USDC` | 1 | 0.2 to 1000 | stake of each side, in USDC |
149
+ | `PARAM_QUIET_S` | 60 | 5 to 3600 | the window the quiet filter looks at, in seconds |
150
+ | `PARAM_QUIET_BPS` | 3 | 0.1 to 1000 | open only when the range over quiet_s is at most this, in basis points |
151
+ | `PARAM_TAKE_PROFIT_X` | 3 | 2 to 1000, or 0 | take-profit as a multiple of the stake, 0 for none |
152
+ | `PARAM_TIME_STOP_S` | 120 | 26 to 86400, or 0 | the position timer: the venue closes the position then; 0 for none |
153
+ | `PARAM_COOLDOWN_S` | 120 | 0 to 86400 | seconds to wait after a position ends |
154
+
155
+ **`minute-trend`** (Minute). Each round, take the side of the move over lookback_s; skip a move below min_bps.
156
+
157
+ | variable | default | bounds | meaning |
158
+ |---|---|---|---|
159
+ | `PARAM_STAKE_USDC` | 1 | 0.01 to 100 | the total each round takes from the wallet, in USDC |
160
+ | `PARAM_LOOKBACK_S` | 30 | 5 to 3600 | the window the trend is measured over, in seconds |
161
+ | `PARAM_MIN_BPS` | 2 | 0 to 1000 | skip the round when the move is smaller than this, in basis points |
162
+
163
+ **`minute-schedule`** (Minute). Play every Nth minute at a fixed stake and side rule, inside a daily UTC window.
164
+
165
+ | variable | default | bounds | meaning |
166
+ |---|---|---|---|
167
+ | `PARAM_STAKE_USDC` | 1 | 0.01 to 100 | the total each round takes from the wallet, in USDC |
168
+ | `PARAM_EVERY_N` | 1 | 1 to 1440 | play in every Nth minute of the clock |
169
+ | `PARAM_SIDE` | alternate | long, short, alternate | the side of each round |
170
+ | `PARAM_START_HOUR_UTC` | 0 | 0 to 23 | the first hour of the window (UTC) |
171
+ | `PARAM_END_HOUR_UTC` | 24 | 1 to 24 | the hour the window ends (UTC) |
172
+
173
+ **`template`** (Knockout). A skeleton that never trades: copy `src/strategies/template.ts` to write
174
+ your own. A strategy is `{ id, game, params, onTick(ctx) }`; `onTick` returns intents and sends
175
+ nothing. Add it to `registry()` in `src/strategies/index.ts`, or load it with `EXTRA_STRATEGIES`.
176
+
177
+ The venue's own bounds also apply: the stake must be inside the venue's limits (Minute's for a
178
+ round), which Wheelman reads from the chain.
179
+
180
+ ## Configuration
181
+
182
+ Environment variables only: `.env` on your machine (or `--env <file>`), the host's settings
183
+ elsewhere. `.env.example` lists every variable with one line on each. The ones you set:
184
+
185
+ | variable | meaning |
186
+ |---|---|
187
+ | `RPC_URL` | required: your HTTPS RPC endpoint |
188
+ | `KEYPAIR_PATH` or `WALLET_SECRET_KEY` | the owner's wallet |
189
+ | `OWNER`, `SESSION_KEYPAIR_PATH` | an agent's settings: the wallet's address and its session key |
190
+ | `STRATEGY`, `MARKET`, `PARAM_*` | what the bot trades |
191
+ | `MAX_STAKE_USDC`, `MAX_OPEN`, `DAILY_LOSS_USDC`, `MIN_BALANCE_USDC` | the risk limits |
192
+ | `PRICE_SOURCE` | `coinbase` (live, no key), `pyth` (your own Pyth key), `auto` (Pyth when you set a key, else Coinbase) or `replay` (a tape, paper mode) |
193
+ | `PYTH_API_KEY` or `PYTH_API_KEY_FILE` | your own Pyth Pro key, for `pyth` and `auto` |
194
+
195
+ Wheelman checks every variable before its first RPC call and refuses a bad value with the reason.
196
+
197
+ ## Risk limits
198
+
199
+ The risk guard sits between every intent and the venue: the bot's, `open`'s and an agent's. It never
200
+ blocks a close. It counts the worst case, every open stake lost, so no limit is passed after the fact.
201
+
202
+ | variable | default | Wheelman opens nothing that would |
203
+ |---|---|---|
204
+ | `MAX_STAKE_USDC` | 1 | stake more than this in one position or round |
205
+ | `MAX_OPEN` | 2 | hold more than this many positions and rounds at once |
206
+ | `DAILY_LOSS_USDC` | required | lose more than this today (UTC), counting every open stake as lost |
207
+ | `MIN_BALANCE_USDC` | 0 | leave the wallet below this, counting every open stake as lost |
208
+
209
+ **Wheelman refuses to trade without a daily loss stop.** Today's loss is read from the chain, so a
210
+ restart does not reset it. A session key adds the owner's own ceiling: its allowance and expiry.
211
+
212
+ ## Paper mode
213
+
214
+ Paper results are priced by the SDK's own settlement arithmetic, with the terms a real position
215
+ freezes at open: the barrier, the target, the exit fee and the market's fee terms (the share of a
216
+ gain the venue keeps). A Minute round also pays Minute's own fees. Two things differ from live: the
217
+ fill is the next price Wheelman sees, not the venue's, and a one-shot command checks the barrier only
218
+ at the prices it reads (`run --paper` sees every tick). The borrow fee is not modelled; it is 0 today.
219
+ A paper result tests what Wheelman does; it does not say what live trading pays.
220
+
221
+ ## RPC: any provider
222
+
223
+ Drop in any endpoint: Helius, Triton, QuickNode, or your own node. Wheelman uses little:
224
+
225
+ - **Stream first, poll last.** The bot subscribes to its own accounts (websocket, or Yellowstone gRPC
226
+ with `GRPC_URL`), reads once after every reconnect, and reads at least every 30 s as a fallback.
227
+ - **Only its own accounts.** One `getMultipleAccounts` reads the venue, a market and the wallet's
228
+ book. When a position ends, it reads its own book's latest transactions once to learn what it
229
+ paid. It never scans a program's accounts.
230
+ - **One rate limit and one backoff per endpoint.** On HTTP 429 or JSON-RPC -32005 it waits 1 s,
231
+ doubles to 30 s with jitter, and stops loudly after 5 attempts. `RPC_FALLBACK_URL` takes over only
232
+ while `RPC_URL` fails.
233
+ - **`confirmed` on every call.** The blockhash and the priority fee are cached for a few seconds.
234
+ - **One send, one bounded rebroadcast.** It simulates first, sends with `maxRetries: 0`, sends the
235
+ same bytes again every 2 s, and stops when the transaction confirms or its blockhash expires. On a
236
+ Helius endpoint it asks Helius for the priority fee; elsewhere it uses recent fees. `SEND_URL` may
237
+ point at a send-only endpoint.
238
+ - **No key in a log.** Every log line names the host only and redacts keys from URLs and errors.
239
+ - **It refuses early:** a non-mainnet endpoint, an unlisted market or a stake the venue does not take
240
+ stops it before any spend.
241
+
242
+ ## Prices
243
+
244
+ A price is needed only for a strategy's signal and for paper fills. Pick the source with `PRICE_SOURCE`:
245
+
246
+ | `PRICE_SOURCE` | What it reads | Needs |
247
+ |---|---|---|
248
+ | `coinbase` (the default) | Coinbase's public ticker, for BTC, ETH, SOL and XRP | nothing: no key, no account |
249
+ | `pyth` | Pyth Pro's price stream, with your own key | `PYTH_API_KEY` (or `PYTH_API_KEY_FILE`) |
250
+ | `auto` | Pyth when a key is set, Coinbase when not | optional: `PYTH_API_KEY` |
251
+ | `replay` | a tape, for paper mode: one JSON line a price, `{"time": 1767225600000, "market": "BTC", "price": 100000}` | `REPLAY_FILE` |
252
+
253
+ To use your own Pyth key, set `PYTH_API_KEY=<your key>` and `PRICE_SOURCE=pyth` (or leave `PRICE_SOURCE=auto`).
254
+ The key goes to Pyth over its stream connection and nowhere else, and no log line carries it. Wheelman finds the
255
+ feed of your market in Pyth's public feed list when it starts, so there is no table to keep. When a market has no
256
+ single feed there, Wheelman refuses with the way to name one: `PYTH_FEEDS=<market>=<Pyth feed id>`. If Pyth closes
257
+ the connection six times without a price, Wheelman stops and says to check the key. A Pyth key is for prices only:
258
+ trading the venue never needs one.
259
+
260
+ To add a source, write one function in `src/prices.ts` that returns a `PriceSource`.
261
+
262
+ ## Hosting
263
+
264
+ The same variables work everywhere. One process, no database, no web server. A fatal error exits
265
+ non-zero, so every host restarts it. `Dockerfile` and `render.yaml` are templates for your own host:
266
+ you run Wheelman, with your own wallet; nobody hosts it for you.
267
+
268
+ - **Any server:** `npm ci --omit=dev && npm start` (that is `wheelman run`), under your process manager.
269
+ - **Docker:** `docker build -t wheelman .` then
270
+ `docker run --env-file .env -v "$PWD/wallets:/app/wallets:ro" wheelman`.
271
+ - **Render:** `render.yaml` describes one background worker. Set `RPC_URL` and `DAILY_LOSS_USDC` in
272
+ the dashboard and put the keypair in a Secret File named `bot-keypair.json` (or set
273
+ `WALLET_SECRET_KEY`).
274
+
275
+ ## Safety
276
+
277
+ - Wallet and session key files are written with mode 600 and never printed, logged or sent. Back up
278
+ the wallet.
279
+ - Use a wallet for Wheelman alone, and fund it with what you are ready to lose. At the barrier a
280
+ position pays nothing.
281
+ - Give an agent a session key, never the wallet. Size its allowance for one session and end it when
282
+ you are done: a token allowance has no clock of its own.
283
+ - Never commit `.env`, `wallets/` or a keypair file; `.gitignore` excludes them.
284
+ - Use `--paper` and `--dry-run` before trading, and after every change you make.
285
+
286
+ ## Development
287
+
288
+ `npm run check` runs the type check and the tests (Node's own test runner, no network).