Skip to main content
Circuit REST endpoints are grouped by resource: /v1/{resource}/{operation}. Agent endpoints live under /v1/agents/.

​
Get Agent Templates

Fetch the template metadata used to create or inspect agent projects. Endpoint: GET /v1/agents/templates cURL Example 
curl -X GET "https://api.circuit.org/v1/agents/templates"
Response 
{
  templates: Record<string, Record<string, Record<string, string>>>;
  descriptionTemplate: string;
  agentsMd: string;
}

​
Check Start Readiness

Check whether one or more wallets have the assets needed to start an agent. Endpoint: GET /v1/agents/startReadinessBatch Request
HeaderDescription
Authorization: Bearer {token}User’s API auth token acquired from authentication
Query ParameterDescription
agentIdAgent ID to evaluate
walletIdsWallet ID to evaluate. Repeat the parameter for multiple wallets. Omit entirely to evaluate all of the caller’s unarchived wallets.
cURL Example 
curl -X GET "https://api.circuit.org/v1/agents/startReadinessBatch?agentId=1&walletIds=456" \
  -H "Authorization: Bearer api_auth_token"
Response 
{
  // Whether the agent trades on Hyperliquid (its required asset lives on a
  // Hypercore network).
  isHyperliquidAgent: boolean;
  // One entry per evaluated wallet, keyed by wallet ID.
  fits: Record<number, {
    id: number;
    address: string;
    name?: string;
    totalUsd?: string;
    status: "ready" | "short" | "unknown";
    swappableUsd?: string;
    assets?: Array<{
      kind: "required" | "gas";
      symbol: string;
      network: string;
      address: string;
      haveFormatted: string;
      needFormatted: string;
      gapFormatted: string;
      haveUsd?: string;
      needUsd?: string;
      gapUsd?: string;
      lockedFormatted?: string;
    }>;
    // Full allocation detail for the wallet: the validated required/gas
    // assets, the server-ranked funding plan, and the wallet's unallocated
    // balances. Absent when validation failed for this wallet.
    allocation?: object;
  }>;
}

​
Start Agent Session

Begin running an agent on a specific wallet. Endpoint: POST /v1/agents/start This endpoint is intended for browser clients that can derive fresh passkey PRF material for the operation. Do not store or reuse the masterKey value. The hosted session receives a server-held signing credential that does not expire while the session remains active. This is a streaming operation: the response is an application/x-ndjson stream of progress lines (planning → executing → settling), terminated by a single result line. The client re-POSTs with the same idempotencyKey until the terminal line reports a terminal state ("done" or "failed"). Request
HeaderDescription
Authorization: Bearer {token}User’s API auth token acquired from authentication
BodyTypeRequiredDescription
agentIdnumbertrueAgent ID
walletIdnumbertrueAgent wallet ID (where the agent runs and the allocation locks) from GET /v1/wallets/list
allocationRawstringtrueTarget amount of the agent’s required asset to allocate, in raw base units (a non-negative integer string). The server derives the required asset from the agent, funds the wallet if short, and computes the final locked amount from post-funding balances.
idempotencyKeystringtrueClient-generated UUID that collapses retried POSTs onto the same durable operation instead of starting a second session.
sourceWalletIdnumberfalseSeparate funding source; defaults to walletId.
autoswapChoiceobjectfalseThe binding source plan: { tokens: string[] } — the ordered token identities to fund from, in priority order. The server draws sources in exactly this order and swaps only these. Omit for the server default ranking.
mode"auto" | "manual"falseExecution mode. Defaults to "auto". Must be in the agent’s allowedExecutionModes.
settingsarrayfalseSession setting overrides: [{ key: string, value: { text } | { bool } | { number } }]. Required settings must be provided.
masterKeystringfalseFresh passkey-derived wallet-manager authority. Required only on the first start that provisions signing for the account; subsequent starts reuse the server-held credential.
cURL Example 
curl -N -X POST "https://api.circuit.org/v1/agents/start" \
  -H "Authorization: Bearer api_auth_token" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": 1,
    "walletId": 456,
    "allocationRaw": "100000000000000",
    "idempotencyKey": "b3f1c0de-0000-4000-8000-000000000001",
    "mode": "auto",
    "masterKey": "passkey_derived_master_key"
  }'
Response NDJSON stream. The terminal line is the operation result; on success: 
{ type: "result", state: "done", result: { sessionId: number } }
While funding is still in progress the same poll returns { state: "working" }; on failure it returns { state: "failed", error: string }.

​
Get Agent Session Info

Retrieve the full detail for a running or stopped agent session you own — status, schedule, balances, ROI, and the agent it runs. Endpoint: GET /v1/agents/sessionInfoById Request
HeaderDescription
Authorization: Bearer {token}User’s API auth token acquired from authentication
Query ParameterDescription
sessionIdSession ID returned by POST /v1/agents/start
cURL Example 
curl -X GET "https://api.circuit.org/v1/agents/sessionInfoById?sessionId=789" \
  -H "Authorization: Bearer api_auth_token"
Response The full session detail. Key fields: 
{
  id: number;
  status: "running" | "scheduled" | "paused" | "stopped";
  startedAt: string;
  nextRunAt: string | null;      // next scheduled run, null when stopped
  runStartedAt: string | null;   // set while a run is in progress
  runIntervalSeconds: number;
  balances: Array<{ ... }>;      // the session's allocated balances
  roiPercent: number;
  roiUsd: number;
  agent: { id: string; name: string; ... } | null;
}

​
Stop Agent Session

Stop a running agent session. Endpoint: POST /v1/agents/unwind This endpoint requires authorization for the session wallet (sessionWalletSign). Request
HeaderDescription
Authorization: Bearer {token}User’s API auth token acquired from authentication
BodyDescription
sessionId: numberSession ID returned by POST /v1/agents/start
cURL Example 
curl -X POST "https://api.circuit.org/v1/agents/unwind" \
  -H "Authorization: Bearer api_auth_token" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": 789 }'
Response 
{
  success: boolean;
}