Agent API

Programmatic access to mylittlechart terminal

Overview

mylittlechart exposes a local REST API on port 17420. It lets AI agents, scripts, and automation tools read live market data, inspect chart state, control indicators and drawing objects, and capture chart screenshots — all without any network round-trips to an external server.

The API server starts automatically with the terminal. No configuration is required to use it locally. Add an API key in User Settings → API Keys to enable authenticated access.

Authentication

Pass your API key as a Bearer token in the Authorization header, or as a query parameter:

request headers
Authorization: Bearer YOUR_API_KEY
query parameter fallback
GET http://localhost:17420/api/v1/bars?api_key=YOUR_API_KEY&symbol=BTCUSDT

Access Tiers

Tier Capabilities Created by
none Open access — only if the key registry is empty (local dev mode). Health endpoint is always open. —
read_only GET all data endpoints. Cannot modify charts, indicators, or drawings. User Settings UI
read_write All read operations plus POST/PATCH/DELETE for chart control, indicators, and drawings. User Settings UI
admin All operations including API key management (list, create, delete). Terminal UI only

Admin keys can only be created from inside the terminal's User Settings panel. They cannot be created via the API itself — this prevents privilege escalation from a compromised key.

When the key registry is empty, the API runs in open access mode — all endpoints are accessible without authentication. This is the default for fresh installs and local development. Add any key in User Settings to lock it down.

Quick Start

bash / curl
# Health check — no auth required
curl http://localhost:17420/api/v1/health

# Get 100 candles for BTCUSDT 1H on Binance
curl -H "Authorization: Bearer YOUR_KEY" \
  "http://localhost:17420/api/v1/bars?exchange=binance&symbol=BTCUSDT&timeframe=1H&limit=100"

# List all open windows
curl -H "Authorization: Bearer YOUR_KEY" \
  http://localhost:17420/api/v1/windows

# Capture a screenshot of chart 0 in tab 0 of window 0
curl -X POST -H "Authorization: Bearer YOUR_KEY" \
  http://localhost:17420/api/v1/windows/0/tabs/0/charts/0/screenshot

# Switch the symbol on a chart (read_write tier)
curl -X PATCH -H "Authorization: Bearer YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"symbol":"ETHUSDT","exchange":"binance"}' \
  http://localhost:17420/api/v1/windows/0/tabs/0/charts/0/symbol
python
import requests

BASE = "http://localhost:17420/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}

# Fetch recent bars
resp = requests.get(
    f"{BASE}/bars",
    headers=HEADERS,
    params={
        "exchange": "binance",
        "symbol":   "BTCUSDT",
        "timeframe":"1H",
        "limit":    200,
    },
)
bars = resp.json()["bars"]
print(f"Received {len(bars)} candles")

# Take a screenshot and save it
import base64, pathlib
r = requests.post(f"{BASE}/windows/0/tabs/0/charts/0/screenshot", headers=HEADERS)
png = base64.b64decode(r.json()["screenshot"])
pathlib.Path("chart.png").write_bytes(png)

CLI Tool

zengeld-agent is a standalone binary that ships with the terminal. It wraps common API operations behind a simple command-line interface and handles authentication, retries, and output formatting automatically.

install / location
# Binary is placed next to the terminal executable on install
# Windows: %LOCALAPPDATA%\mylittlechart\zengeld-agent.exe
# Linux / macOS: ~/.local/share/mylittlechart/zengeld-agent

# Or build from source
cargo build --release --bin zengeld-agent

Configuration file

Place a TOML config at ~/.zengeld-agent.toml to avoid passing flags every time:

~/.zengeld-agent.toml
# zengeld-agent configuration

api_key  = "your_key_here"
base_url = "http://localhost:17420"   # default, change for SSH tunnels
timeout  = 10                          # seconds
output   = "json"                      # "json" | "pretty" | "csv"

Usage examples

bash
# Print terminal health
zengeld-agent health

# Fetch 500 candles as CSV
zengeld-agent bars --exchange binance --symbol BTCUSDT --tf 1H --limit 500 --output csv

# Save screenshot to file
zengeld-agent screenshot --window 0 --tab 0 --chart 0 --out chart.png

# List all indicators on a chart
zengeld-agent indicators --window 0 --tab 0 --chart 0

# Watch indicator values in real time (polling)
zengeld-agent watch --indicator rsi_0 --interval 500ms

Endpoint Reference

All endpoints are prefixed with /api/v1. All responses are JSON unless noted.

