Agent API

Configuration

Credentials are hardcoded in the wrapper script. No need to read TOOLS.md.

Agent IDs (UUIDs)

All agent/* endpoints require agent_id (UUID), not agent_name.

agent_key	name	agent_id
md	John Smith	06ce74f6-0406-484e-b5f2-632316b73f66
trader	Chad	ab990f5c-3cba-4ab7-a41a-8241c9628665
quant	Dexter	ccb259c3-64cd-45b2-b0c5-0d03128213ce
analyst	Gina	b4d79f10-bcdb-4485-bcc4-556e0e07abb1
audit	Clark	fd38eed7-d48a-4743-bf01-93eb883005fc
performance	Usain	f46f189c-b049-4d7d-9229-01323f4ca235
serge	Serge	344b8622-8061-482f-a0c1-d5eb26ce7949

Making Requests

Use the wrapper script for all API calls:

./scripts/api/agent_api.sh <endpoint> '<json_payload>'

If no payload is needed, omit the second argument (defaults to {}).

Examples:

./scripts/api/agent_api.sh trading/get_account_state
./scripts/api/agent_api.sh data/get_facts '{"from_timestamp":"2026-03-01T00:00:00Z","to_timestamp":"2026-03-01T16:00:00Z"}'
./scripts/api/agent_api.sh agent/send_log '{"agent_id":"b4d79f10-bcdb-4485-bcc4-556e0e07abb1","content":"bullish thesis confirmed"}'
./scripts/api/agent_api.sh agent/save_memory '{"agent_id":"b4d79f10-bcdb-4485-bcc4-556e0e07abb1","state":{}}'

Endpoints

Agent Management

Endpoint	Payload	Notes
agent/get_agents	{}	Returns all agents with hierarchy

Agent Memory & Reports

Endpoint	Payload
agent/get_memory	{"agent_id": "<uuid>", "page": 1, "limit": 1}
agent/save_memory	{"agent_id": "<uuid>", "state": <json>}
agent/get_reports	{"agent_id": "<uuid>", "page": 1, "limit": 20}
agent/save_report	{"agent_id": "<uuid>", "report": {"title": "...", "content": "..."}}
agent/send_log	{"agent_id": "<uuid>", "content": <json-serializable>}
agent/get_logs	{"agent_id": "<uuid>", "page": 1, "limit": 20} (omit agent_id for global feed)

Agent Tasks

Tasks are ordered by priority (P1 → P3) then newest timestamp.

agent/get_tasks

Fetches tasks (global or per-agent).

Field	Type	Notes
agent_id	string (UUID)	optional — omit for global feed
page	number	optional, default 1, must be >= 1
limit	number	optional, default 100, must be >= 1

Response fields per task:

id: number
agent_id: string (UUID)
agent_key: string
agent_name: string
agent_role: string
agent_avatar_url?: string | null
title: string
content: string
priority: "P1" | "P2" | "P3"
status: "waiting" | "ready" | "done" | "closed"
user_note: string
timestamp: string | null

agent/save_task

Creates a new task.

Field	Type	Notes
agent_id	string (UUID)	required
title	string	required, short label
content	string	required, full description/details
priority	"P1" | "P2" | "P3"	required

agent/update_task_note

Updates a task's user_note and/or status.

Field	Type	Notes
task_id	number	required, positive int
user_note	string	required
status	"waiting" | "ready" | "done" | "closed"	optional

Returns: { task_id, user_note, status }

Usage pattern (create): fetch existing tasks first, then only create tasks whose title is not already present.
Usage pattern (execute): see agents/TASK_MANAGEMENT.md for the full task execution workflow.

Agent Incidents

Incidents track operational errors and bugs that require resolution. Distinct from tasks: an incident documents what went wrong; a task is a specific action to fix it.

agent/save_incident

Creates a new incident.

Field	Type	Notes
agent_id	string (UUID)	required — agent that detected/owns the incident
incident	string	required — complete description of the incident (what happened, impact, context)
title	string	optional — short descriptive label (no prefixes like CRITICAL/WARNING)
level	"critical" | "warning" | "info"	optional, default "warning"
status	"open" | "closed"	optional, default "open"
user_note	string	optional — dev0xx's notes
agent_note	string	optional — agent's resolution notes

When to set status:

• "open" — incident needs resolution (leave for MD/dev0xx to act on)
• "closed" — already resolved or just needs documentation

agent/get_incidents

Fetches incidents (global or per-agent).

Field	Type	Notes
agent_id	string (UUID)	optional — omit for global feed
page	number	optional, default 1
limit	number	optional, default 20

Response fields per incident:

id: number
agent_id: string (UUID)
title: string
incident: string
level: "critical" | "warning" | "info"
status: "open" | "closed"
user_note: string
agent_note: string
timestamp: string | null

agent/update_incident

Updates an incident's status and/or notes.

Field	Type	Notes
incident_id	number	required
status	"open" | "closed"	optional
user_note	string	optional
agent_note	string	optional — use to document resolution actions taken

Usage pattern (resolve): after completing a task that fixes an incident, call update_incident with agent_note summarizing what was done and set status: "closed".
Usage pattern (dedup): fetch existing incidents first (get_incidents), then only create incidents not already present (match semantically, not just by title).

Agent Research

Endpoint	Payload
agent/save_research	{"agent_id": "<uuid>", "research": {"title": "...", "content": "..."}}
agent/get_research	{"agent_id": "<uuid>", "page": 1, "limit": 20} (omit agent_id for global feed)

Market Data

Endpoint	Payload
data/get_facts	{"from_timestamp": "<ISO>", "to_timestamp": "<ISO>"}
data/get_market_snapshot	{"timestamp": "<ISO>"}
data/get_technical_indicators	{}
data/now	{} (public, no auth)

Trading (Hyperliquid)

All trading endpoints accept an optional hyperliquid_env parameter: "mainnet" (default) or "testnet". Case-insensitive, falls back to mainnet if invalid. Omit for mainnet (no need to set explicitly).

Endpoint	Payload
trading/get_account_state	{"hyperliquid_env": "mainnet"} (env optional, default mainnet)
trading/open_position	{"sz_pct": <float>, "is_buy": <bool>, "leverage": <int>, "tp_px": <float>, "sl_px": <float>, "hyperliquid_env": "mainnet"} (env optional)
trading/close_position	{"hyperliquid_env": "mainnet"} (env optional)

Memory Sync (Start of Run)

Before reading local state, sync from backend:

./scripts/api/update_memory.sh <agent_key>

This fetches latest memory via agent/get_memory and writes to memory/states/<agent_key>-state.json. Run at the START of every agent run.

Reports (Run Cache)

After each pipeline run, agents write their output to memory/reports/<agent_key>.md. To push this as a report:

./scripts/api/send_report.sh <agent_key> "<title>"

Title should be a short descriptive string (e.g. "macro analysis", "technical levels", "trade decision").

Notes

• ALL requests are POST with JSON body. GET returns 405.
• All timestamps must be ISO-8601 (e.g. 2026-03-01T16:00:00Z).
• agent_id is UUID — never use agent_name in API calls.
• updated_at is auto-set by backend on save_memory, save_research, and save_report (when report is dict). Do NOT set it manually in payloads.
• sz_pct = position size as fraction of account (0.01 = 1%)
• is_buy = true for long, false for short
• tp_px / sl_px = take profit / stop loss price (both required on open)
• SL placement: For longs, sl_px BELOW current price. For shorts, sl_px ABOVE. Otherwise triggers immediately.
• Always check trading/get_account_state before opening positions.

Error Handling

If any endpoint returns non-200 or "status": "error":

1. Stop and report to dev0xx immediately
2. Include: endpoint, HTTP status, error message
3. Do not retry silently or continue without the backend