dexbot 1.4.12 → 1.4.13

package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md

@@ -0,0 +1,243 @@
+# DEXBot2 Tuning Cheat Sheet
+
+This is a practical baseline for grid trading on DEXBot2.
+It is based on the engine's actual grid math and reset flow, not a universal "best" config.
+
+## Core rule
+
+- Start from `targetSpreadPercent ≈ 4 x incrementPercent`.
+- DEXBot2 enforces a minimum spread floor of about `2.1 x incrementPercent` and at least two spread slots, so the spread cannot be arbitrarily tight.
+- The tighter the grid, the more liquid and stable the market must be.
+
+## Structural vs Adaptive
+
+Keep these structural settings static in normal operation:
+
+- `incrementPercent`
+- `targetSpreadPercent`
+- `activeOrders`
+
+These settings define ladder geometry and order-size distribution, so changing them is a retune, not a tactical response.
+
+Use these adaptive settings for live trading behavior:
+
+- `weightDistribution`
+- `minPrice` / `maxPrice` ratio
+- debt / collateral actions
+
+That is the practical split:
+
+- increment/spread define the grid
+- AMA provides the anchor
+- weights adapt to trend
+- range ratio adapts slowly to former price action
+- debt/collateral actions manage CR
+
+## Quick ladder
+
+| Regime | Increment | Spread | Open orders | Typical use |
+|---|---:|---:|---:|---|
+| Loose | `0.6%` | `2.4%` | `20 / 20` or lower if size gets too small | Conservative, noisy, thinner, or less mature markets |
+| Basic | `0.5%` | `2.0%` | `20 / 20` | Safe default starting point |
+| Competitive | `0.4%` | `1.6%` | `10-20 / 10-20` | Liquid enough for tighter quoting |
+| Very competitive | `0.3%` | `1.2%` | `5-15 / 5-15` | Mature market, higher maintenance, lower slack |
+| Good-like / aggressive | `0.2%` | `0.8%` | `3-10 / 3-10` | Only when liquidity, fees, and precision support it |
+
+The main tradeoff is always the same:
+
+- lower increment = tighter ladder, but more churn and smaller per-order sizes
+- higher increment = wider ladder, less churn, but slower response and less quote quality
+
+## What each setting means
+
+### `incrementPercent`
+
+This is the spacing between grid levels.
+
+- lower values tighten the ladder
+- higher values reduce churn and give the market more room to move
+- if the pair is noisy or thin, do not force a tight increment
+
+### `targetSpreadPercent`
+
+This is the empty gap between the best buy and best sell rails.
+
+- keep it as small as the market can tolerate
+- `4x increment` is a healthy starting heuristic
+- `3x` is a conservative default, not a universal optimum
+
+### `weightDistribution`
+
+This controls how size is distributed across the ladder.
+
+- `0.5` is the neutral baseline
+- values above `0.5` concentrate more size near the market-adjacent orders
+- values below `0.5` flatten the ladder
+
+Use weights to express inventory preference:
+
+- mature, stable markets usually work best with flatter or near-neutral weights
+- trending markets can justify stronger weighting if you want more size near the spread
+- volatile markets usually prefer flatter weights so the bot does not over-commit near the edge
+- lower volatility lets you increase weights and concentrate more funds near market-adjacent orders
+- higher volatility argues for lower weights so more funds stay on the outer levels
+
+In DEXBot2, buy-side allocation is reversed internally so the near-market buy orders also receive the larger share when weights are higher.
+
+Negative weights are a special case:
+
+- use slightly negative weights only when you intentionally want more size toward the outer ladder
+- this makes sense in very volatile or mean-reverting markets where distant fills are realistic
+- for most markets, lowering toward `0` is safer than going negative
+- negative weights are not a default optimization; they are a deliberate fade/outer-liquidity choice
+
+### `botFunds`
+
+This is how much of each side's available balance gets committed.
+
+- `100% / 100%` is aggressive
+- leaving reserve gives you flexibility for fees, manual intervention, and regime changes
+- if orders get too small, reduce commitment or reduce order count
+
+### `activeOrders`
+
+This is the number of live orders kept near the market on each side.
+
+- more orders = smoother ladder, but smaller orders
+- fewer orders = larger orders, but less depth
+- `20 / 20` is a solid conservative baseline
+- as increment tightens, you may need fewer orders unless capital is large enough to keep order sizes meaningful
+
+### `minPrice` / `maxPrice`
+
+These define the outer range of the grid.
+
+- make the range only as wide as needed for the expected move until the next reset
+- `3x` is a conservative default, not a target
+- mature and frequently reset markets often do not need that much width
+- wider ranges make sense only if the bot must survive larger drift between resets
+- practical range bands:
+  - below `2x` = very competitive
+  - around `2x` = competitive
+  - around `3x` = conservative
+  - above `3x` = very conservative
+- treat range ratio as a slow-moving structural setting driven by former price action, not a fast tactical knob
+
+### `gridPrice`
+
+This controls the reference price used when the grid is rebuilt.
+
+- `null` uses the start price
+- `ama` or `ama1`..`ama4` recenters on the adaptive moving average
+- use AMA when the market drifts enough that a static center becomes stale
+
+## Fund allocation logic
+
+Use allocation settings to match market structure, not emotion.
+
+- mature and liquid markets can support more aggressive deployment
+- volatile or thin markets usually need more reserve and flatter allocation
+- if you want stronger quoting near the spread, increase the weight
+- if you want the ladder to feel smoother and less front-loaded, reduce the weight
+
+The clean mental model is:
+
+- `incrementPercent` controls spacing
+- `targetSpreadPercent` controls the empty buffer
+- `weightDistribution` controls size concentration
+- `botFunds` controls risk budget
+- `activeOrders` controls depth
+
+## When to adjust
+
+Adjust when the market changes enough that the current settings no longer make sense.
+
+Examples:
+
+- spreads are too tight and the bot churns
+- spreads are too wide and the bot misses fills
+- order sizes become dust-like
+- too much capital sits idle
+- the price center keeps drifting away from the grid
+- the pair becomes more or less liquid than before
+
+Do not tune on a fixed schedule. Tune when the bot's behavior stops matching the market.
+
+## Resetting a grid
+
+Use a normal reset when you want the bot to rebuild around the current market:
+
+```bash
+dexbot reset <bot-name>
+```
+
+That writes the recalculation trigger file. If the bot is running, it resets immediately; if it is stopped, it resets on the next start.
+
+Use a hard cleanup only when you want a full wipe of persisted order state.
+
+## AMA in practice
+
+AMA is the recentering mechanism.
+
+- it is calculated from 1h candle closes
+- it watches how far the adaptive center moves
+- once the move crosses the configured threshold, DEXBot2 triggers a grid recalculation
+- **AMA recently centering requires whitelisting the bot for the market adapter to work live (otherwise it only logs).**
+- `gridPrice: "ama"` tells the rebuilt grid to center itself on that AMA reference
+- `gridPrice: "pool"` or `gridPrice: "book"` centers the rebuilt grid on the live pair price instead
+- `gridPrice: null` falls back to the current `startPrice` reference
+
+### `poolRef`
+
+When using `startPrice: "pool"`, the bot discovers a pool matching your trading pair. If no such pool exists (e.g. a pair using a wrapped token without its own AMM pool), set `poolRef` to pin a proxy pool:
+
+```json
+"poolRef": "1.19.48"
+```
+
+The pool is fetched directly by ID (`get_objects`) — no discovery, no caching. Enter just the number (`"48"`) and the `1.19.` prefix is added automatically. Leave unset for normal discovery behavior.
+
+Practical interpretation:
+
+- if the market trends, AMA helps the bot stay centered
+- if the market is choppy, a higher delta threshold reduces unnecessary resets
+- if the market is moving and the bot lags, lower the threshold and recenter sooner
+
+## Suggested operating defaults
+
+For a conservative starting point:
+
+- `incrementPercent: 0.5`
+- `targetSpreadPercent: 2.0`
+- `activeOrders: 20 / 20`
+- `weightDistribution: 0.5 / 0.5`
+- `minPrice` and `maxPrice`: as narrow as the expected drift allows, not blindly `3x`
+
+For a more competitive market:
+
+- `incrementPercent: 0.4`
+- `targetSpreadPercent: 1.6`
+- keep order sizes meaningful before increasing order count
+- use weights only if you have a reason to prefer front-loaded inventory
+
+For a very competitive market:
+
+- `incrementPercent: 0.3`
+- `targetSpreadPercent: 1.2`
+- ensure liquidity is strong enough to justify the tighter ladder
+- watch churn, fills, and dust closely
+
+For an aggressive market:
+
+- `incrementPercent: 0.2`
+- `targetSpreadPercent: 0.8`
+- only use this when the pair is liquid enough to support it
+- reset discipline and fee control matter more at this level
+
+## Bottom line
+
+- tune for the market you actually have, not the market you wish you had
+- tighter grids belong to more mature markets
+- wider bounds are a safety margin, not a default optimum
+- weights shape inventory behavior
+- resets are for when the market regime has changed

