> ## Documentation Index > Fetch the complete documentation index at: https://docs.circuit.org/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Base URL: https://api.circuit.org/v1 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** ```bash theme={null} curl -X GET "https://api.circuit.org/v1/agents/templates" ``` **Response** ```typescript theme={null} { templates: Record>>; 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 API auth token acquired 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** ```bash theme={null} curl -X GET "https://api.circuit.org/v1/agents/startReadinessBatch?agentId=1&walletIds=456" \ -H "Authorization: Bearer api_auth_token" ``` **Response** ```typescript theme={null} { // 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; // 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** | Header | Description | | ------------------------------- | -------------------------------------------------- | | `Authorization: Bearer {token}` | User's API auth token acquired from authentication | | Body | Type | Required | Description | | ---------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | `number` | true | Agent ID | | `walletId` | `number` | true | Agent wallet ID (where the agent runs and the allocation locks) from [`GET /v1/wallets/list`](./wallet-endpoints#list-user-wallets) | | `allocationRaw` | `string` | true | Target 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. | | `idempotencyKey` | `string` | true | Client-generated UUID that collapses retried POSTs onto the same durable operation instead of starting a second session. | | `sourceWalletId` | `number` | false | Separate funding source; defaults to `walletId`. | | `autoswapChoice` | `object` | false | The 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"` | false | Execution mode. Defaults to `"auto"`. Must be in the agent's `allowedExecutionModes`. | | `settings` | `array` | false | Session setting overrides: `[{ key: string, value: { text } \| { bool } \| { number } }]`. Required settings must be provided. | | `masterKey` | `string` | false | Fresh 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** ```bash theme={null} 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: ```typescript theme={null} { 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** | Header | Description | | ------------------------------- | -------------------------------------------------- | | `Authorization: Bearer {token}` | User's API auth token acquired from authentication | | Query Parameter | Description | | --------------- | ------------------------------------------------------------------------------ | | `sessionId` | Session ID returned by [`POST /v1/agents/start`](./agents#start-agent-session) | **cURL Example** ```bash theme={null} 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: ```typescript theme={null} { 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** | Header | Description | | ------------------------------- | -------------------------------------------------- | | `Authorization: Bearer {token}` | User's API auth token acquired from authentication | | Body | Description | | ------------------- | ------------------------------------------------------------------------------ | | `sessionId: number` | Session ID returned by [`POST /v1/agents/start`](./agents#start-agent-session) | **cURL Example** ```bash theme={null} 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** ```typescript theme={null} { success: boolean; } ```