Skip to main content
The @darkpool/agent-service package is a self-contained agent runtime. Each process is one agent. Run multiple instances with distinct names + ports for a fleet.

​
Required env

AGENT_KEY=suiprivkey1…                       # signing key for this agent
AGENT_PREDICT_MANAGER_ID=0x…                 # this agent's PredictManager
AGENT_STRATEGY=alternate                      # alternate | yes-only | no-only | llm
AGENT_NAME=btc-alpha                          # appears in /status + fleet view
AGENT_STATUS_PORT=8083                        # 8083+ (resolver owns 8082)
AGENT_TRADE_DUSDC=2                           # per-tick spend cap
AGENT_TICK_MS=60000                           # default 60s
Missing required vars → process exits 1 with a clean message. Optional: 
TRADE_AGENT_ID=0x…                           # if set, runtime reads is_active per tick
AGENT_PROMPT_FILE=packages/agent-service/prompts/momentum.md  # personality mandate
# LLM block. Only required when AGENT_STRATEGY=llm:
LLM_PROVIDER=groq                             # groq | anthropic | openai | ollama
LLM_API_KEY=gsk_…
LLM_MODEL=                                    # blank = provider default
LLM_BASE_URL=                                 # blank = provider default

​
Tick loop

​
Strategies

  • alternate / yes-only / no-only. Heuristic. Probes $50 strike rungs outward from spot, trades the first ask inside ask_bounds. See Heuristic Strategies.
  • llm. Native AI mode. The model researches via tools and submits a structured decision; the runtime executes under guardrails. See LLM Strategy.
Missing LLM_API_KEY when AGENT_STRATEGY=llm → falls back to alternate with a warning.

​
/status HTTP

The runtime exposes a tiny HTTP server on AGENT_STATUS_PORT: 
GET /status                            → { name, strategy, config, model, mandate, lastTick, ticks, mints, skips, errors, actionFeed: […] }
GET /health                            → { ok: true }
The frontend fleet view (/agents) polls each configured URL (comma-separated VITE_AGENT_STATUS_URLS) in parallel and renders the action feed inline.

​
Health hardening

The runtime collapses consecutive identical feed entries into one row with a ×N counter and humanizes common errors (gas / manager-balance / api-unreachable) via humanizeAgentError so the fleet card surfaces one actionable warning rather than log spam.

​
Logs

[agent btc-alpha] tick 14: spot $63320, picked YES @ $65000 ask 27.3¢, minting $2
[agent btc-alpha] tx 68vPpzXm… ok
[agent btc-alpha] tick 15: no quote in bounds for ask @ $50 rungs $63270..$63370

​
Multi-instance

# Agent #1: alternating buyer
AGENT_NAME=btc-alpha AGENT_STRATEGY=alternate AGENT_STATUS_PORT=8083 \
  pnpm --filter @darkpool/agent-service dev

# Agent #2. YES-only momentum agent
AGENT_NAME=btc-yes AGENT_STRATEGY=yes-only AGENT_STATUS_PORT=8084 \
  pnpm --filter @darkpool/agent-service dev

# Agent #3. LLM-brained, with a mandate
AGENT_NAME=btc-brain AGENT_STRATEGY=llm \
  AGENT_PROMPT_FILE=packages/agent-service/prompts/momentum.md \
  AGENT_STATUS_PORT=8085 \
  pnpm --filter @darkpool/agent-service dev
Frontend wiring: 
VITE_AGENT_STATUS_URLS=http://localhost:8083/status,http://localhost:8084/status,http://localhost:8085/status