# elliottech/lighter-agent-kit architecture

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

- Interactive diagram: https://gitdiagram.com/elliottech/lighter-agent-kit
- Repository: https://github.com/elliottech/lighter-agent-kit

## Overview

Lighter Agent Kit is an agent skill for querying Lighter markets and accounts, submitting live trades, and simulating paper trades. The principal workflow starts with an agent request, routes to a JSON CLI script, resolves symbols and deployment metadata as needed, and reads from or writes to Lighter. Paper trading instead simulates supported orders against live order-book snapshots and persists local state. The README documents broader read, write, transfer, and account-configuration capabilities. Source excerpts are partial, so the graph omits unverified internal call details.

Main entry points: [`scripts/trade.py`](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/trade.py) (Live trading writes), [`scripts/paper.py`](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/paper.py) (Paper trading), [`scripts/query.py`](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/query.py) (Market and account reads), [`scripts/_symbols.py`](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_symbols.py) (Symbol resolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_query["Market and account reads<br/>[query.py]"]
  node_trade["Live trading writes<br/>[trade.py]"]
  node_paper["Paper trading<br/>[paper.py]"]
end

subgraph group_trading["Trading workflows"]
end

subgraph group_shared["Shared runtime"]
  node_symbols["Symbol resolution<br/>[_symbols.py]"]
  node_assets["Asset registry<br/>[_assets.py]"]
  node_sdk["SDK and credentials<br/>[_sdk.py]"]
  node_cli["JSON CLI helpers<br/>[_cli.py]"]
  node_paths["Local path policy<br/>[_paths.py]"]
end

subgraph group_localdata["Local data"]
  node_paperstate[("Paper state file")]
  node_symbolcache[("Symbol cache")]
  node_assetcache[("Asset cache")]
  node_credentials["Credentials file"]
end

node_agent(("AI agent"))
node_lighter{{"Lighter API"}}

node_agent -->|"requests reads"| node_query
node_agent -->|"requests writes"| node_trade
node_agent -->|"requests simulation"| node_paper
node_query -->|"fetches data"| node_lighter
node_trade -->|"submits signed writes"| node_lighter
node_paper -->|"fetches live books"| node_lighter
node_query -->|"resolves markets"| node_symbols
node_trade -->|"resolves markets"| node_symbols
node_paper -->|"resolves markets"| node_symbols
node_trade -->|"resolves assets"| node_assets
node_query -->|"loads SDK"| node_sdk
node_trade -->|"loads SDK"| node_sdk
node_paper -->|"loads SDK"| node_sdk
node_query -->|"uses output helpers"| node_cli
node_trade -->|"uses output helpers"| node_cli
node_paper -->|"uses output helpers"| node_cli
node_sdk -->|"locates credentials"| node_paths
node_symbols -->|"locates cache"| node_paths
node_assets -->|"locates cache"| node_paths
node_sdk -->|"reads credentials"| node_credentials
node_symbols -->|"reads and writes"| node_symbolcache
node_assets -->|"reads and writes"| node_assetcache
node_paper -->|"persists state"| node_paperstate

click node_query "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/query.py"
click node_trade "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/trade.py"
click node_paper "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/paper.py"
click node_symbols "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_symbols.py"
click node_assets "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_assets.py"
click node_sdk "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_sdk.py"
click node_cli "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_cli.py"
click node_paths "https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_paths.py"

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_query,node_trade,node_paper toneBlue
class node_symbols,node_assets,node_sdk,node_cli,node_paths,node_lighter toneMint
class node_paperstate,node_symbolcache,node_assetcache,node_credentials toneRose
class node_agent toneIndigo
```

## Components

### Agent interfaces

- [Market and account reads](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/query.py): `scripts/query.py`
- [Live trading writes](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/trade.py): `scripts/trade.py`
- [Paper trading](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/paper.py): `scripts/paper.py`

### Shared runtime

- [Symbol resolution](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_symbols.py): `scripts/_symbols.py`
- [Asset registry](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_assets.py): `scripts/_assets.py`
- [SDK and credentials](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_sdk.py): `scripts/_sdk.py`
- [JSON CLI helpers](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_cli.py): `scripts/_cli.py`
- [Local path policy](https://github.com/elliottech/lighter-agent-kit/blob/main/scripts/_paths.py): `scripts/_paths.py`

### Local data

- **Paper state file**
- **Symbol cache**
- **Asset cache**
- **Credentials file**

### Other components

- **AI agent**
- **Lighter API**

## Connections

- AI agent → Market and account reads: requests reads (evidence: `README.md`)
- AI agent → Live trading writes: requests writes (evidence: `README.md`)
- AI agent → Paper trading: requests simulation (evidence: `README.md`)
- Market and account reads → Lighter API: fetches data (evidence: `README.md`)
- Live trading writes → Lighter API: submits signed writes (evidence: `README.md`)
- Paper trading → Lighter API: fetches live books (evidence: `README.md`)
- Market and account reads → Symbol resolution: resolves markets (evidence: `scripts/query.py`)
- Live trading writes → Symbol resolution: resolves markets (evidence: `scripts/trade.py`)
- Paper trading → Symbol resolution: resolves markets (evidence: `scripts/paper.py`)
- Live trading writes → Asset registry: resolves assets (evidence: `scripts/trade.py`)
- Market and account reads → SDK and credentials: loads SDK (evidence: `scripts/query.py`)
- Live trading writes → SDK and credentials: loads SDK (evidence: `scripts/trade.py`)
- Paper trading → SDK and credentials: loads SDK (evidence: `scripts/paper.py`)
- Market and account reads → JSON CLI helpers: uses output helpers (evidence: `scripts/query.py`)
- Live trading writes → JSON CLI helpers: uses output helpers (evidence: `scripts/trade.py`)
- Paper trading → JSON CLI helpers: uses output helpers (evidence: `scripts/paper.py`)
- SDK and credentials → Local path policy: locates credentials (evidence: `scripts/_sdk.py`)
- Symbol resolution → Local path policy: locates cache (evidence: `scripts/_symbols.py`)
- Asset registry → Local path policy: locates cache (evidence: `scripts/_assets.py`)
- SDK and credentials → Credentials file: reads credentials (evidence: `scripts/_sdk.py`)
- Symbol resolution → Symbol cache: reads and writes (evidence: `scripts/_symbols.py`)
- Asset registry → Asset cache: reads and writes (evidence: `scripts/_assets.py`)
- Paper trading → Paper state file: persists state (evidence: `README.md`)
