tradeledger

tradeledger

A read-only window onto a live trading experiment. tradeledger lets an agent quote the experiment's actual state — its current balance and open position, the trades it has actually closed, the contributor shadow rules it runs, and the story it tells about itself — instead of inventing plausible numbers.

Nothing here trades. The five tools only read public data; there is no order, wallet, or account-write operation in the surface, and no credential is needed or accepted.

Tools

Tool	Arguments	What it answers
get_live_status	—	Balance, total PnL, win rate, trade count, market regime, and the open position if one is running.
get_recent_trades	limit (optional integer)	The most recent closed trades, each with direction, exit reason, PnL, and regime.
list_adopted_rules	status (optional: adopted, queued, or all)	The contributor-proposed shadow rules, filtered by where they stand.
get_rule_status	rule_id (required string)	One rule's per-bucket hit rates and how far it sits from its promotion bar.
get_latest_saga_chapter	lang (optional: en or zh)	The newest entry in the experiment's narrated saga.

How it works

tradeledger is a forwarding client. A tool call is packaged as a JSON-RPC tools/call request and sent to a single upstream MCP endpoint; whatever the upstream returns is handed back untouched. When the upstream fails, the answer is an error text beginning tradeledger error: — never a locally invented figure.

Provenance

The endpoint and the forwarding shape are labelled reconstructions. The original server's public description names its data sources in prose but publishes no per-tool endpoint, so this rebuild points every call at one configurable upstream:

• IBITLABS_MCP_URL — upstream MCP endpoint. Default: https://www.ibitlabs.com/api/mcp (labelled reconstruction).
• REQUEST_TIMEOUT_MS — per-request timeout. Default: 15000.

Run it as an MCP server

{
  "mcpServers": {
    "tradeledger": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tradeledger", "mcp"]
    }
  }
}

Or in a container:

docker run -i ghcr.io/cloudcorprecords/tradeledger

Run it as a CLI

npx @reneturcios/tradeledger get_live_status '{}'
npx @reneturcios/tradeledger get_recent_trades '{"limit": 2}'
npx @reneturcios/tradeledger get_rule_status '{"rule_id": "F"}'
npx @reneturcios/tradeledger --version

Each tool subcommand takes exactly one JSON object string with the tool's arguments and prints the result text. Exit codes are 0 on success, 1 on an error result, and 2 on a usage error.

Development

npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — offline; the upstream is stubbed
npm run dev     # tsx src/cli.ts — run the CLI from source

The test suite never touches the network: it drives the core with a stubbed JSON-RPC upstream whose payloads are the public worked-example responses, and checks they pass through untouched, that failures become tradeledger error: results, and that the served tool list matches the contracted five tools exactly.

License

MIT. See LICENSE.