Monitoring

openbroker-monitoring is an optional addon that wires the openbroker audit pipeline into a dashboard or external sink. When installed alongside openbroker, it auto-loads at automation startup — no flags, no wiring.

It exists as a separate package because the env-read + outbound fetch pattern would otherwise trip the OpenClaw scanner's "credential harvesting" rule when shipped inside the plugin tarball.

Install

Terminal

npm install openbroker openbroker-monitoring

If openbroker-monitoring resolves through Node's normal module lookup at runtime, the openbroker automation runtime auto-loads it. No code changes needed.

Configuration

Env var	Purpose
OB_DASHBOARD_URL	Dashboard base URL, e.g. `http://localhost:3001`. Required.
OB_DASHBOARD_API_KEY	Bearer token sent as `Authorization: Bearer <key>`. Optional.
HYPERSTABLE_VAULT_ADDRESS (or VAULT)	Vault address used in the URL path. Required.

If OB_DASHBOARD_URL or the vault address is missing, the observer returns null and the runtime no-ops cleanly — safe to leave installed in environments where you don't want forwarding.

What gets forwarded

The observer fans out three kinds of audit events to the dashboard. Each request is fire-and-forget with a 5-second timeout; failures are swallowed so the trading loop is never blocked.

Event	Endpoint	Payload
api.audit.record(kind, payload)	POST {url}/api/vaults/{vault}/audit/notes	{ category, label, data }
api.audit.metric(name, value, tags)	POST {url}/api/vaults/{vault}/audit/metrics	{ name, value, tags }
Audited write methods (`marketOrder`, `cancel`, etc.)	POST {url}/api/vaults/{vault}/agent/logs	{ action, status, details, txHash? }

The third one is automatic — every write call on the openbroker client (place order, cancel, update leverage, etc.) is forwarded with its arguments and result.

Programmatic use

If you'd rather wire it manually instead of via convention auto-load:

my-runner.ts

import { createDashboardObserver } from 'openbroker-monitoring';
import { startAutomation } from 'openbroker';
 
const observer = createDashboardObserver({
  url: 'http://localhost:3001',
  apiKey: process.env.MY_KEY,
  vaultAddress: '0x…',
});
 
await startAutomation({
  scriptPath: './my-strategy.ts',
  auditObservers: observer ? [observer] : [],
});

The observer implements the AutomationAuditObserver interface, so any package exporting an object with the same shape can plug into the same hooks.

interface AutomationAuditObserver {
  onNote?(kind: string, payload?: unknown): void;
  onMetric?(name: string, value: number, tags?: Record<string, unknown>): void;
  onAgentAction?(
    action: string,
    status: 'success' | 'error',
    details: Record<string, unknown>,
    txHash?: string,
  ): void;
}

Why it lives in its own package

The OpenClaw scanner inspects every plugin tarball at install time and blocks files that combine process.env reads with outbound fetch calls. That pattern is the whole point of a dashboard forwarder — read API key + URL from env, POST data — so we keep that code out of openbroker-plugin and let users opt in by installing this package separately. The runtime convention-load means there's no friction to enabling it, and the network code only ever lives in a package the scanner doesn't see.

OpenClaw Plugin Reference