API Reference

Base URL: http://127.0.0.1:8790 (default; configurable via --host and --port).

All responses are JSON. The gateway binds to localhost by default. Bind publicly only behind a trusted reverse proxy.

Start the gateway: koyal gateway

System

`GET /api/health`

Liveness probe.

{"status": "ok"}

`GET /api/doctor`

Full health check with version info.

{
  "status": "ok",
  "version": "0.1.0",
  "harness": "rust",
  "uptime_seconds": 142
}

`GET /api/overview`

Full dashboard state snapshot: agents, proposals, halt state, AI usage, wallets.

{
  "status": "ok",
  "agents": [],
  "proposals": [],
  "halt": {"halted": false, "reason": null},
  "aiUsage": {
    "totals": {"calls": 0, "inputTokens": 0, "outputTokens": 0}
  }
}

`GET /api/harness/status`

Current harness tick state.

{
  "totalSessionInputTokens": 0,
  "totalSessionOutputTokens": 0,
  "totalTicks": 0,
  "guardrailTriggers": [],
  "lastTickAt": null,
  "lastTickAgent": null,
  "lastTickResult": null
}

`GET /api/harness/token-usage`

Session token usage totals.

`GET /api/harness/guardrails`

Guardrail trigger history.

`POST /api/harness/tick`

Run one agent tick.

{"agent": "solana_jupiter", "propose": true, "newSession": false}

`GET /api/logs`

Fetch structured logs. Supports ?file=agent&limit=100&level=INFO.

`GET /api/usage`

AI provider token usage records.

Proposals

`GET /api/proposals`

List all trade proposals.

[
  {
    "id": "prop_1",
    "agentId": "solana_jupiter",
    "action": "swap",
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000000",
    "slippageBps": 50,
    "status": "pending",
    "createdAt": "2025-01-01T00:00:00Z"
  }
]

`POST /api/proposals`

Create a new trade proposal.

{
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "1000000000",
  "slippageBps": 50
}

`POST /api/proposals/approve`

Approve a proposal by ID.

{"id": "prop_1"}

`POST /api/proposals/reject`

Reject a proposal.

{"id": "prop_1", "reason": "price impact too high"}

`POST /api/proposals/execute`

Execute an approved proposal.

{"id": "prop_1"}

Halt Control

`GET /api/halt`

{"halted": false, "reason": null}

`POST /api/halt`

{"halted": true, "reason": "manual halt"}

Agents

`GET /api/agents`

List all managed agents.

`POST /api/agents`

Create a managed agent.

{
  "id": "trader1",
  "name": "Trader One",
  "kind": "trading",
  "model": "claude-sonnet-4-6",
  "tools": ["get_quote", "swap"],
  "memoryEnabled": true
}

Bots

`GET /api/bots`

List all bots. Supports ?agent=trader1.

`POST /api/bots`

Create a bot.

{
  "id": "bot1",
  "ownerAgentId": "trader1",
  "name": "Jupiter Bot",
  "venue": "jupiter"
}

`PATCH /api/bots/{id}`

Update bot fields.

`DELETE /api/bots/{id}`

Delete a bot.

`POST /api/bots/{id}/lifecycle`

Transition bot lifecycle.

{"target": "live"}

States: paper → live → paused

`GET /api/bots/{id}/risk`

Get bot risk config.

`PUT /api/bots/{id}/risk`

Set bot risk config.

{
  "maxPositionPct": 2.0,
  "maxDrawdownPct": 5.0,
  "maxDailyTrades": 10
}

`POST /api/bots/{id}/assign-wallet`

Assign a wallet to a bot.

{"walletId": "wallet_id"}

Wallets

`GET /api/wallets`

List all wallets.

`POST /api/wallets`

Import a wallet.

{
  "label": "Trade Wallet",
  "address": "7R7tHW6...",
  "chain": "solana",
  "role": "trade"
}

`POST /api/wallets/generate`

Generate a new wallet.

{"chain": "solana", "index": 0}

Response includes address, public key, and (optionally) encrypted private key.

`POST /api/wallets/{id}/derive`

Derive a wallet for another chain from the same seed.

{"chain": "evm", "index": 0}

`PATCH /api/wallets/{id}`

Update wallet metadata.

`DELETE /api/wallets/{id}`

Remove wallet from store.

Executors

`GET /api/executors`

List active trading executors. Supports ?agent=trader1.

`GET /api/executor-snapshot`

