paper-broker

Imported from shubhamtaywade82/paper-broker (AGENTS.md). Install upstream with npx skills add shubhamtaywade82/paper-broker. Copyright stays with the author.

AGENTS.md

1. Mission

You are an engineering agent working on a production-oriented, local-first, event-driven crypto trading system.

You MUST behave as an evidence-first software engineer.

Your primary responsibilities are:

1. Preserve architectural boundaries.
2. Never invent functionality, APIs, files, configuration, or behavior.
3. Inspect the existing implementation before modifying it.
4. Implement requested work completely.
5. Verify every change.
6. Never claim success without evidence.
7. Protect paper/live execution boundaries.
8. Keep the system deterministic where determinism is required.
9. Treat LLM reasoning as advisory/orchestrating, never as an authority over risk.
10. Produce small, coherent, working commits.

2. System Context

The system consists of:

• Binance SDK (@nemesis-oss/binance-sdk): Binance REST/WS market data and exchange/tool integration.
• Ollama SDK (@nemesis-oss/ollama-sdk): local LLM runtime, agent loop, tools, MCP, skills and telemetry.
• Paper Broker: deterministic paper execution with SQLite event persistence.
• Market Data: normalized market state from Binance WebSocket streams.
• Strategy Engine: signal generation with cooldowns, validation, and conflict rules.
• Signal Executor: sizing, risk validation, order submission to broker.
• Scheduler: periodic jobs for snapshots, funding, expiry, stale market detection.
• Persistence: SQLite with append-only event log and queryable state tables.
• REST API: Fastify server for monitoring and controlled operational access.
• CLI: operational commands for trade, monitor, backtest.

Existing SDKs are authoritative for their respective exchange/model capabilities. Do not duplicate their implementation unless explicitly required.

3. Architectural Authority

Architecture precedence:

1. Current source code
2. Tests
3. Explicit task requirements
4. ADRs / architecture documentation
5. Repository README
6. Agent skills and rules
7. Your assumptions

If documentation conflicts with implementation:

• inspect the implementation;
• identify the discrepancy;
• do not silently guess;
• update documentation only after verifying the intended behavior.

Never treat README claims as proof that a feature exists.

4. Evidence-First Rule

Before changing code:

1. Locate the relevant implementation.
2. Read the surrounding code.
3. Find its tests.
4. Find interfaces/contracts used by it.
5. Identify callers and dependents.
6. Determine current behavior.
7. Only then design the change.

You MUST NOT implement from filenames alone.

You MUST NOT assume a method exists because its name sounds plausible.

You MUST NOT fabricate API responses, exchange behavior, tool names, configuration variables, or library capabilities.

If the required information is unavailable:

• search the repository;
• inspect dependency types;
• inspect official SDK code;
• state exactly what remains unknown.

5. Never Hallucinate

The following are prohibited:

• inventing files that were not inspected;
• inventing interfaces;
• inventing API endpoints;
• inventing Binance/CoinDCX behavior;
• assuming an exchange accepts an order type without verifying;
• assuming an SDK exposes a method without verifying it;
• creating fake test fixtures and treating them as production semantics;
• claiming that an integration works without executing it;
• claiming a test passes without running it;
• claiming deployment works without verifying the actual runtime.

Use explicit uncertainty:

"Not verified from the current repository."

rather than:

"This should work."

6. Trading Safety Rules

These rules are NON-NEGOTIABLE.

6.1 LLM

The LLM MUST NOT:

• directly submit live orders;
• bypass the risk engine;
• bypass kill switches;
• modify risk limits;
• fabricate market data;
• calculate authoritative execution state;
• assume missing values;
• override reconciliation failures.

The LLM may:

• select skills;
• request evidence;
• analyze structured facts;
• rank setups;
• identify contradictions;
• produce TradeIntent/signal;
• recommend WAIT / NO_TRADE / HOLD;
• assist position-management decisions.

This rule is why TradingAgentsPipeline's risk-team and fund-manager stages are deterministic policy rather than model calls. Converting them to LLM calls would hand the LLM authority over risk approval, violating 6.1 and CONTRACTS.md §5. Each AgentCycleStep carries engine: 'llm' | 'deterministic' so the two kinds of stage cannot be confused downstream.

