Skip to main content
POST
Start an agent

Authorizations

Authorization
string
header
required

The permit the user approved for your app.

Headers

idempotency-key
string<uuid>

Optional. A UUID your app generates for this request. Send the same value when you retry, and Circuit returns the first result instead of acting twice. Reusing a key with different contents returns 409. Without a key, a retried request can act twice.

Body

application/json
agent
string
required

The agent to start, from GET /partner/agents.

Example:

"agt_0b3c9e2a-6d1f-4f7a-9c2e-5b8a1d4e7f60"

wallet
string | null

The wallet it should trade, from the account. Null runs it on paper money.

Example:

null

amount
string | null

How much of the agent's starting asset to give it, as a decimal string. Null lets Circuit pick its default amount.

Maximum string length: 80
Pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$
Example:

"100"

Response

OK

An agent running for the user on one wallet or on paper money.

id
string
required

The session's id, starting with ses_.

agent
string
required

The agent it runs, starting with agt_.

name
string
required

The agent's name.

status
required

The agent is running on its own schedule.

Allowed value: "running"
started_at
string<date-time>
required

When the session started.

wallet
string | null

The wallet it trades, starting with wal_. Null when it runs on paper money.

value_usd
string | null

The current value of what the session holds, in USD as a decimal string. Null until Circuit first values a new session, about a minute after it starts, or when a holding can't be priced.

pnl_usd
string | null

Profit or loss since the session started, in USD as a decimal string. Null when unknown.

error
string | null

What the user needs to do when status is needs_user. Null otherwise.