Skip to main content
The Agents API is the primary interface for inspecting and controlling the Halyrd trading agent. All endpoints are scoped to a specific agent by ID — use the /agents/current alias whenever you want to target the single running instance without hardcoding an ID. Lifecycle actions (promote, demote, kill-switch) are irreversible or near-irreversible; read their individual caveats before calling them in production.

​
GET /agents

Returns the list of agents registered in this Halyrd instance. The array always contains exactly one element in the current release. 
GET http://localhost:8000/agents
Response 
[
  {
    "id": "seed",
    "name": "Halyrd",
    "status": "PAPER",
    "phase": "paper",
    "market_mode": "spot",
    "last_heartbeat": "2025-06-22T14:00:00Z"
  }
]
FieldTypeDescription
idstringStable agent identifier. Use this as {id} in all scoped paths.
namestringHuman-readable agent name.
statusstringOne of PAPER, ELIGIBLE, LIVE, DEMOTED.
phasestringActive trading phase (paper or live).
market_modestringTrading mode — currently always spot.
last_heartbeatstringISO 8601 timestamp of the most recent internal heartbeat.

​
GET /agents/

Returns a single agent object. /agents/current is a convenience alias that resolves to the running agent without requiring you to know its ID. 
GET http://localhost:8000/agents/seed
# or
GET http://localhost:8000/agents/current
Response 
{
  "id": "seed",
  "name": "Halyrd",
  "status": "PAPER",
  "phase": "paper",
  "market_mode": "spot",
  "last_heartbeat": "2025-06-22T14:00:00Z"
}

​
PATCH /agents//config

Updates the agent’s evaluation configuration. Each accepted patch creates a new immutable ConfigVersion and sets it as current. The previous version is retained in the version history. 
PATCH http://localhost:8000/agents/current/config
Content-Type: application/json
Request body 
{
  "evaluation_config": {
    "max_drawdown_pct": 15.0,
    "daily_drawdown_pct": 5.0,
    "max_consecutive_losses": 3,
    "eval_window_days": 14,
    "trade_floor": 15
  }
}
FieldTypeDescription
max_drawdown_pctnumberMaximum peak-to-trough drawdown allowed during the eval window, as a percentage.
daily_drawdown_pctnumberMaximum intraday drawdown allowed before the agent stands aside, as a percentage.
max_consecutive_lossesintegerNumber of back-to-back losing trades that triggers a cooldown.
eval_window_daysintegerLength of the evaluation window in calendar days.
trade_floorintegerMinimum number of closed trades required to reach ELIGIBLE.
Response 
{
  "id": "cfv_abc",
  "parent_id": "cfv_prev",
  "params_summary": "max_dd=15%, daily_dd=5%, window=14d, floor=15",
  "created_at": "2025-06-22T10:00:00Z"
}

​
GET /agents//watchlist/candidates

Returns a ranked list of token candidates the agent considers tradeable given current market conditions and your configured strategy. Use this to inform your manual watchlist selection before committing via PUT /watchlist. 
GET http://localhost:8000/agents/current/watchlist/candidates
Response 
[
  { "token": "ETH", "rank": 1, "score": 0.91, "reason": "Strong mean-reversion setup, RSI 22." },
  { "token": "LINK", "rank": 2, "score": 0.74, "reason": "Price 4.8% below 48h SMA, low funding." },
  { "token": "CAKE", "rank": 3, "score": 0.61, "reason": "Moderate setup; elevated spread — monitor." }
]

​
PUT /agents//watchlist

Replaces the agent’s active watchlist with the supplied token array and syncs the TWAK signing allowlist at runtime. This takes effect immediately without requiring an agent restart. 
PUT http://localhost:8000/agents/current/watchlist
Content-Type: application/json
Request body 
{
  "tokens": ["ETH", "CAKE", "LINK"]
}
Response — returns a new ConfigVersion: 
{
  "id": "cfv_xyz",
  "parent_id": "cfv_abc",
  "params_summary": "watchlist=[ETH, CAKE, LINK]",
  "created_at": "2025-06-22T10:15:00Z"
}
The TWAK allowlist must always be a superset of the agent’s watchlist. When you call this endpoint, the allowlist is updated automatically to satisfy that constraint — you do not need to manage it separately.

​
POST /agents//promote

Attempts to promote the agent from paper trading to live trading. The agent must be in ELIGIBLE status unless you pass force: true. 
POST http://localhost:8000/agents/current/promote
Content-Type: application/json
Request body 
{
  "force": false
}
Success response — 200 OK 
{
  "status": "LIVE",
  "first_tx_hash": "0xabc..."
}
Error response — 409 Conflict 
{
  "error": "NOT_ELIGIBLE",
  "message": "Agent has not met evaluation criteria. Use force: true to override."
}
Passing force: true bypasses the evaluation gate and takes the agent live immediately, regardless of whether objectives have been met. Only use this if you have manually verified readiness.

​
POST /agents//demote

Returns the agent to paper-trading mode. Any open live positions will be closed at market before the transition completes. 
POST http://localhost:8000/agents/current/demote
Response 
{
  "status": "PAPER"
}

​
POST /agents//kill-switch

Immediately revokes the agent’s TWAK signing session, preventing any further order submissions. This is the emergency stop. 
POST http://localhost:8000/agents/current/kill-switch
Content-Type: application/json
Request body 
{
  "confirm": true
}
Response 
{
  "twak_session": "revoked"
}
Calling the kill-switch immediately revokes the agent’s signing rights. No new orders can be submitted until a new TWAK session is provisioned. This action cannot be undone via the API — you must re-provision through the dashboard.

​
GET /agents//config/versions

Returns the full version history of configuration changes for the agent, ordered from most recent to oldest. Each version records the parameters it was created with, the period it was active, and its outcome. 
GET http://localhost:8000/agents/current/config/versions
Response 
[
  {
    "id": "cfv_abc",
    "parent_id": null,
    "params_summary": "balanced preset",
    "run_period": {
      "from": "2025-06-15T00:00:00Z",
      "to": null
    },
    "outcome": "running"
  }
]
FieldTypeDescription
idstringUnique ID for this config version.
parent_idstring | nullID of the version this was derived from; null for the initial version.
params_summarystringHuman-readable summary of the key parameters.
run_period.fromstringISO 8601 timestamp when this version became active.
run_period.tostring | nullISO 8601 timestamp when it was superseded; null if currently active.
outcomestringrunning, superseded, demoted, or killed.

​
GET /agents//identity

Returns the agent’s on-chain identity metadata, including its ERC-8004 token ID and links to its on-chain profile and block explorer page. 
GET http://localhost:8000/agents/current/identity
Response 
{
  "erc8004_token_id": "42",
  "profile_uri": "https://halyrd.xyz/agents/seed",
  "bscscan_url": "https://bscscan.com/token/0xabc...#42"
}
FieldTypeDescription
erc8004_token_idstringThe token ID that uniquely identifies this agent on-chain under the ERC-8004 standard.
profile_uristringPublic URL for the agent’s metadata profile.
bscscan_urlstringDirect link to the agent’s token entry on BscScan.