List Available Agents
Get all agents available to the user.
Endpoint: GET /agents
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session token acquired from authentication |
curl -X GET "https://api.circuit.org/v1/agents" -H "Authorization: Bearer user_session_token"
Returns AgentsArray<{
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;
}>
Get Agent Details
Retrieve detailed information about a specific agent.
Endpoint: GET /agents/:id
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session token acquired from authentication |
| Path Parameter | Description |
|---|
id | An agent ID from GET /agents response |
curl -X GET "https://api.circuit.org/v1/agents/1" -H "Authorization: Bearer user_session_token"
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;
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;
}
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.
GET /agents/:id/historical-stats
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session 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”) |
# Default format (day)
curl -X GET "https://api.circuit.org/v1/agents/1/historical-stats?format=week" -H "Authorization: Bearer user_session_token"
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;
}>;
}
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)
Start Agent Session
Begin running an agent on a specific wallet.
Endpoint: POST /agents/start
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session 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 |
allocations: array | See below |
mode: "auto" | "manual" | Optional execution mode. Defaults to "auto" if omitted. |
allocations 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 -X POST "https://api.circuit.org/v1/agents/start" -H "Authorization: Bearer user_session_token" -H "Content-Type: application/json" -d '{
"agentId": 1,
"walletId": 456,
"mode": "auto",
"allocations": [
{
"network": "ethereum:1",
"address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"tokenId": null,
"amount": "100000000000000"
}
]
}'
Stop Agent Session
Stop a running agent session.
Endpoint: DELETE /agents/stop/:sessionId
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session token acquired from authentication |
| Path Parameter | Description |
|---|
sessionId | Session ID from POST /agents/start response |
curl -X DELETE "https://api.circuit.org/v1/agents/stop/789" -H "Authorization: Bearer user_session_token"
Get Agent Logs
Retrieve execution logs for a specific agent session.
Endpoint: GET /agents/logs/:sessionId
Request
| Header | Description |
|---|
Authorization: Bearer {token} | User’s session token acquired from authentication |
| Path Parameter | Description |
|---|
sessionId | Session ID from POST /agents/start response |
curl -X GET "https://api.circuit.org/v1/agents/logs/789" -H "Authorization: Bearer user_session_token"
Returns LogsArray<{
id: number;
sessionId: number;
type: string;
message: string;
createdAt: string;
}>