Health — 1 endpoint
GET
/health Returns terminal version, uptime, and connected exchanges. No auth required.
open
response — GET /api/v1/health
{
  "status":   "ok",
  "version":  "0.4.1",
  "uptime_s": 3842,
  "windows":  2,
  "exchanges": ["binance", "bybit"]
}
Market Data — 3 endpoints
GET
/bars OHLCV candles from any connected exchange. Params: exchange, symbol, timeframe, limit (max 5000), before (unix ms).
read
GET
/connectors Lists all configured exchange connectors with their connection status and supported symbols.
read
GET
/watchlists Returns all saved watchlists with their symbol entries and last-known prices.
read
response — GET /api/v1/bars
{
  "exchange":   "binance",
  "symbol":     "BTCUSDT",
  "timeframe":  "1H",
  "bars": [
    {
      "t": 1741996800000,  // open time unix ms
      "o": 83412.5,
      "h": 84100.0,
      "l": 82990.0,
      "c": 83850.0,
      "v": 1284.37
    },
    // ...
  ]
}
Window Discovery — 5 endpoints
GET
/windows Lists all open terminal windows with their IDs and focus state.
read
GET
/windows/{wid} Details of a single window: geometry, title, whether it's minimized.
read
GET
/windows/{wid}/tabs Lists all tabs in a window with their active chart count and tab names.
read
GET
/windows/{wid}/tabs/{tid} Details of a single tab: layout, active chart index.
read
GET
/windows/{wid}/tabs/{tid}/charts Lists all chart panels in the tab layout with their symbol, exchange, timeframe, and viewport range.
read
Chart Control — 2 endpoints (read_write)
PATCH
/windows/{wid}/tabs/{tid}/charts/{cid}/viewport Pan and zoom the chart. Body: {"from_ms": 0, "to_ms": 0, "price_min": 0, "price_max": 0}. All fields optional.
write
PATCH
/windows/{wid}/tabs/{tid}/charts/{cid}/symbol Switch the chart to a different symbol or exchange. Body: {"symbol": "ETHUSDT", "exchange": "binance"}.
write
Indicators — 5 endpoints
GET
/windows/{wid}/tabs/{tid}/charts/{cid}/indicators Lists all indicators on the chart with their IDs, types, and parameter values.
read
POST
/windows/{wid}/tabs/{tid}/charts/{cid}/indicators Add an indicator. Body: {"type": "rsi", "params": {"period": 14}}. Returns the assigned indicator ID.
write
PATCH
/windows/{wid}/tabs/{tid}/charts/{cid}/indicators/{iid} Update indicator parameters. Body: {"params": {"period": 21}}.
write
DELETE
/windows/{wid}/tabs/{tid}/charts/{cid}/indicators/{iid} Remove an indicator from the chart.
write
GET
/windows/{wid}/tabs/{tid}/charts/{cid}/indicators/{iid}/values Returns the computed numeric series for the indicator. Params: limit, before.
read
response — GET …/indicators/rsi_0/values
{
  "indicator_id": "rsi_0",
  "type":         "rsi",
  "params": { "period": 14 },
  "series": [
    { "t": 1741996800000, "v": 58.34 },
    { "t": 1742000400000, "v": 61.07 },
    // ...
  ]
}
Drawing Primitives — 4 endpoints
GET
/windows/{wid}/tabs/{tid}/charts/{cid}/drawings Lists all drawing objects (trendlines, horizontal levels, fibs, rectangles) with coordinates and styles.
read
POST
/windows/{wid}/tabs/{tid}/charts/{cid}/drawings Add a drawing. Body: {"type": "hline", "price": 83000, "color": "#F4CD63", "label": "Support"}.
write
PATCH
/windows/{wid}/tabs/{tid}/charts/{cid}/drawings/{did} Update drawing properties (position, color, label, visibility).
write
DELETE
/windows/{wid}/tabs/{tid}/charts/{cid}/drawings/{did} Remove a drawing from the chart.
write
Catalog — 2 endpoints
GET
/catalog/indicators Search available indicator types. Params: q (name search), category (trend, oscillator, volume, …).
read
GET
/catalog/primitives Lists all supported drawing primitive types with their required and optional fields.
read
Screenshots — 1 endpoint
POST
/windows/{wid}/tabs/{tid}/charts/{cid}/screenshot Captures the chart as a PNG and returns it base64-encoded. Synchronous — waits for the next rendered frame (5 s timeout). Optional body: {"width": 1920, "height": 1080}.
read
response — POST …/screenshot
{
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",  // base64-encoded PNG
  "width":      1920,
  "height":     1080,
  "captured_at":1741996800000
}
API Keys — 3 endpoints (admin)
GET
/keys Lists all API keys with their tier, label, and last-used timestamp. Key values are never returned.
admin
POST
/keys Create a new key. Body: {"label": "my-script", "tier": "read_only"}. Admin keys cannot be created here — use the terminal UI.
admin
DELETE
/keys/{key_id} Revoke a key by ID. Takes effect immediately.
admin

Write Semantics

POST, PATCH, and DELETE endpoints return 202 Accepted immediately. The command is enqueued and applied on the terminal's next render frame (typically under 16 ms). This keeps the API non-blocking and consistent with the terminal's own frame-based update model.

write response (202)
{
  "accepted": true,
  "queued_at": 1741996800123
}

Response Format

All responses are JSON with Content-Type: application/json. HTTP status codes follow REST conventions:

Status Meaning
200 OK Successful read. Body contains requested data.
202 Accepted Write command queued. Will be applied on next frame.
400 Bad Request Missing or invalid parameters. Body: {"error": "..."}.
401 Unauthorized No key provided but registry is non-empty.
403 Forbidden Key exists but tier is insufficient for this endpoint.
404 Not Found Window, tab, chart, or object ID does not exist.
408 Request Timeout Screenshot timed out (terminal may be overloaded).
500 Internal Error Unexpected terminal error. Body: {"error": "..."}.
error response
{
  "error": "window 3 does not exist",
  "code":  "NOT_FOUND"
}

Rate Limits

The API has no hard rate limit for local connections. However, the screenshot endpoint is bounded by the terminal's frame rate — back-to-back screenshot calls will queue and each waits for a fresh rendered frame. For continuous monitoring, poll at most once per second per chart to avoid piling up queued captures.