dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/autotrade/assets/limits.schema.json

@@ -0,0 +1,569 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dexterm.xyz/schemas/limits.schema.json",
+  "title": "dexterm-limits/1",
+  "description": "dexterm real-mode limits: $DEXTERM_HOME/autotrade/real/limits.json. A number in global replaces the placeholder default (null turns it off); every other scope can only tighten (the stricter number wins). Only `dexterm autotrade limits` writes it; raising needs a typed confirmation on a real terminal.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema"
+  ],
+  "properties": {
+    "schema": {
+      "const": "dexterm-limits/1"
+    },
+    "global": {
+      "$ref": "#/$defs/globalSet"
+    },
+    "modes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "real": {
+          "$ref": "#/$defs/set"
+        },
+        "paper": {
+          "$ref": "#/$defs/set"
+        }
+      }
+    },
+    "strategies": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/set"
+      }
+    },
+    "accounts": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/set"
+      }
+    },
+    "updatedAt": {
+      "type": "number"
+    },
+    "migratedFrom": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "set": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "perTradeSol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "the most SOL one buy signal may spend (a bigger buy is clamped down to it) (SOL; a cap: smaller is stricter)"
+        },
+        "perTradePct": {
+          "type": "number",
+          "minimum": 0.01,
+          "maximum": 100,
+          "description": "the most one buy may spend as a percent of the book (bookSol, else the strategy book); with perTradeSol set too, the smaller wins (% of book; a cap: smaller is stricter)"
+        },
+        "dailySol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "SOL all buy signals may spend per local day (a buy over it is refused) (SOL/day; a cap: smaller is stricter)"
+        },
+        "buysPerDay": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1000000,
+          "description": "buy signals per local day (0 = no buys) (buys/day; a cap: smaller is stricter)"
+        },
+        "maxOpenPositions": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "real positions open at once, across every strategy and account on this home (open; a cap: smaller is stricter)"
+        },
+        "maxExposurePct": {
+          "type": "number",
+          "minimum": 0.01,
+          "maximum": 100,
+          "description": "the cost of every open real position together, as a percent of the book (a buy is clamped to what is left) (% of book; a cap: smaller is stricter)"
+        },
+        "minPositionSol": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1000000000000,
+          "description": "a buy smaller than this after every clamp is refused (no dust orders) (SOL; a floor: larger is stricter)"
+        },
+        "maxPositionSol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "the most SOL one position may cost, adds included (a buy is clamped to what is left) (SOL; a cap: smaller is stricter)"
+        },
+        "perCoinSolPerDay": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "SOL spent on one coin per local day, re-entries included (a buy over it is refused) (SOL/day; a cap: smaller is stricter)"
+        },
+        "perCoinBuysPerDay": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "buy signals on one coin per local day (buys/day; a cap: smaller is stricter)"
+        },
+        "bookSol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "what the percent limits are a percent of: the size of YOUR account (unset = the strategy's own book) (SOL; a cap: smaller is stricter)"
+        },
+        "dailyLossSol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "when the day's realized loss reaches this, no new buy goes out until the next local day (exits still do) (SOL/day; a cap: smaller is stricter)"
+        },
+        "maxDrawdownSol": {
+          "type": "number",
+          "minimum": 1e-06,
+          "maximum": 1000000000000,
+          "description": "the drawdown breaker: realized PnL this far below its peak trips it; no new buy until you reset it (typed) (SOL; a cap: smaller is stricter)"
+        },
+        "lossStreak": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "this many losing closes in a row pause new buys for lossStreakPauseMin (losses; a cap: smaller is stricter)"
+        },
+        "lossStreakPauseMin": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 525600,
+          "description": "how long the loss-streak pause lasts (min; a floor: larger is stricter)"
+        },
+        "maxHoldMinutes": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 525600,
+          "description": "a real position held this long gets its exit signal (the stricter of this and the exit profile's own cap) (min; a cap: smaller is stricter)"
+        },
+        "minLiquidityUsd": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1000000000000,
+          "description": "no buy on a coin with less pool liquidity (unknown liquidity is refused while this is set) (USD; a floor: larger is stricter)"
+        },
+        "minMcapUsd": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1000000000000,
+          "description": "no buy on a coin below this market cap (unknown is refused while this is set) (USD; a floor: larger is stricter)"
+        },
+        "maxSlippageBps": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "the slippage tolerance a signal states (the stricter of this and the strategy's) (bps; a cap: smaller is stricter)"
+        },
+        "maxPriceImpactPct": {
+          "type": "number",
+          "minimum": 0.01,
+          "maximum": 100,
+          "description": "the price impact a buy may have on the pool (constant-product estimate): a buy is clamped to it; the signal states it (%; a cap: smaller is stricter)"
+        },
+        "signalTtlSec": {
+          "type": "integer",
+          "minimum": 10,
+          "maximum": 600,
+          "description": "how long an executor may act on a signal (the stricter of this and the channel setting) (s; a cap: smaller is stricter)"
+        },
+        "maxBuysPerMinute": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10000,
+          "description": "the signal rate limit: buy signals in any 60 s (buys/min; a cap: smaller is stricter)"
+        },
+        "maxSellsPerMinute": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "OPTIONAL: sells are never capped unless you set this; a sell over it waits for the next tick (sells/min; a cap: smaller is stricter)"
+        },
+        "minForwardTrades": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "the evidence floor for real: arming needs a COMPLETED forward test of these exact rules with at least this many closed paper trades, and a backtest on record (below it only a typed override on your own terminal arms, journaled) (trades; a floor: larger is stricter)"
+        },
+        "executorSilenceMin": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 525600,
+          "description": "no heartbeat, receipt or ack from your executor for this long pauses new buy signals (exits still go out) (min; a cap: smaller is stricter)"
+        }
+      }
+    },
+    "globalSet": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "perTradeSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "the most SOL one buy signal may spend (a bigger buy is clamped down to it) (SOL; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "perTradePct": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0.01,
+              "maximum": 100,
+              "description": "the most one buy may spend as a percent of the book (bookSol, else the strategy book); with perTradeSol set too, the smaller wins (% of book; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "dailySol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "SOL all buy signals may spend per local day (a buy over it is refused) (SOL/day; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "buysPerDay": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1000000,
+              "description": "buy signals per local day (0 = no buys) (buys/day; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxOpenPositions": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100000,
+              "description": "real positions open at once, across every strategy and account on this home (open; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxExposurePct": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0.01,
+              "maximum": 100,
+              "description": "the cost of every open real position together, as a percent of the book (a buy is clamped to what is left) (% of book; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "minPositionSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1000000000000,
+              "description": "a buy smaller than this after every clamp is refused (no dust orders) (SOL; a floor: larger is stricter)"
+            }
+          ]
+        },
+        "maxPositionSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "the most SOL one position may cost, adds included (a buy is clamped to what is left) (SOL; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "perCoinSolPerDay": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "SOL spent on one coin per local day, re-entries included (a buy over it is refused) (SOL/day; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "perCoinBuysPerDay": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100000,
+              "description": "buy signals on one coin per local day (buys/day; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "bookSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "what the percent limits are a percent of: the size of YOUR account (unset = the strategy's own book) (SOL; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "dailyLossSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "when the day's realized loss reaches this, no new buy goes out until the next local day (exits still do) (SOL/day; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxDrawdownSol": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1e-06,
+              "maximum": 1000000000000,
+              "description": "the drawdown breaker: realized PnL this far below its peak trips it; no new buy until you reset it (typed) (SOL; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "lossStreak": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "description": "this many losing closes in a row pause new buys for lossStreakPauseMin (losses; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "lossStreakPauseMin": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 525600,
+              "description": "how long the loss-streak pause lasts (min; a floor: larger is stricter)"
+            }
+          ]
+        },
+        "maxHoldMinutes": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 525600,
+              "description": "a real position held this long gets its exit signal (the stricter of this and the exit profile's own cap) (min; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "minLiquidityUsd": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1000000000000,
+              "description": "no buy on a coin with less pool liquidity (unknown liquidity is refused while this is set) (USD; a floor: larger is stricter)"
+            }
+          ]
+        },
+        "minMcapUsd": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1000000000000,
+              "description": "no buy on a coin below this market cap (unknown is refused while this is set) (USD; a floor: larger is stricter)"
+            }
+          ]
+        },
+        "maxSlippageBps": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "description": "the slippage tolerance a signal states (the stricter of this and the strategy's) (bps; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxPriceImpactPct": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 0.01,
+              "maximum": 100,
+              "description": "the price impact a buy may have on the pool (constant-product estimate): a buy is clamped to it; the signal states it (%; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "signalTtlSec": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 10,
+              "maximum": 600,
+              "description": "how long an executor may act on a signal (the stricter of this and the channel setting) (s; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxBuysPerMinute": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 10000,
+              "description": "the signal rate limit: buy signals in any 60 s (buys/min; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "maxSellsPerMinute": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "description": "OPTIONAL: sells are never capped unless you set this; a sell over it waits for the next tick (sells/min; a cap: smaller is stricter)"
+            }
+          ]
+        },
+        "minForwardTrades": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100000,
+              "description": "the evidence floor for real: arming needs a COMPLETED forward test of these exact rules with at least this many closed paper trades, and a backtest on record (below it only a typed override on your own terminal arms, journaled) (trades; a floor: larger is stricter)"
+            }
+          ]
+        },
+        "executorSilenceMin": {
+          "oneOf": [
+            {
+              "type": "null",
+              "description": "off: this limit does not apply"
+            },
+            {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 525600,
+              "description": "no heartbeat, receipt or ack from your executor for this long pauses new buy signals (exits still go out) (min; a cap: smaller is stricter)"
+            }
+          ]
+        }
+      }
+    }
+  }
+}

