# 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

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

Or in a container:

```bash
docker run -i ghcr.io/cloudcorprecords/tradeledger
```

## Run it as a CLI

```bash
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

```bash
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](LICENSE).