Caliquity - Trading Agent

This repository was built during a hackathon, under a very compressed time window: roughly one and a half working days, from morning to evening on the first day and from morning to early afternoon on the second day. For this reason, the project is intentionally different from a long-term production repository: it is designed to show fast execution, practical system design, tool integration, and the ability to deliver a working autonomous-agent demo under real hackathon constraints.

An autonomous trading-agent prototype built for a hackathon demo. The system reads live market data, keeps a lightweight memory, uses an LLM only when useful, applies risk checks, executes paper trades, and records every cycle in a structured journal.

Project Overview

The project is organized around a simple agent loop:

• Market stream: reads live prices from Alpaca WebSocket and updates the current market memory.
• Memory layer: stores the latest market snapshot and the completed decision cycles.
• Human context: lets the human operator provide mood, goals, or strategy preferences during the run.
• Decision node: calls the LLM only when a trigger says a new decision is needed.
• Risk guard: checks exposure, confidence, position limits, and safety rules before execution.
• Broker tools: execute simulated orders through Alpaca Paper Trading.
• Journal: records decisions, reasons, risk results, and execution outcomes.
• Dashboard: shows prices, portfolio state, decisions, reasons, and journal activity in real time.

The main goal is a stable Level 3 Autonomous Agent demo: live data retrieval, written rationales, simulated order execution, portfolio updates, tool-failure handling,structured journaling, web search and best reasoning.

Run Instructions

1. Install dependencies

uv sync

2. Create the environment file

cp .env.example .env

Then edit .env and add your API keys.

3. Test the connection

uv run python scripts/test_connection.py

4. Start the dashboard

Open a first terminal and run:

uv run python scripts/dashboard.py

Then open the dashboard in the browser:

http://127.0.0.1:8765

5. Start the autonomous agent

Open a second terminal and run:

uv run trading-agent

The dashboard and the agent must run in two separate terminals.

6. Show the journal

To read the latest journal entries from the terminal:

uv run python scripts/show_journal.py

7. Stop the system

To stop the dashboard or the agent, press:

CTRL + C

Notes

• Keep .env private and never commit real API keys.
• The dashboard and agent are separate processes.
• The agent should never invent prices, news, positions, or tool results.
• If live market data is missing or stale, the safe behavior is to hold.

Documentation

The complete documentation, including the full hackathon brief and the supporting material used during development, is available in the docs folder.

by CaliBrAIted Team