package/dist/packages/autotrade/examples/executor/README.md

@@ -0,0 +1,70 @@
+# dexterm executor reference kit
+
+dexterm holds no key and signs nothing. In real mode a strategy sends a **LIVE TRADE FIRE** signal
+(`dexterm-trade-fire/1`) for every buy and sell. **Your own executor** acts on it: a Telegram trading bot you chose,
+or any script.
+
+This folder holds three small executors you can wire up in minutes, so you can see the whole path work before
+anything can spend money:
+
+| file | channel | how dexterm reaches it |
+|---|---|---|
+| `webhook-executor.mjs` | webhook | `dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal` |
+| `signal-cmd-executor.mjs` | command hook | `dexterm autotrade signal channels --signal-cmd '["/abs/node","/abs/signal-cmd-executor.mjs","--account","main"]'` |
+| `jsonl-tail-executor.mjs` | JSONL stream | `dexterm autotrade signal channels --jsonl on` (add `--jsonl-signed on` for HMAC lines) |
+
+Each one handles every signal the same way:
+
+1. It verifies the HMAC, when you give it the secret file. Without `--secret-file` it acts on unsigned bodies (it says `HMAC NOT checked` when it starts); before you put a real trade into `act()`, run it with `--secret-file` and `--require-hmac`.
+2. It checks the account id.
+3. It dedupes by nonce. Delivery is at-least-once, so a repeat is normal, and the seen set survives a restart.
+4. It ignores anything past `expiresAt` (the TTL).
+5. It writes a receipt to dexterm's `autotrade/real/receipts.jsonl` and a heartbeat to `autotrade/real/executor.jsonl`.
+
+**All of them are DRY RUN.** `act()` in `kit.mjs` only logs what it WOULD do, and the receipt says so:
+status `rejected`, reason `dry-run: would BUY …`. There is no wallet code, no key and no chain call anywhere in this
+kit. Trading for real means replacing `act()` with your own code, or handing the order to your own bot. That is your
+code and your wallet, never dexterm's.
+
+## Five minutes, end to end (paper money only)
+
+```sh
+# 1. a secret for the HMAC (written to a 0600 file, stored in your keychain, never printed)
+dexterm autotrade signal secret generate --out ~/.dexterm-exec.secret
+
+# 2. start the kit's webhook executor (dry run) in another terminal
+node webhook-executor.mjs --account main --secret-file ~/.dexterm-exec.secret
+
+# 3. point dexterm at it, then prove the round trip
+dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal
+dexterm autotrade signal test          # per channel: delivered, latency, the kit's receipt
+dexterm autotrade executor status      # alive · last heartbeat · last receipt · lag
+```
+
+`signal test` sends a signal marked `test: true` that names no mint, so there is nothing in it to trade. The kit
+receipts it as `rejected` (`test signal: received, never traded`).
+
+## Heartbeats and the silence pause
+
+dexterm counts a heartbeat, a receipt, or an ack on the webhook or command hook as a sign of life. When it hears
+nothing for longer than your `executorSilenceMin` limit (placeholder: 15 min), a real run **pauses new buy
+signals** and tells you in the run log and on Telegram. Exits keep going out. The kit sends a heartbeat every 60 s
+(`--heartbeat-sec`). Your own executor can append the same line, POST it to the run's loopback listener
+(`--executor-port`), or run `dexterm autotrade executor heartbeat`:
+
+```json
+{"schema":"dexterm-executor-heartbeat/1","at":1761300000000,"executor":"my-bot","accountId":"main","dryRun":false,"lastNonce":42}
+```
+
+## Receipts
+
+A receipt is data only. It moves a real position from `unconfirmed` to executed / rejected / failed. With a fill
+(`priceUsd`, `sizeSol`, `tokens`, `txSig`), dexterm also measures how far the real fill was from its own paper fill:
+slippage, latency, partial fills and rejections. That shows in `dexterm autotrade audit`, `signal status` and
+`dexterm autotrade report`.
+
+```json
+{"schema":"dexterm-trade-receipt/1","signalId":"<the signal's id>","nonce":42,"accountId":"main","status":"executed","at":1761300001200,"fill":{"priceUsd":0.00123,"sizeSol":0.25,"tokens":40650,"txSig":null},"reason":null,"executor":"my-bot"}
+```
+
+See `telegram-bot-recipe.md` for the Telegram trading-bot setup. The bot executes, and dexterm never signs.