Agents - Circuit

List Available Agents

Get all agents available to the user. Endpoint: GET /agents Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

cURL Example

curl -X GET "https://api.circuit.org/v1/agents"    -H "Authorization: Bearer api_auth_token"

Response

Returns Agents

Array<{
  id: number;
  name: string;
  description: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    id: number;
    username: string;
  };
  imageUrl: string | null;
  category: string;
  shortDescription: string | null;
  allowedWalletTypes: string[];
  allowedExecutionModes: ("manual" | "auto")[];
  totalSessions: number;
  userSessions: number;
  totalRuns: number;
  totalTransactions: number;
  networks: string[];
  tokensTraded: Array<{
    network: string;
    type: string;
    address: string | null;
    tokenId: string | null;
    imageUrl: string | null;
  }>;
  tvlUsd: number;
  volumeUsd: number;
  roi7dPercent: number | null;
  roi30dPercent: number | null;
  roi1yrPercent: number | null;
  roiInceptionPercent: number | null;
}>

Empty Agents

[]

Unauthorized

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Get Agent Details

Retrieve detailed information about a specific agent. Endpoint: GET /agents/:id Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

Path Parameter	Description
`id`	An agent ID from `GET /agents` response

cURL Example

curl -X GET "https://api.circuit.org/v1/agents/1"    -H "Authorization: Bearer api_auth_token"

Response

Agent Details

{
  id: number;
  name: string;
  description: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy: {
    id: number;
    username: string;
  };
  imageUrl: string | null;
  shortDescription: string | null;
  allowedWalletTypes: string[];
  allowedExecutionModes: ("manual" | "auto")[];
  defaultSleepIntervalMinutes: number;
  defaultScheduleAlignment: "rolling" | "fixed";
  agentVersion: string | null;
  sdkVersion: string | null;
  totalSessions: number;
  totalRuns: number;
  distinctUsers: number;
  totalTransactions: number;
  networks: string[];
  tokensTraded: Array<{
    network: string;
    type: string;
    address: string | null;
    tokenId: string | null;
    imageUrl: string | null;
  }>;
  tvlUsd: number;
  volumeUsd: number;
  roi7dPercent: number | null;
  roi30dPercent: number | null;
  roi1yrPercent: number | null;
  roiInceptionPercent: number | null;
}

Invalid Agent ID

{
  error: string;
}

Unauthorized

{
  error: string;
}

Agent Not Found

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Get Agent Historical Stats

This REST endpoint is not currently available. Historical stats are accessible via the tRPC API. This section is provided for reference and will be updated when the REST endpoint is enabled.

Retrieve performance statistics for an agent. Endpoint: GET /agents/:id/historical-stats Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

Path Parameter	Description
`id`	An agent ID from `GET /agents` response

Query Parameter	Description
`format`	Time format - “day”, “week”, “month”, “year” (defaults to “day”)

cURL Example

# Default format (day)
curl -X GET "https://api.circuit.org/v1/agents/1/historical-stats?format=week"    -H "Authorization: Bearer api_auth_token"

Response

Success

{
  id: number;
  totalPeriodWeightedRoi: number | null;
  transactions: Array<{
    timestamp: string;
    count: number;
  }>;
  roi: Array<{
    timestamp: string;
    weightedAvgHourlyReturn: number | null;
  }>;
  tvl: Array<{
    timestamp: string;
    totalTvlUsd: number;
  }>;
}

Format Options

day: 24 hourly data points (last 24 hours)
week: 7 daily data points (last 7 days)
month: 30 daily data points (last 30 days)
year: 365 daily data points (last 365 days)

Invalid Parameter

{
  error: string;
}

Unauthorized

{
  error: string;
}

Not Found

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Start Agent Session

Begin running an agent on a specific wallet. Endpoint: POST /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. Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

Body	Description
`agentId: number`	An agent ID from `GET /agents` response
`walletId: number`	User’s Wallet ID from `GET /wallets` response
`masterKey: string`	Fresh passkey-derived wallet-manager authority for this hosted-session start
`allocation: object`	See below
`mode: "auto" \| "manual"`	Optional execution mode. Defaults to `"auto"` if omitted.

allocation Object Properties

Property	Type	Required	Description
`network`	`string`	true	Network identifier (for example, `"ethereum:1"` or `"solana"`)
`address`	`string`	true	Token contract address. For native EVM tokens use `"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"`; for native SOL use `"11111111111111111111111111111111"`.
`tokenId`	`string \| null`	false	Token ID for NFTs of multi-token contracts. Use `null` for fungible tokens (default: `null`)
`amount`	`string`	true	Maximum amount to allocate in smallest unit (wei for Ethereum, lamports for Solana)

cURL Example

curl -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,
    "masterKey": "passkey_derived_master_key",
    "mode": "auto",
    "allocation": {
      "network": "ethereum:1",
      "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "tokenId": null,
      "amount": "100000000000000"
    }
  }'

Response

Success Start

{
  sessionId: number;
}

Bad Request

{
  error: string;
}

Unauthorized

{
  error: string;
}

Agent / Wallet Not Found

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Stop Agent Session

Stop a running agent session. Endpoint: DELETE /agents/stop/:sessionId Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

Path Parameter	Description
`sessionId`	Session ID from `POST /agents/start` response

cURL Example

curl -X DELETE "https://api.circuit.org/v1/agents/stop/789"    -H "Authorization: Bearer api_auth_token"

Response

Success

{
  success: boolean;
}

Invalid Session ID

{
  error: string;
}

Unauthorized

{
  error: string;
}

Session Not Found

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Get Agent Logs

Retrieve execution logs for a specific agent session. Endpoint: GET /agents/logs/:sessionId Request

Header	Description
`Authorization: Bearer {token}`	User’s API auth token acquired from authentication

Path Parameter	Description
`sessionId`	Session ID from `POST /agents/start` response

cURL Example

curl -X GET "https://api.circuit.org/v1/agents/logs/789"    -H "Authorization: Bearer api_auth_token"

Response

Returns Logs

Array<{
  id: number;
  sessionId: number;
  type: string;
  message: string;
  createdAt: string;
}>

Empty Logs

[]

Invalid Session ID

{
  error: string;
}

Unauthorized

{
  error: string;
}

Internal Server Error

{
  error: string;
}

Documentation Index

​List Available Agents

​Get Agent Details

​Get Agent Historical Stats

​Start Agent Session

​Stop Agent Session

​Get Agent Logs

List Available Agents

Get Agent Details

Get Agent Historical Stats

Start Agent Session

Stop Agent Session

Get Agent Logs