@rekt-trading/wheelman 0.0.0-stage → 1.0.1
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 +75 -0
- package/LICENSE +191 -0
- package/README.md +287 -2
- package/dist/account.js +162 -0
- package/dist/cli.js +163 -0
- package/dist/client.js +245 -0
- package/dist/commands.js +332 -0
- package/dist/config.js +256 -0
- package/dist/errors.js +24 -0
- package/dist/journal.js +63 -0
- package/dist/mcp.js +117 -0
- package/dist/minute.js +140 -0
- package/dist/paper.js +220 -0
- package/dist/prices.js +374 -0
- package/dist/risk.js +60 -0
- package/dist/rpc.js +321 -0
- package/dist/runner.js +189 -0
- package/dist/setup.js +133 -0
- package/dist/strategies/index.js +34 -0
- package/dist/strategies/knockout.js +111 -0
- package/dist/strategies/minute.js +53 -0
- package/dist/strategies/template.js +24 -0
- package/package.json +57 -4
- package/skills/wheelman/SKILL.md +61 -0
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
|
-
#
|
|
1
|
+
# Wheelman
|
|
2
2
|
|
|
3
|
-
|
|
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).
|