openbroker 1.0.42 → 1.0.44

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.44] - 2026-02-25
+
+### Added
+- **Trade Fills**: New `fills` command to view trade fill history with prices, fees, and realized PnL
+- **Order History**: New `orders` command to view all historical orders (filled, canceled, open, triggered, rejected)
+- **Order Status**: New `order-status` command to check the status of a specific order by OID or CLOID
+- **Fee Schedule**: New `fees` command to view fee tier, maker/taker rates, referral/staking discounts, and daily volumes
+- **Candle Data**: New `candles` command to view OHLCV candlestick data with configurable intervals and bar counts
+- **Funding History**: New `funding-history` command to view historical funding rates for any asset
+- **Recent Trades**: New `trades` command to view the tape (time & sales) for an asset with buy/sell volume breakdown
+- **Rate Limit**: New `rate-limit` command to check API rate limit usage, capacity, and cumulative volume
+- **Cumulative Funding on Positions**: The `positions` command now shows cumulative funding received/paid per position
+- **Client Extensions**: Added 9 new methods to HyperliquidClient
+  - `getUserFunding()` - Funding ledger updates
+  - `getUserFills()` - Trade fill history
+  - `getHistoricalOrders()` - All orders with statuses
+  - `getOrderStatus()` - Single order lookup
+  - `getUserFees()` - Fee schedule and volume
+  - `getCandleSnapshot()` - OHLCV candle data
+  - `getFundingHistory()` - Historical funding rates per asset
+  - `getRecentTrades()` - Recent trades for an asset
+  - `getUserRateLimit()` - API rate limit status
+- **Plugin Tools**: Added 8 new OpenClaw plugin tools
+  - `ob_fills`, `ob_orders`, `ob_order_status`, `ob_fees`
+  - `ob_candles`, `ob_funding_history`, `ob_trades`, `ob_rate_limit`
+
 ## [1.0.37] - 2025-02-08
 - **Detailed Docs**: Adding detailed docs for all sub commands
 

package/README.md

@@ -149,6 +149,111 @@ openbroker spot --top 20         # Top 20 by volume
 | `--top` | Limit to top N by volume | — |
 | `--verbose` | Show token metadata | — |
 
+#### `fills` — Trade Fill History
+
+View your trade executions with prices, fees, and realized PnL.
+
+```bash
+openbroker fills                          # Recent fills
+openbroker fills --coin ETH               # ETH fills only
+openbroker fills --coin BTC --side buy --top 50
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Filter by coin symbol | — |
+| `--side` | Filter by side: `buy` or `sell` | — |
+| `--top` | Number of recent fills to show | `20` |
+
+#### `orders` — Order History
+
+View all historical orders including filled, canceled, and rejected.
+
+```bash
+openbroker orders                         # Recent orders
+openbroker orders --coin ETH --status filled
+openbroker orders --top 50
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Filter by coin symbol | — |
+| `--status` | Filter by status (filled, canceled, open, triggered, etc.) | — |
+| `--top` | Number of recent orders to show | `20` |
+
+#### `order-status` — Check Order Status
+
+Look up the status of a specific order by ID.
+
+```bash
+openbroker order-status --oid 123456789   # By order ID
+openbroker order-status --oid 0x1234...   # By client order ID
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--oid` | Order ID (number) or client order ID (hex string) | **required** |
+
+#### `fees` — Fee Schedule
+
+View your fee tier, maker/taker rates, discounts, and recent daily trading volumes.
+
+```bash
+openbroker fees
+```
+
+#### `candles` — OHLCV Candle Data
+
+View candlestick chart data for an asset.
+
+```bash
+openbroker candles --coin ETH                           # 24 hourly candles
+openbroker candles --coin BTC --interval 4h --bars 48   # 48 four-hour bars
+openbroker candles --coin SOL --interval 1d --bars 30   # 30 daily bars
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Asset symbol | **required** |
+| `--interval` | Candle interval: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M | `1h` |
+| `--bars` | Number of bars to fetch | `24` |
+
+#### `funding-history` — Historical Funding Rates
+
+View historical funding rate data for an asset.
+
+```bash
+openbroker funding-history --coin ETH              # Last 24h
+openbroker funding-history --coin BTC --hours 168  # Last 7 days
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Asset symbol | **required** |
+| `--hours` | Hours of history to fetch | `24` |
+
+#### `trades` — Recent Trades (Tape)
+
+View recent trades for an asset with buy/sell volume breakdown.
+
+```bash
+openbroker trades --coin ETH              # Last 30 trades
+openbroker trades --coin BTC --top 50     # Last 50 trades
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--coin` | Asset symbol | **required** |
+| `--top` | Number of recent trades | `30` |
+
+#### `rate-limit` — API Rate Limit
+
+Check your API rate limit usage and capacity.
+
+```bash
+openbroker rate-limit
+```
+
 ---
 
 ### Trading Commands