package/claw/docs/POSITION_HEALTH.md

@@ -0,0 +1,117 @@
+# Position Health And Decision Loop
+
+This document covers the position health subsystem: on-chain position discovery, collateral ratio assessment, trend alignment, and the decision loop that ties them together.
+
+## Overview
+
+The subsystem has three layers:
+
+1. **Discovery** (`modules/position_discovery.ts`) — scans an account's on-chain call orders and normalizes them into position objects.
+2. **Health assessment** (`modules/position_health.ts`) — classifies each position into a collateral ratio zone, checks trend alignment, and recommends actions.
+3. **Decision loop** (`modules/decision_loop.ts`) — orchestrates discovery, trend analysis, and health assessment into a single evaluation cycle.
+
+The subsystem evaluates and recommends. It does not execute trades.
+
+## Position Discovery
+
+`discoverPositions(accountName)` scans the account's call orders on-chain and returns normalized position objects. It does not depend on PositionManager state files — it sees what actually exists on-chain.
+
+Each discovered position includes:
+
+- call order ID, borrower, market pair
+- debt amount and collateral amount (float-converted)
+- BTS-per-MPA derived from the settlement feed
+- computed collateral ratio
+- feed publication time
+
+`discoverPositionsSummary(accountName)` returns a compact summary with rounded values for quick inspection.
+
+## 3-Zone CR Model
+
+The health assessor classifies collateral ratios into three zones using the thresholds from `CR_ZONES` in the repo-root `modules/constants.ts`:
+
+| Zone | CR range | Status | Meaning |
+|---|---|---|---|
+| `red_low` | below `CR_ZONES.RED_LOW` (1.7) | `not_acceptable` | Near liquidation, immediate action needed |
+| `green` | `CR_ZONES.RED_LOW` (1.7) ≤ CR < `CR_ZONES.RED_HIGH` (3.0) | `safe` | Healthy operating range |
+| `red_high` | above `CR_ZONES.RED_HIGH` (3.0) | `over_collateralized` | Capital sitting idle, consider deploying |
+
+## Dual-Layer Actions
+
+When a position needs adjustment, the assessor recommends actions in two layers:
+
+- **Layer 1 (primary)**: adjust debt first — reduce debt when CR is low, increase debt when CR is high.
+- **Layer 2 (fallback)**: adjust collateral if debt changes are insufficient — add collateral when CR is low, withdraw collateral when CR is high.
+
+This mirrors the actual strategy levers: debt adjustments are the primary tool, collateral adjustments are the backup.
+
+Action priorities:
+
+| Zone | Priority | Layer 1 | Layer 2 |
+|---|---|---|---|
+| `red_low` | `immediate` | `reduce_debt` | `add_collateral` |
+| `green` | — | no action | no action |
+| `red_high` | `immediate` | `increase_debt` | `withdraw_collateral` |
+
+## Trend Alignment
+
+When a trend signal is available, the assessor checks whether the position direction is aligned with the trend:
+
+- A short position aligned with a `DOWN` trend is `aligned`.
+- A short position opposed to an `UP` trend with confidence >= 50% triggers a `review_direction` action.
+- Neutral trends produce no directional action.
+
+## CR Adjustment Planning
+
+CR math is handled by the shared planner at `modules/cr_planner.ts` (root level, not claw), which provides `debtDeltaForTargetCr()` and `collateralDeltaForTargetCr()`. Claw's position health module consumes these through the planner interface. Any executed CR adjustment should be followed by a grid rebuild, because the available-funds baseline is no longer valid after the debt or collateral leg changes.
+
+## Decision Loop Planning
+
+The decision loop in `modules/decision_loop.ts` combines all signals into a unified assessment:
+
+- CR adjustment intent (debt first, collateral second)
+- price range ratio recommendation based on historical price action
+- the CR plan should be treated as structural, not tactical, so execution code must rebuild the grid after it applies
+
+## Decision Loop
+
+`evaluate(accountName, options)` runs one full cycle:
+
+1. Discover all on-chain positions for the account.
+2. Fetch trend input per market (feed price + market price).
+3. Update a per-market trend analyzer (Kalman filter-based, state persists across calls).
+4. Assess each position's health with the trend signal.
+5. Sort assessments by action priority (immediate first).
+6. Return assessments with a summary of zone distribution and action counts.
+
+The summary includes:
+
+- zone counts (`red_low`, `green`, `red_high`)
+- immediate action count
+- `allGreen` flag for quick health checks
+
+## Position Manager Watch
+
+`modules/position_manager_watch.ts` is a PM2-compatible watcher process that keeps `PositionManager` state synchronized and reacts to fills. It does not invoke `decision_loop.evaluate()` itself.
+
+```bash
+npm run service:position-watch -- --account your-account
+```
+
+## Related Modules
+
+- `modules/feed_price_source.ts` — fetches on-chain settlement feed prices and order book mid-prices for trend input.
+- `modules/kibana_price_source.ts` — alternative price source using Kibana for historical candle data (order book fills and LP pool swaps).
+- `modules/position_manager.ts` — persistent short-position tracking (create, update, close, export). Separate from on-chain discovery.
+
+## Source Of Truth
+
+The executable behavior lives in the modules. This document should be kept aligned with:
+
+- `../cr_planner.ts` (root level)
+- `modules/position_health.ts`
+- `modules/position_discovery.ts`
+- `modules/decision_loop.ts`
+- `modules/feed_price_source.ts`
+- `modules/position_manager_watch.ts`
+- `claw/tests/test_position_health.ts`

package/claw/docs/RUNTIME_COMPARISON.md

@@ -0,0 +1,256 @@
+# Claw Runtime Comparison
+
+This note compares the nine runtime families supported by the Claw bridge layer (the eight listed below plus memU):
+
+- OpenClaw
+- Hermes
+- OpenFang
+- NanoBot
+- PicoClaw
+- NanoClaw
+- ZeroClaw
+- NullClaw
+
+The comparison is based on the current `claw/` bridge design and runtime metadata. It is a practical analysis, not a formal benchmark report.
+
+## What The Bridge Optimizes For
+
+The bridge is trying to satisfy eight different operating modes with one shared BitShares surface:
+
+- very small footprint and fast startup
+- broad assistant and plugin coverage
+- CLI-first workspace integration
+- simple MCP-based integration
+- low-cost hardware and launcher-based workflows
+- workspace-native skill loading and local manifest workflows
+
+That means each runtime is a different compromise, not a strict upgrade path.
+
+## Comparison Axes
+
+The useful axes are:
+
+- runtime footprint
+- startup latency
+- integration style
+- developer ergonomics
+- ecosystem breadth
+- operational complexity
+
+## Deep Dive
+
+### OpenClaw
+
+OpenClaw is the broadest and heaviest option.
+
+Strengths:
+
+- Richest runtime surface.
+- Native plugin model is a strong fit for extension-heavy workflows.
+- Broadest assistant-style experience among the eight core runtimes (excluding memU).
+- Best when the bridge needs to live inside a feature-rich product rather than a small runtime shim.
+
+Tradeoffs:
+
+- Highest operational complexity.
+- Largest dependency and runtime footprint.
+- More moving parts means more integration surface to keep aligned.
+
+Best fit:
+
+- Desktop or server environments where footprint is less important.
+- Teams that value extensibility and a mature assistant ecosystem.
+- Workflows that benefit from plugin registration over a narrow CLI surface.
+
+### Hermes
+
+Hermes is the best fit when Claw should be one capability inside a broader assistant runtime rather than the whole product.
+
+Strengths:
+
+- Broad agent platform with memory, messaging, cron, browser automation, voice, and subagent delegation.
+- MCP-first integration lets Hermes consume the shared Claw surface without vendoring DEXBot2-specific runtime code.
+- Good fit when trading is only one part of a larger assistant workflow.
+
+Tradeoffs:
+
+- Heavier operational surface than the narrower runtimes.
+- Adds little value if the only requirement is safe DEXBot inspection and execution.
+- The integration should stay MCP-first; a Hermes-specific bridge wrapper would mostly duplicate existing Claw behavior.
+
+Best fit:
+
+- Users who want a general-purpose assistant that can also trade.
+- Always-on or messaging-driven workflows where memory and scheduling matter.
+- Teams that want Hermes features without moving BitShares execution outside DEXBot2.
+
+### OpenFang
+
+OpenFang is the CLI-first local workspace integration with the thinnest maintenance surface.
+
+Strengths:
+
+- Local CLI bridge keeps the integration narrow and explicit.
+- Generated `SKILL.md` can wrap the shared Claw surface without vendoring OpenFang internals.
+- Good fit when the runtime should consume commands from a workspace skill file instead of embedding Claw as a library.
+
+Tradeoffs:
+
+- Less feature-rich than a full plugin-driven assistant platform.
+- Depends on OpenFang's local CLI and workspace skill conventions.
+- Best when the bridge stays deliberately thin.
+
+Best fit:
+
+- Local workspace installs.
+- Operators who want the smallest possible adapter between OpenFang and DEXBot2.
+- CLI-first workflows that do not need a new transport layer.
+
+### NanoBot
+
+NanoBot sits between OpenClaw and PicoClaw in spirit, but it is a different tradeoff: a smaller Python codebase with MCP integration.
+
+Strengths:
+
+- Easier to inspect and adapt than a large feature-rich assistant stack.
+- MCP gives a simple external-tool boundary.
+- Good for lightweight assistant workflows and rapid iteration.
+
+Tradeoffs:
+
+- Slower startup and heavier runtime cost than Go or Rust.
+- Python dependency management adds operational friction compared with a static or near-static binary workflow.
+- Less suited to very small hardware or always-on resource-constrained deployments.
+
+Best fit:
+
+- Teams that want a lightweight assistant they can reason about quickly.
+- Environments where Python ergonomics matter more than the absolute smallest footprint.
+- MCP-first integrations with moderate complexity.
+
+### PicoClaw
+
+PicoClaw is the smallest Go-based option in the set and is the most launcher-oriented.
+
+Strengths:
+
+- Small binary deployment model.
+- Good fit for low-cost boards and constrained Linux targets.
+- MCP-based tool integration keeps the external surface consistent.
+- Web launcher support makes it friendlier for desktop-style setup and usage.
+
+Tradeoffs:
+
+- The platform is still evolving quickly, so behavior and footprint can shift more often.
+- Less mature than the longer-running ecosystems around OpenClaw or the broader upstream Rust tooling around ZeroClaw.
+- The launcher and workspace behavior add some setup expectations that are easy to miss without good docs.
+
+Best fit:
+
+- Small-board deployments.
+- Users who want a low-footprint Go runtime with a practical launcher.
+- Deployments where the assistant needs to be easy to bootstrap, not just tiny.
+
+### NanoClaw
+
+NanoClaw is the Claude Code skill-driven local runtime with a narrow bridge wrapper.
+
+Strengths:
+
+- Uses a plain `SKILL.md` skill file and a local bridge script.
+- Fits the same shared Claw command surface without introducing a separate transport stack.
+- Keeps the bridge skill name distinct from NanoClaw's bundled `claw` skill.
+
+Tradeoffs:
+
+- More workspace-convention dependent than the external-tool runtimes.
+- Newer than the longer-established OpenClaw, NanoBot, and PicoClaw flows.
+- Best experience depends on NanoClaw's `.claude/skills` layout and local CLI invocation.
+
+Best fit:
+
+- Users who want a Claude Code style local assistant with a narrow bridge.
+- Workspace-driven installs where a generated `bitshares-claw` skill file is acceptable.
+- Operators who want to keep runtime integration simple and file-based.
+
+### ZeroClaw
+
+ZeroClaw is the smallest and most constrained option.
+
+Strengths:
+
+- Best cold-start behavior.
+- Best fit for small, static, local deployments.
+- Clear skill-manifest model with `SKILL.toml`.
+- Best when the bridge should feel tiny and deterministic rather than broad.
+
+Tradeoffs:
+
+- Rust-oriented integration is more specialized than the other options.
+- The workflow is more manifest-driven, so the runtime surface is less flexible than plugin-first systems.
+- Better for fast, narrow automation than for a broad assistant shell.
+
+Best fit:
+
+- Edge devices.
+- Minimal local automation.
+- Users who want the most predictable, lowest-overhead runtime.
+
+### NullClaw
+
+NullClaw is the Zig-native runtime focused on workspace skill loading.
+
+Strengths:
+
+- Native `SKILL.toml` loading in the workspace skill tree.
+- MCP server support alongside the built-in skill loader.
+- Strong fit for local, file-based assistant workflows.
+- Keeps the bridge surface aligned with the NullClaw workspace conventions.
+
+Tradeoffs:
+
+- Newer integration path than the longer-established OpenClaw, NanoBot, and PicoClaw flows.
+- More workspace-centric than the CLI-first ZeroClaw wrapper.
+- Best experience depends on `~/.nullclaw/workspace/skills` and NullClaw's config conventions.
+
+Best fit:
+
+- Users who want a Zig-native assistant runtime with native skill manifests.
+- Local workflows where the bridge should slot into a NullClaw workspace directly.
+- Operators who want workspace-native NullClaw support without changing the shared Claw bridge surface.
+
+## Recommendation Matrix
+
+If you optimize primarily for:
+
+- **Lowest footprint**: ZeroClaw
+- **Broadest feature set**: OpenClaw
+- **General-purpose assistant that can also trade**: Hermes
+- **CLI-first workspace integration**: OpenFang
+- **Simplest external tool boundary**: NanoBot or PicoClaw, depending on whether you want Python or Go
+- **Skill-file driven local assistant**: NanoClaw
+- **Lowest-cost hardware**: PicoClaw, then ZeroClaw
+- **Most mature assistant ecosystem**: OpenClaw
+- **Fastest local command-style integration**: ZeroClaw
+- **Workspace-native skill manifests**: NullClaw
+
+## Practical Rule Of Thumb
+
+- Choose **OpenClaw** if the bridge should live inside a larger assistant product with rich extension points.
+- Choose **Hermes** if you want a broader assistant runtime and want Claw to remain an MCP-backed trading capability inside it.
+- Choose **OpenFang** if you want a CLI-first workspace bridge with minimal maintenance overhead.
+- Choose **NanoBot** if you want a compact Python assistant that is easy to modify.
+- Choose **PicoClaw** if you want a small Go runtime with MCP and launcher support.
+- Choose **NanoClaw** if you want a Claude Code skill-driven local runtime with a narrow bridge.
+- Choose **ZeroClaw** if the bridge must be tiny and deterministic.
+- Choose **NullClaw** if you want a Zig-native runtime with workspace skill loading and MCP support.
+
+## Source Of Truth
+
+The executable behavior lives in the `claw/` modules and scripts. This comparison is documentation only and should be kept aligned with:
+
+- `../modules/claw_runtime_matrix.ts`
+- `../modules/claw_catalog.ts`
+- `../modules/claw_manifest.ts`
+- `../modules/claw_skill_md.ts`
+- `../scripts/claw_skill_md.ts`