Final execution path:

LLM/Strategy -> Signal -> TradeIntentEngine/RiskEngine -> SignalExecutor
             -> ExecutionRouter (+LiveTradingGuard) -> Broker -> EventLog

ExecutionRouter sits on every order submission and selects the paper broker or the live venue adapter from the runtime profile. An armed live profile with no usable adapter rejects the order — it never falls back to simulated fills.

6.2 Risk

No order reaches the broker without:

• signal validation (schema + expiry + conflicts);
• position validation;
• exposure validation;
• execution-mode validation;
• market state validation (no stale data).

6.3 Operating Mode

TRADING_MODE controls operational profile:

• paper: simulated execution, real market data
• shadow: planned (read-only account state)
• live: planned (real execution with explicit arm state)

Mode selection MUST be controlled by one flag.

Do not introduce independent boolean flags such as:

• PAPER_ENABLED
• SHADOW_ENABLED
• LIVE_ENABLED

Secrets and infrastructure configuration belong in environment variables. Mode-dependent behavior belongs in mode profiles.

7. Market Data

Market data must be normalized before entering the trading engine.

Trading logic MUST NOT depend directly on:

• raw WebSocket payload structures;
• exchange-specific event schemas.

Use canonical domain events through MarketStateManager.

Example canonical events:

• MarketTick (bid/ask/last/mark/funding)
• CandleClosed
• MarketStale
• MarketRecovered

Exchange adapters translate external data into canonical events.

8. Event-Driven Architecture

Prefer events over polling when meaningful events exist.

Current event types in this system:

• ORDER_CREATED
• ORDER_FILLED
• ORDER_CANCELLED
• ORDER_REJECTED
• POSITION_OPENED
• POSITION_INCREASED
• POSITION_REDUCED
• POSITION_CLOSED
• POSITION_FLIPPED
• FUNDING_APPLIED
• ACCOUNT_SNAPSHOT
• MARKET_TICK
• SIGNAL_EXECUTED
• SIGNAL_REJECTED
• RISK_EVENT
• SYSTEM_EVENT

Do not add arbitrary polling loops where event-driven behavior is practical.

9. Execution Rules

Paper execution is implemented via PaperBroker.

The broker interface includes:

• submitOrder(signal) - process a signal into orders
• cancelOrder(orderId) - cancel an open order
• cancelAll(symbol?) - cancel all open orders
• getOpenOrders(symbol?) - query open orders
• getPositions() - query all positions
• getAccount() - query account state

Strategy code MUST NOT know which implementation is active.

10. Reconciliation

For live trading (future):

Internal state is NOT authoritative.

The exchange is authoritative for:

• positions
• open orders
• fills
• wallet/balance
• execution state

After startup, reconnect, timeout, uncertain write state, or provider recovery:

1. query exchange;
2. reconcile;
3. persist result;
4. block new orders if reconciliation fails.

Never retry an uncertain live order blindly.

11. Dashboard and API

Dashboard and API are clients of the trading runtime.

They MUST NOT bypass:

• authentication (when implemented);
• authorization;
• risk;
• execution router;
• broker boundaries.

All operational commands must go through the same command pipeline.

12. Error Handling

Every meaningful failure MUST be captured.

Errors must be:

• normalized;
• classified;
• persisted via EventLog;
• exposed to observability (telemetry/logs);
• sent to notifications according to severity (when implemented).

Do not send every low-level debug event to notifications.

Critical trading failures MUST immediately block unsafe trading.

13. Testing Rule

Every behavior change requires tests.

At minimum:

• unit test for changed domain logic;
• regression test for previous behavior;
• integration test for boundary changes.

For critical paths also verify:

• paper execution;
• market data handling;
• signal validation;
• risk rejection;
• event persistence.

14. Definition of Done

A task is NOT complete until:

1. Implementation exists.
2. Tests exist or are demonstrably unnecessary.
3. Type checking passes (pnpm typecheck).
4. Linting passes (pnpm lint).
5. Relevant tests pass (pnpm test).
6. Build passes (pnpm build).
7. Runtime/integration verification passes when applicable.
8. Documentation/contracts are updated.
9. No unrelated changes remain.
10. Git diff has been inspected.
11. Commit message accurately describes the change.

Never stop after writing code.

15. Commit Discipline

Before committing:

• run git status;
• inspect changed files;
• inspect git diff;
• run required verification;
• confirm no secrets are staged;
• confirm no unrelated files changed.

A commit MUST represent a coherent, verified unit of work.

Do NOT:

• commit half implementations;
• commit knowingly failing tests;
• use --no-verify to bypass validation;
• amend unrelated historical commits;
• mix refactors with feature work unless necessary.

16. Commit Completion Report

After completing a commit, report:

• what changed;
• files changed;
• tests run;
• commands run;
• verification result;
• known limitations;
• commit SHA.

If verification failed, say so explicitly.

17. Change Discipline

Prefer:

small change -> test -> verify -> commit

over:

large speculative refactor -> hope it works

Do not refactor unrelated code simply because it is imperfect.

18. Security

Never commit:

• API keys
• API secrets
• Telegram bot tokens
• chat IDs if treated as secret by project policy
• passwords
• local credential files
• production database files

Review .gitignore before adding infrastructure artifacts.

19. Dependency Discipline

Do not add dependencies casually.

Before adding a package:

1. verify that it is necessary;
2. check whether an existing dependency already solves the problem;
3. inspect package/runtime compatibility;
4. add tests;
5. update lockfile;
6. run full verification.

20. No Silent Architecture Changes

If a requested implementation would materially alter:

• event semantics;
• order lifecycle;
• risk boundaries;
• execution mode;
• persistence model;
• agent autonomy;

stop and document the architectural impact before proceeding.

When in doubt, create an ADR in docs/decisions/.

21. Required Final Verification

Before declaring completion run the repository's canonical verification command:

pnpm verify:complete

If this command does not exist yet, use at least:

• pnpm typecheck
• pnpm lint
• pnpm test
• pnpm build

For integration-sensitive changes also run the relevant smoke/integration tests.

A green compile is NOT proof of correctness.

22. Default Agent Behavior

When a task is ambiguous:

1. inspect repository context;
2. resolve ambiguity from code/tests/docs;
3. ask only if a consequential decision remains unresolved.

Do not fill missing requirements with imagination.

When an implementation is risky:

• prefer safe failure;
• prefer NO_TRADE / HOLD;
• prefer rejecting the operation to guessing.

23. Scope Control

The requested task defines the primary scope.

Do not:

• rename unrelated files;
• rewrite working infrastructure;
• replace libraries without reason;
• redesign architecture;
• "clean up" unrelated code;
• introduce abstractions merely because they look elegant.

If a broader change is truly required:

1. explain why;
2. identify affected components;
3. preserve existing behavior;
4. test the migration.

24. Project State Awareness

Before starting any significant work:

1. Read PROJECT_STATE.md to understand current phase and capabilities.
2. Read CONTRACTS.md to understand invariants that must not change.
3. Read KNOWN_LIMITATIONS.md to avoid claiming incomplete features as done.

Update these files when the project materially changes.

25. Mandatory Implementation Protocol

For every task, follow this protocol:

TASK
 ↓
READ AGENTS.md (this file)
 ↓
READ PROJECT_STATE.md
 ↓
READ CONTRACTS.md
 ↓
LOCATE IMPLEMENTATION (source files)
 ↓
LOCATE TESTS
 ↓
CHECK SDK CAPABILITIES
 ↓
PLAN (write mini-design)
 ↓
IMPLEMENT
 ↓
TEST
 ↓
TYPECHECK
 ↓
LINT
 ↓
BUILD
 ↓
INTEGRATION/SMOKE
 ↓
GIT DIFF REVIEW
 ↓
SECURITY CHECK
 ↓
COMMIT
 ↓
COMMIT VERIFICATION REPORT

The agent should not skip from TASK → CODE.