Snapshot executor state for an agent.

`GET /api/permissions`

List pending permission requests (approval queue).

`POST /api/approvals/respond`

Respond to a pending approval request.

{"requestId": "req_1", "decision": "allow"}

Loops

`GET /api/loops`

List all loops. Supports ?agent=trader1.

`POST /api/loops`

Create a loop from a blueprint.

{"agentId": "trader1", "blueprint": "price_watcher"}

`PATCH /api/loops/{id}`

Update loop config.

`DELETE /api/loops/{id}`

Delete a loop.

`POST /api/loops/{id}/toggle`

Enable or disable a loop.

`POST /api/loops/{id}/run`

Run a loop immediately (ignores schedule).

`GET /api/blueprints`

List available loop blueprints.

[
  {"id": "price_watcher", "name": "Price Watcher", "description": "..."},
  {"id": "wallet_monitor", "name": "Wallet Monitor", "description": "..."}
]

Skills

`GET /api/skills`

List all skills with state.

`GET /api/skills/catalog`

Full skill catalog (installed + available).

`GET /api/skills/{name}`

Get a specific skill.

`POST /api/skills/toggle`

Toggle skill active/inactive.

{"name": "trading-agent-builder"}

`POST /api/skills/refresh`

Force refresh skill metadata from disk.

Vault

`GET /api/vault/agents`

List agents with a vault directory.

`GET /api/vault/bible/{agent}`

Full composed bible (soul + instructions + memories + learnings + bot configs).

`GET /api/vault/bible-files/{agent}`

List bible component files.

`GET /api/vault/soul/{agent}`

Read soul.md.

`PUT /api/vault/soul/{agent}`

Write soul.md.

{"content": "I trade conservatively..."}

`GET /api/vault/instructions/{agent}`

Read instructions.md.

`PUT /api/vault/instructions/{agent}`

Write instructions.md.

`GET /api/vault/memories/{agent}`

List memories.

`POST /api/vault/memories/{agent}`

Write a memory.

{"key": "risk_level", "value": "conservative", "tags": ["config"]}

`GET /api/vault/learnings/{agent}`

List learnings.

`POST /api/vault/learnings/{agent}`

Write a learning entry.

`POST /api/vault/propose-edit/{agent}`

Submit a vault edit proposal (goes through approval flow).

`GET /api/vault/bots/{agent}`

List bots in the vault for an agent.

AI / Chat

`POST /api/chat`

Send a message to the agent’s AI provider.

{
  "messages": [{"role": "user", "content": "What's the SOL price?"}],
  "agent": "trader1"
}

`GET /api/providers`

List AI providers and their configured status.

`GET /api/context`

Current agent context (config + vault summary).

MCP

`GET /api/mcp`

List configured MCP servers.

`POST /api/mcp`

Add an MCP server.

{
  "name": "Solana",
  "url": "https://mcp.solana.com/mcp",
  "chain": "solana",
  "toolPrefix": "solana_",
  "enabled": true
}

`PATCH /api/mcp/{name}`

Update MCP server config.

`DELETE /api/mcp/{name}`

Remove an MCP server.

`POST /api/mcp/test`

Test connectivity to an MCP server.

`GET /api/mcp/tools`

List all tools from connected MCP servers.

`POST /api/mcp/call`

Call an MCP tool.

{"method": "solana_get_balance", "args": {"address": "..."}}

Connectors

`GET /api/connectors/catalog`

Full connector catalog.

`GET /api/connectors`

List active connections.

`POST /api/connectors`

Create a connection instance.

`PATCH /api/connectors/{id}`

Update a connection.

`DELETE /api/connectors/{id}`

Remove a connection.

Settings

`GET /api/settings`

Get all harness settings.

`PATCH /api/settings`

Update settings.

{"ai.gateway": "anthropic", "ai.model": "claude-sonnet-4-6"}

`GET /api/settings/schema`

JSON schema for all settings (used by the dashboard settings UI).

Setup

`GET /api/setup`

Setup checklist status. Used by the dashboard onboarding flow.

WebSocket

`GET /ws`

Real-time update stream. Connect with any WebSocket client.

const ws = new WebSocket('ws://127.0.0.1:8790/ws');
ws.onmessage = (e) => console.log(JSON.parse(e.data));

Message types: init, proposal, executor_update, learning, tick_complete, halt_change.

Keyboard shortcuts

Koyal Docs