package/claw/ecosystem.config.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+const path = require('node:path');
+
+// The compiled ecosystem config (claw/ecosystem.config.ts → dist/claw/) anchors
+// all paths to the dist/claw build output. This committed .cjs mirrors that
+// layout so `pm2 start ecosystem.config.cjs` works from the claw/ package root.
+const DIST_CLAW = path.join(__dirname, '..', 'dist', 'claw');
+
+module.exports = {
+  apps: [
+    {
+      name: 'ai-bot-position-watch',
+      script: path.join(DIST_CLAW, 'modules', 'position_manager_watch.js'),
+      cwd: DIST_CLAW,
+      autorestart: true,
+      max_memory_restart: '200M',
+      watch: false,
+      error_file: path.join(DIST_CLAW, 'data', 'logs', 'ai-bot-position-watch-error.log'),
+      out_file: path.join(DIST_CLAW, 'data', 'logs', 'ai-bot-position-watch.log'),
+      log_date_format: 'YY-MM-DD HH:mm:ss.SSS',
+      merge_logs: false,
+      combine_logs: true,
+      max_restarts: 13,
+      min_uptime: 60000,
+      restart_delay: 3000
+    }
+  ]
+}

package/claw/examples/claw_consumer_example.ts

@@ -0,0 +1,54 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+const { createClawInfrastructure } = require('../modules/claw_infra');
+const { getErrorMessage } = require('../../modules/utils/errors');
+
+async function main() {
+  const accountName = process.argv[2] || null;
+  const pair = process.argv[3] || 'BTS/USD';
+  const [baseSymbol, quoteSymbol] = pair.split('/');
+
+  const claw = createClawInfrastructure({
+    accountName,
+    runtime: {
+      name: 'claw-consumer',
+      accountName
+    }
+  });
+
+  const market = await claw.market.readMarketSnapshot(baseSymbol, quoteSymbol, 5);
+  const account = accountName ? await claw.market.readAccountSnapshot(accountName) : null;
+  const orderUtils = claw.order.utils;
+  const gapSlots = orderUtils.calculateGapSlots(0.4, 1.6);
+  const defaultWeights = claw.order.constants.DEFAULT_CONFIG.weightDistribution;
+
+  await claw.stateStore.patch({
+    lastSeenPair: pair,
+    lastSeenAt: new Date().toISOString()
+  });
+
+  console.log(JSON.stringify({
+    account: account ? {
+      balances: account.balances,
+      openOrders: account.openOrders.length
+    } : null,
+    market: {
+      asks: Array.isArray(market.orderBook.asks) ? market.orderBook.asks.length : 0,
+      bids: Array.isArray(market.orderBook.bids) ? market.orderBook.bids.length : 0,
+      headBlock: market.dynamicGlobalProperties ? market.dynamicGlobalProperties.head_block_number : null,
+      tickerLatest: market.ticker ? market.ticker.latest : null
+    },
+    order: {
+      defaultWeights,
+      gapSlots,
+      utilityKeys: Object.keys(orderUtils).slice(0, 10)
+    }
+  }, null, 2));
+}
+
+main().catch((err) => {
+  console.error(getErrorMessage(err));
+  process.exit(1);
+});
+export {};