Agents - Circuit

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

Header	Description
`Authorization: Bearer {token}`	User’s bearer token from authentication

Query Parameter	Description
`agentId`	Agent ID to evaluate
`walletIds`	Wallet 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.
  readiness: Record<number, {
    id: number;
    address: string;
    name?: string;
    totalBalanceUsd?: string;
    status: "ready" | "fundable" | "short" | "unknown";
    error?: string;
    blocker?: "wrong_vm_family" | "session_running" | "sanctioned" | "polymarket_not_grandfathered";
    // Marked value of recorded unallocated quantities (full portfolio). Display only.
    recordedUnallocatedUsd?: string;
    // Startable inventory USD (held required + accepted autoswap sources). Wallet
    // selection ranks by this — the same capacity the start picker's Available column shows.
    // A lower bound: unpriced accepted sources contribute nothing to the sum.
    availableToUseUsd?: string;
    assets?: Array<{
      symbol: string;
      network: string;
      address: string;
      haveFormatted: string;
      needFormatted: string;
      gapFormatted: string;
      haveUsd?: string;
      needUsd?: string;
      gapUsd?: string;
      lockedFormatted?: string;
    }>;
    // Recorded allocation-capacity rows and the executor's independently live
    // funding-source observation. `authorities` has one outcome per attempted
    // network/venue; failures never masquerade as empty balances.
    allocation?: {
      isValid: boolean;
      requiredAsset: object;
      sources?: {
        autoswapSources: object[];
        rejectedAutoswapSources: object[];
        authorities: Array<
          | { network: string; status: "available" }
          | { network: string; status: "unavailable"; reason: string }
        >;
        fundingSourceBalances: object[];
      };
      sourcesError?: string;
      unallocatedBalances: object[];
    };
  }>;
  failedStartSettings: Record<number, object>;
}

Start Agent Session

Begin running an agent on a specific wallet. Endpoint: POST /v1/agents/start The request seats a run-wallet-scoped permit on the agent. The start is held-only: the wallet must already hold the required starting asset (any funding swap runs first as its own swap operation), and the session’s allocation locks min(allocationTargetRaw, recorded availability). The server returns an operation ID immediately; poll the intent-status endpoint until it completes. Request

Header	Description
`Authorization: Bearer {token}`	User’s bearer token from authentication

Body	Type	Required	Description
`agentId`	`string`	true	Agent UUID
`walletId`	`number`	true	Agent wallet ID (where the agent runs and the allocation locks) from `GET /v1/wallets/list`
`idempotencyKey`	`string`	true	Client-generated UUID that collapses retried POSTs onto the same durable operation instead of starting a second session.
`scopedPermit`	`string`	true	Long-lived permit scoped to the run wallet and attached private credentials. Trading credentials use `wallet.sign`, which includes private reads; read-only credentials use `wallet.read`.
`allocationTargetRaw`	`string`	true	Allocation target in raw base units of the agent’s required asset. `"0"` starts with no wallet allocation (exchange-only / zero-minimum agents). The session locks `min(target, recorded availability)`.
`mode`	`"auto" \| "manual"`	false	Execution mode. Defaults to `"auto"`. Must be in the agent’s `allowedExecutionModes`.
`runtime`	`"lambda" \| "cloudflare"`	false	Runtime for this session. Defaults to `"lambda"`.
`settings`	`array`	false	Session setting overrides: `[{ key: string, value: { text } \| { bool } \| { number } }]`. Required settings must be provided.

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": "42abaad6-426c-43c8-acbe-283b27f2c8ee",
    "walletId": 456,
    "idempotencyKey": "b3f1c0de-0000-4000-8000-000000000001",
    "scopedPermit": "circuit_permit_...",
    "allocationTargetRaw": "100000000000000",
    "mode": "auto",
    "runtime": "lambda"
  }'

Response If the session already exists:

{ state: "active", sessionId: number }

Otherwise the queued start returns { state: "starting", operationId: string }. Poll GET /v1/operations/{operationId} for progress and terminal state.

Get Agent Session Info

Retrieve the full detail for a running or stopped agent session you own - status, schedule, inventory, ROI, and the agent it runs. Endpoint: GET /v1/agents/sessionInfoById Request

Header	Description
`Authorization: Bearer {token}`	User’s bearer token from authentication

Query Parameter	Description
`sessionId`	Session 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
  balances: Array<{ ... }>;      // fungible rows in the session inventory
  roiPercent: number | null;     // null until every required allocation fact is priced
  roiUsd: number | null;
  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

Header	Description
`Authorization: Bearer {token}`	User’s bearer token from authentication

Body	Description
`sessionId: number`	Session 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;
}

​Get Agent Templates

​Check Start Readiness

​Start Agent Session

​Get Agent Session Info

​Stop Agent Session

Get Agent Templates

Check Start Readiness

Start Agent Session

Get Agent Session Info

Stop Agent Session