How stephen-kimoi/ai-trading-agent-template works
1. This repository is a reusable AI trading-agent template built around four boundaries: on-chain identity, capital/risk control, exchange execution, and explainability/audit logging. The central runtime is a TypeScript agent loop that pulls market data, asks a strategy what to do, validates the action on-chain, sends the order to Kraken, and then records a signed checkpoint.
2. The main control flow lives in src/agent/index.ts. It is the orchestrator that wires together the strategy, the exchange client, the on-chain wrappers, and the explanation layer. That file is the best place to draw the “runtime core” box in an architecture diagram.
3. Strategy is intentionally isolated behind TradingStrategy in src/agent/strategy.ts. The repository ships with example logic such as a momentum-style strategy, but the architecture treats the strategy as a plug-in. This means model choice and signal generation are decoupled from identity, risk, and execution.
4. Market execution is handled by src/exchange/kraken.ts, which talks to the Kraken REST API. The README makes clear that both paper trading and live trading are supported, so the exchange layer is the external trading venue boundary. The agent does not trade directly from strategy output; it routes decisions through this adapter.
5. On-chain control is split into three contract-facing modules in src/onchain/: vault.ts, riskRouter.ts, and reputationRegistry.ts / validationRegistry.ts support code. These wrappers encapsulate Sepolia interactions with the deployed contracts, so the agent’s business logic remains separate from blockchain plumbing.
6. The deployed smart contracts in contracts/ are the durable trust layer:
- AgentRegistry.sol provides ERC-8004 agent identity.
- HackathonVault.sol manages capital allocation per agent.
- RiskRouter.sol performs trade validation before execution.
- The registry components for reputation/validation provide a place to record and query trust/audit state.
These contracts define the permission and validation boundary before any exchange order is placed.
7. Identity registration is its own workflow. src/agent/identity.ts and scripts/register-agent.ts handle creating or registering the agent on-chain, producing an AGENT_ID that the runtime uses later. In diagram terms, identity exists before trading begins and is a prerequisite for checkpoint signing and registry writes.
8. Explainability is a first-class subsystem under src/explainability/. reasoner.ts formats human-readable decision summaries, while checkpoint.ts generates and verifies EIP-712 signed checkpoints. Every decision, including HOLD decisions, becomes an auditable artifact rather than only executed trades.
9. The audit trail is dual-write: checkpoints are posted to the ValidationRegistry on Sepolia and also appended locally to checkpoints.jsonl. That means the system has both an on-chain verification path and a local append-only log path. The on-chain record anchors integrity; the JSONL file supports inspection and dashboard display.
10. Operational tooling is split into scripts:
- scripts/deploy.ts deploys the contract suite to Sepolia and outputs addresses.
- scripts/register-agent.ts registers the agent identity.
- scripts/run-agent.ts starts the live trading loop.
- scripts/dashboard.ts runs a local dashboard on localhost:3000.
This separation shows the repo is designed for repeatable setup, not a monolithic always-on service.
11. Configuration and secrets are environment-driven. The runtime depends on Sepolia RPC access, a private key, Kraken API credentials, deployed contract addresses, and the agent ID. The presence of .env.example and deployed.json indicates a clear split between code, deployment metadata, and runtime credentials.
12. In end-to-end terms, the data flow is: market price data from Kraken enters the agent; the strategy emits a TradeDecision; the risk router/vault layer validates whether the decision is allowed; if approved, the order is sent to Kraken; then the reasoner and checkpoint layer produce a signed explanation record that is persisted locally and posted on-chain. That is the core architecture a diagram should emphasize.
Main entry points: index.ts Agent loop · contracts Contracts · checkpoint.ts Checkpoint · identity.ts Identity
Components 16
Runtime
Agent orchestration and plug-in decision flow
- Agent loop · Main TypeScript control loop that wires market data, strategy, risk checks, execution, and audit writes
src/agent/index.ts - Strategy · TradingStrategy boundary for signal generation and decision policy
src/agent/strategy.ts - Identity · Creates or loads the on-chain agent identity used by the runtime
src/agent/identity.ts
On-chain
Identity, vault, risk, and registry contracts
- Vault · Wrapper for capital allocation and vault interaction
src/onchain/vault.ts - Risk router · Wrapper that validates proposed trades before execution
src/onchain/riskRouter.ts - Reputation · Wrapper for reputation lookup and trust state writes
src/onchain/reputationRegistry.ts - Validation · Wrapper for audit and validation record writes on Sepolia
src/onchain/validationRegistry.ts - Contracts · Durable smart-contract layer for identity, vault, risk, reputation, and validation
contracts
Exchange
External market execution boundary
- Kraken · REST adapter for market data and order execution
src/exchange/kraken.ts
Explainability
Decision narration and signed checkpoints
- Reasoner · Formats human-readable summaries for decisions and outcomes
src/explainability/reasoner.ts - Checkpoint · Builds and verifies EIP-712 signed checkpoints for every decision
src/explainability/checkpoint.ts
Ops
Deployment, registration, and runtime entrypoints
Shared
Common types and interfaces
- Types · Shared TypeScript types such as trade decisions and agent data
src/types/index.ts
Connections 19
- Run agent → Agent loop: starts · Launches the runtime loop
- Agent loop → Strategy: asks · Requests a trade decision from the plug-in strategy
- Agent loop → Kraken: reads/writes · Pulls market data and submits orders
- Agent loop → Risk router: validates · Checks whether the proposed trade is allowed
- Agent loop → Vault: checks capital · Enforces allocation and capital controls
- Agent loop → Reasoner: explains · Converts decisions into human-readable rationale
- Agent loop → Checkpoint: signs · Creates a signed checkpoint for each decision
- Agent loop → Identity: uses agent id · Depends on the registered on-chain identity
- Strategy → Types: emits · Produces typed trade decisions
- Identity → Contracts: registers on · Creates or resolves the on-chain agent identity
- Vault → Contracts: calls · Talks to the deployed vault contract
- Risk router → Contracts: calls · Talks to the deployed risk router contract
- Reputation → Contracts: calls · Reads and writes reputation state
- Validation → Contracts: calls · Anchors validation and checkpoint records
- Checkpoint → Validation: posts · Publishes signed checkpoints on-chain
- Checkpoint → Reasoner: packages · Combines rationale with the signed audit artifact
- Deploy → Contracts: deploys · Publishes the contract suite
- Register → Identity: provisions · Creates the agent identity workflow before trading
- Dashboard → Validation: reads · Uses local and on-chain audit state for display