Loop Blueprints

Blueprints are pre-built loop templates. Instantiate one with koyal loop create --blueprint <id> or POST /api/loops {"blueprint": "<id>"}.

Available Blueprints

price_watcher

Monitors an asset price at a configurable interval. Posts to Telegram or webhook on threshold breach.

{
  "blueprint": "price_watcher",
  "agentId": "trader1",
  "params": {
    "symbol": "SOL/USDC",
    "intervalSecs": 60,
    "alertThresholdPct": 3.0,
    "notify": "telegram"
  }
}

Actions: Read-only. No trades.

wallet_monitor

Polls wallet balances on a schedule. Alerts on balance drop beyond threshold.

{
  "blueprint": "wallet_monitor",
  "agentId": "trader1",
  "params": {
    "walletId": "wallet_1",
    "chain": "solana",
    "intervalSecs": 300,
    "alertThresholdPct": 10.0
  }
}

Actions: Read-only. Query balance, send alert.

dca

Dollar-cost averaging. Buys a fixed amount on a fixed schedule.

{
  "blueprint": "dca",
  "agentId": "trader1",
  "params": {
    "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputMint": "So11111111111111111111111111111111111111112",
    "amountUsdc": 100,
    "intervalHours": 24,
    "slippageBps": 50
  }
}

Actions: Creates trade proposals on schedule.

pnl_reporter

Computes realized/unrealized PnL from the trade ledger and posts a summary.

{
  "blueprint": "pnl_reporter",
  "agentId": "trader1",
  "params": {
    "intervalHours": 24,
    "notify": "telegram",
    "includeLedgerSummary": true
  }
}

Actions: Read-only. Reads ledger, sends report.

agent_tick_loop

Runs agent ticks on a cron schedule. The core loop for autonomous trading.

{
  "blueprint": "agent_tick_loop",
  "agentId": "trader1",
  "params": {
    "cron": "*/30 * * * *",
    "propose": true,
    "newSession": false
  }
}

Actions: Calls POST /api/harness/tick. Full trading authority.

health_ping

Periodic self-health check. Alerts if the harness or providers become unhealthy.

{
  "blueprint": "health_ping",
  "agentId": "trader1",
  "params": {
    "intervalSecs": 300,
    "notify": "telegram"
  }
}

position_close

One-shot loop that closes all open positions for a bot. Useful for emergency deleveraging.

{
  "blueprint": "position_close",
  "agentId": "trader1",
  "params": {
    "botId": "bot1",
    "maxSlippageBps": 100
  }
}

CLI

# List available blueprints
koyal loop blueprints

# Create from blueprint
koyal loop create --blueprint price_watcher --agent trader1

# List running loops
koyal loop list --agent trader1

# Toggle a loop on/off
koyal loop toggle --id loop_id_1

# Run once immediately
koyal loop run --id loop_id_1

Custom Loops

Create a loop without a blueprint:

POST /api/loops
{
  "agentId": "trader1",
  "name": "My Custom Loop",
  "cron": "0 */4 * * *",
  "action": "tick",
  "params": {"propose": true}
}

Supported action values: tick, price_check, balance_check, pnl_report, health_check, custom_script.