@@ -559,6 +664,113 @@ openbroker approve-builder --max-fee "0.05%"  # Custom max fee
 | `--builder` | Custom builder address (advanced) | Open Broker |
 | `--verbose` | Show debug output | — |
 
+## OpenClaw Plugin
+
+OpenBroker ships as an [OpenClaw](https://openclaw.ai) plugin. When installed via OpenClaw, it registers structured agent tools and a background position watcher — no Bash wrappers needed.
+
+### Install via OpenClaw
+
+```bash
+openclaw plugins install openbroker
+```
+
+Or install from a local checkout during development:
+
+```bash
+openclaw plugins install -l ./open-broker-mvp
+```
+
+After installation, run `openbroker setup` to configure your wallet (same onboarding as the standalone CLI).
+
+### Plugin Tools
+
+When loaded, the plugin registers these agent tools:
+
+| Category | Tool | Description |
+|----------|------|-------------|
+| Info | `ob_account` | Account balance, equity, margin, open orders |
+| Info | `ob_positions` | Open positions with PnL, leverage, liquidation price |
+| Info | `ob_fills` | Trade fill history with fees and realized PnL |
+| Info | `ob_orders` | Order history (filled, canceled, open, etc.) |
+| Info | `ob_order_status` | Check status of a specific order by ID |
+| Info | `ob_fees` | Fee schedule, tier, maker/taker rates, volume |
+| Info | `ob_funding` | Funding rates sorted by annualized rate |
+| Info | `ob_funding_history` | Historical funding rates for an asset |
+| Info | `ob_candles` | OHLCV candle data for an asset |
+| Info | `ob_trades` | Recent trades (tape) for an asset |
+| Info | `ob_markets` | Market data (price, volume, OI) |
+| Info | `ob_search` | Search assets across perps, HIP-3, and spot |
+| Info | `ob_spot` | Spot markets and token balances |
+| Info | `ob_rate_limit` | API rate limit usage and capacity |
+| Trading | `ob_buy` | Market buy |
+| Trading | `ob_sell` | Market sell |
+| Trading | `ob_limit` | Limit order (GTC, IOC, ALO) |
+| Trading | `ob_trigger` | Trigger order (TP/SL) |
+| Trading | `ob_tpsl` | Set TP/SL on existing position |
+| Trading | `ob_cancel` | Cancel orders |
+| Advanced | `ob_twap` | TWAP execution |
+| Advanced | `ob_bracket` | Entry + TP + SL |
+| Advanced | `ob_chase` | Chase price with ALO orders |
+| Monitoring | `ob_watcher_status` | Background watcher state |
+
+### Background Position Watcher
+
+The plugin runs a background service that polls your Hyperliquid account every 30 seconds and sends webhook notifications when:
+
+- **Position opened** — new position detected
+- **Position closed** — position removed
+- **Size changed** — position increased or decreased
+- **PnL threshold** — unrealized PnL changed by more than the configured % (default: 5%)
+- **Margin warning** — margin usage exceeds threshold (default: 80%)
+
+### Plugin Configuration
+
+Configure in your OpenClaw settings under `plugins.entries.openbroker.config`:
+
+```json
+{
+  "privateKey": "0x...",
+  "accountAddress": "0x...",
+  "network": "mainnet",
+  "hooksToken": "your-hooks-secret",
+  "watcher": {
+    "enabled": true,
+    "pollIntervalMs": 30000,
+    "pnlChangeThresholdPct": 5,
+    "marginUsageWarningPct": 80,
+    "notifyOnPositionChange": true,
+    "notifyOnFunding": true
+  }
+}
+```
+
+All fields are optional — the plugin falls back to `~/.openbroker/.env` and environment variables.
+
+### OpenClaw Webhook Setup
+
+For the position watcher to notify your agent, you need webhooks enabled in your OpenClaw gateway config:
+
+```yaml
+hooks:
+  enabled: true
+  token: "your-hooks-secret"   # Must match hooksToken in plugin config
+```
+
+The watcher sends alerts to `POST /hooks/agent` with `wakeMode: "now"`, which triggers an immediate agent turn. The agent receives a message like:
+
+```
+Position alert: ETH unrealized PnL changed from +$500 to -$200 (-140%).
+```
+
+### CLI Commands
+
+The plugin also registers CLI commands accessible via the OpenClaw CLI:
+
+```bash
+openclaw ob status    # Show watcher state and current positions
+openclaw ob watch     # Run watcher in foreground (debugging)
+```
+
 ## Development
 
 For local development without global install:

package/SKILL.md

@@ -4,8 +4,8 @@ description: Hyperliquid trading plugin with background position monitoring. Exe
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.42", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
-allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.44", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -111,6 +111,55 @@ openbroker spot --balances        # Show your spot balances
 openbroker spot --top 20          # Top 20 by volume
 ```
 
+### Trade Fills
+```bash
+openbroker fills                          # Recent fills
+openbroker fills --coin ETH               # ETH fills only
+openbroker fills --coin BTC --side buy --top 50
+```
+
+### Order History
+```bash
+openbroker orders                         # Recent orders (all statuses)
+openbroker orders --coin ETH --status filled
+openbroker orders --top 50
+```
+
+### Order Status
+```bash
+openbroker order-status --oid 123456789   # Check specific order
+openbroker order-status --oid 0x1234...   # By client order ID
+```
+
+### Fee Schedule
+```bash
+openbroker fees                           # Fee tier, rates, and volume
+```
+
+### Candle Data (OHLCV)
+```bash
+openbroker candles --coin ETH                           # 24 hourly candles
+openbroker candles --coin BTC --interval 4h --bars 48   # 48 four-hour bars
+openbroker candles --coin SOL --interval 1d --bars 30   # 30 daily bars
+```
+
+### Funding History
+```bash
+openbroker funding-history --coin ETH              # Last 24h
+openbroker funding-history --coin BTC --hours 168  # Last 7 days
+```
+
+### Recent Trades (Tape)
+```bash
+openbroker trades --coin ETH              # Last 30 trades
+openbroker trades --coin BTC --top 50     # Last 50 trades
+```
+
+### Rate Limit
+```bash
+openbroker rate-limit                     # API usage and capacity
+```
+
 ## Trading Commands
 
 ### Market Orders (Quick)
@@ -321,6 +370,53 @@ Run `openbroker setup` to create the global config interactively.
 
 The builder fee (1 bps / 0.01%) is hardcoded and not configurable.
 
+## OpenClaw Plugin (Optional)
+
+This skill works standalone via Bash — every command above runs through the `openbroker` CLI. For enhanced features, the same `openbroker` npm package also ships as an **OpenClaw plugin** that you can enable alongside this skill.
+
+### What the plugin adds
+
+- **Structured agent tools** (`ob_account`, `ob_buy`, `ob_limit`, etc.) — typed tool calls with proper input schemas instead of Bash strings. The agent gets structured JSON responses.
+- **Background position watcher** — polls your Hyperliquid account every 30s and sends webhook alerts when positions open/close, PnL moves significantly, or margin usage gets dangerous.
+- **CLI commands** — `openclaw ob status` and `openclaw ob watch` for inspecting the watcher.
+
+### Enable the plugin
+
+The plugin is bundled in the same `openbroker` npm package. To enable it in your OpenClaw config:
+
+```yaml
+plugins:
+  entries:
+    openbroker:
+      enabled: true
+      config:
+        hooksToken: "your-hooks-secret"   # Required for watcher alerts
+        watcher:
+          enabled: true
+          pollIntervalMs: 30000
+          pnlChangeThresholdPct: 5
+          marginUsageWarningPct: 80
+```
+
+The plugin reads wallet credentials from `~/.openbroker/.env` (set up by `openbroker setup`), so you don't need to duplicate `privateKey` in the plugin config unless you want to override.
+
+### Webhook setup for watcher alerts
+
+For position alerts to reach the agent, enable hooks in your gateway config:
+
+```yaml
+hooks:
+  enabled: true
+  token: "your-hooks-secret"   # Must match hooksToken above
+```
+
+Without hooks, the watcher still runs and tracks state (accessible via `ob_watcher_status`), but it can't wake the agent.
+
+### Using with or without the plugin
+
+- **Skill only (no plugin):** Use Bash commands (`openbroker buy --coin ETH --size 0.1`). No background monitoring.
+- **Skill + plugin:** The agent prefers the `ob_*` tools when available (structured data), falls back to Bash for commands not covered by tools (strategies, scale). Background watcher sends alerts automatically.
+
 ## Risk Warning
 
 - Always use `--dry` first to preview orders

package/bin/cli.ts

@@ -23,6 +23,14 @@ const commands: Record<string, { script: string; description: string }> = {
   'all-markets': { script: 'info/all-markets.ts', description: 'View all markets (perps, HIP-3, spot)' },
   'search': { script: 'info/search-markets.ts', description: 'Search for assets across providers' },
   'spot': { script: 'info/spot.ts', description: 'View spot markets and balances' },
+  'fills': { script: 'info/fills.ts', description: 'View trade fill history' },
+  'orders': { script: 'info/orders.ts', description: 'View order history' },
+  'order-status': { script: 'info/order-status.ts', description: 'Check status of a specific order' },
+  'fees': { script: 'info/fees.ts', description: 'View fee schedule and volume' },
+  'candles': { script: 'info/candles.ts', description: 'View OHLCV candle data' },
+  'funding-history': { script: 'info/funding-history.ts', description: 'View historical funding rates' },
+  'trades': { script: 'info/trades.ts', description: 'View recent trades for an asset' },
+  'rate-limit': { script: 'info/rate-limit.ts', description: 'View API rate limit status' },
 
   // Operations
   'buy': { script: 'operations/market-order.ts', description: 'Market buy order' },
@@ -57,11 +65,19 @@ Setup:
 Info Commands:
   account              View account balance, equity, and margin
   positions            View open positions with PnL
+  fills                View trade fill history
+  orders               View order history (all statuses)
+  order-status         Check status of a specific order
+  fees                 View fee schedule, tiers, and volume
   funding              View funding rates (sorted by annualized rate)
+  funding-history      View historical funding rates for an asset
+  candles              View OHLCV candle data
+  trades               View recent trades (tape) for an asset
   markets              View market data for main perps
   all-markets          View all markets (perps, HIP-3, spot)
   search               Search for assets across all providers
   spot                 View spot markets and balances
+  rate-limit           View API rate limit status
 
 Trading Commands:
   buy                  Market buy order

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openbroker",
   "name": "OpenBroker — Hyperliquid Trading",
-  "version": "1.0.0",
+  "version": "1.0.44",
   "description": "Trade on Hyperliquid DEX with background position monitoring",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {