# stephen-kimoi/ai-trading-agent-template architecture

> Architecture diagram of the GitHub repository stephen-kimoi/ai-trading-agent-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephen-kimoi/ai-trading-agent-template
- Repository: https://github.com/stephen-kimoi/ai-trading-agent-template

## Overview

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: [`src/agent/index.ts`](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/index.ts) (Agent loop), [`contracts`](https://github.com/stephen-kimoi/ai-trading-agent-template/tree/main/contracts) (Contracts), [`src/explainability/checkpoint.ts`](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/explainability/checkpoint.ts) (Checkpoint), [`src/agent/identity.ts`](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/identity.ts) (Identity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_agent_runtime["Agent loop<br/>orchestrator<br/>[index.ts]"]
  node_strategy["Strategy<br/>plugin<br/>[strategy.ts]"]
  node_identity["Identity<br/>workflow<br/>[identity.ts]"]
end

subgraph group_onchain["On-chain"]
  node_vault["Vault<br/>capital adapter<br/>[vault.ts]"]
  node_risk_router["Risk router<br/>validation adapter<br/>[riskRouter.ts]"]
  node_reputation_registry["Reputation<br/>registry adapter"]
  node_validation_registry["Validation<br/>registry adapter"]
  node_contracts[("Contracts<br/>solidity suite")]
end

subgraph group_exchange["Exchange"]
  node_kraken["Kraken<br/>exchange adapter<br/>[kraken.ts]"]
end

subgraph group_explainability["Explainability"]
  node_reasoner["Reasoner<br/>explanation formatter<br/>[reasoner.ts]"]
  node_checkpoint["Checkpoint<br/>signed audit<br/>[checkpoint.ts]"]
end

subgraph group_ops["Ops"]
  node_deploy["Deploy<br/>ops script<br/>[deploy.ts]"]
  node_register["Register<br/>ops script<br/>[register-agent.ts]"]
  node_run["Run agent<br/>ops script<br/>[run-agent.ts]"]
  node_dashboard["Dashboard<br/>ops script<br/>[dashboard.ts]"]
end

subgraph group_shared["Shared"]
  node_types["Types<br/>shared interfaces<br/>[index.ts]"]
end

node_run -->|"starts"| node_agent_runtime
node_agent_runtime -->|"asks"| node_strategy
node_agent_runtime -->|"reads/writes"| node_kraken
node_agent_runtime -->|"validates"| node_risk_router
node_agent_runtime -->|"checks capital"| node_vault
node_agent_runtime -->|"explains"| node_reasoner
node_agent_runtime -->|"signs"| node_checkpoint
node_agent_runtime -->|"uses agent id"| node_identity
node_strategy -->|"emits"| node_types
node_identity -->|"registers on"| node_contracts
node_vault -->|"calls"| node_contracts
node_risk_router -->|"calls"| node_contracts
node_reputation_registry -->|"calls"| node_contracts
node_validation_registry -->|"calls"| node_contracts
node_checkpoint -->|"posts"| node_validation_registry
node_checkpoint -->|"packages"| node_reasoner
node_deploy -->|"deploys"| node_contracts
node_register -->|"provisions"| node_identity
node_dashboard -->|"reads"| node_validation_registry

click node_agent_runtime "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/index.ts"
click node_strategy "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/strategy.ts"
click node_identity "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/identity.ts"
click node_kraken "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/exchange/kraken.ts"
click node_vault "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/vault.ts"
click node_risk_router "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/riskRouter.ts"
click node_reputation_registry "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/reputationRegistry.ts"
click node_validation_registry "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/validationRegistry.ts"
click node_contracts "https://github.com/stephen-kimoi/ai-trading-agent-template/tree/main/contracts"
click node_reasoner "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/explainability/reasoner.ts"
click node_checkpoint "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/explainability/checkpoint.ts"
click node_deploy "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/deploy.ts"
click node_register "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/register-agent.ts"
click node_run "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/run-agent.ts"
click node_dashboard "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/dashboard.ts"
click node_types "https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/types/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_runtime,node_strategy,node_identity toneBlue
class node_vault,node_risk_router,node_reputation_registry,node_validation_registry,node_contracts toneAmber
class node_kraken toneMint
class node_reasoner,node_checkpoint toneRose
class node_deploy,node_register,node_run,node_dashboard toneIndigo
class node_types toneTeal
```

## Components

### Runtime

Agent orchestration and plug-in decision flow

- [Agent loop](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/index.ts): orchestrator · Main TypeScript control loop that wires market data, strategy, risk checks, execution, and audit writes · `src/agent/index.ts`
- [Strategy](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/strategy.ts): plugin · TradingStrategy boundary for signal generation and decision policy · `src/agent/strategy.ts`
- [Identity](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/agent/identity.ts): workflow · 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](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/vault.ts): capital adapter · Wrapper for capital allocation and vault interaction · `src/onchain/vault.ts`
- [Risk router](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/riskRouter.ts): validation adapter · Wrapper that validates proposed trades before execution · `src/onchain/riskRouter.ts`
- [Reputation](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/reputationRegistry.ts): registry adapter · Wrapper for reputation lookup and trust state writes · `src/onchain/reputationRegistry.ts`
- [Validation](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/onchain/validationRegistry.ts): registry adapter · Wrapper for audit and validation record writes on Sepolia · `src/onchain/validationRegistry.ts`
- [Contracts](https://github.com/stephen-kimoi/ai-trading-agent-template/tree/main/contracts): solidity suite · Durable smart-contract layer for identity, vault, risk, reputation, and validation · `contracts`

### Exchange

External market execution boundary

- [Kraken](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/exchange/kraken.ts): exchange adapter · REST adapter for market data and order execution · `src/exchange/kraken.ts`

### Explainability

Decision narration and signed checkpoints

- [Reasoner](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/explainability/reasoner.ts): explanation formatter · Formats human-readable summaries for decisions and outcomes · `src/explainability/reasoner.ts`
- [Checkpoint](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/explainability/checkpoint.ts): signed audit · Builds and verifies EIP-712 signed checkpoints for every decision · `src/explainability/checkpoint.ts`

### Ops

Deployment, registration, and runtime entrypoints

- [Deploy](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/deploy.ts): ops script · Deploys the contract suite and records addresses · `scripts/deploy.ts`
- [Register](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/register-agent.ts): ops script · Registers the agent identity and produces the agent ID · `scripts/register-agent.ts`
- [Run agent](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/run-agent.ts): ops script · Starts the live trading loop · `scripts/run-agent.ts`
- [Dashboard](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/scripts/dashboard.ts): ops script · Runs the local monitoring dashboard · `scripts/dashboard.ts`

### Shared

Common types and interfaces

- [Types](https://github.com/stephen-kimoi/ai-trading-agent-template/blob/main/src/types/index.ts): shared interfaces · Shared TypeScript types such as trade decisions and agent data · `src/types/index.ts`

## Connections

- 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
