Account Operations

Account operations create and execute one human-reviewed financial intent without chat. Typed and raw actions use the selected wallet or venue account regardless of agent attribution. Authenticate with a passkey-signed bearer token.

Create validates live facts and stores one inert reviewed action without moving money.
Approve admits that action and returns its three-state resource. Engine actions execute synchronously within a 30-second lifecycle deadline.

Transcribe Terminal dictation

POST /v1/assistant/transcription takes no body and returns { token: string }, an OpenAI token valid for establishing a connection within 60 seconds. Authenticate with an account-write permit; support view is read-only. Admission is limited to ten per user per minute. Never store or log tokens. The server selects the transcription model, context and semantic endpointing. Connect to OpenAI’s Realtime WebSocket with intent=transcription and stream 24 kHz PCM. Match final transcripts to committed item IDs. The web recorder allows two seconds after an endpoint for continued speech, then returns editable text. Done finishes immediately; only Send creates a Turn. Circuit stores no audio. Web capture is capped at two minutes, connection/finalization at 60 seconds each.

Create Operation

Endpoint: POST /v1/operations

Body	Type	Required	Description
`idempotencyKey`	string	true	Stable identity for this creation request. An identical repeat returns the original operation; changed input returns `409`.
`operation`	object	true	One structured financial intent.

Every intent includes walletId. Asset sides are { network, asset }. Amounts accept an exact decimal, "max", { percentOfBalance }, or { valueUsd }.

`kind`	Required intent
`swap`	`swapIntent: { from, to, amount, slippage?, providers?, toWalletId? }`. `providers`, when supplied, is nonempty; see supported providers.
`send`	`sendIntent: { from, amount, to: { walletId } \| { address } }`.
`perp`	`perpIntent` names `asset`, `reduceOnly`, `size` or `valueUsdc`, and optional `slippage`. Opens also name `side: "long" \| "short"`; reductions infer closing side.
`spot`	`spotIntent: { asset, side: "buy" \| "sell", size, slippage? }` or `valueUsdc` sizing; selling supports `size: "max"`.
`predictionBuy`	`prediction: { asset, spendPusd }`.
`predictionSell`	`prediction: { asset, shares }`.
`predictionRedeem`	`prediction: { asset }`, an outcome token ID selecting its whole resolved market; redeems all YES and NO holdings for pUSD.
`transaction`	`description`, optional `sourceUrls`, and `action: { kind: "evmTx", evm: { chainId, toAddress, valueWei, data } }` or `{ kind: "solanaTx", solana: { hexTransaction } \| { instructions } }`.
`accountSetup`	`venue: "hyperliquid" \| "polymarket"`; prepare explicit account setup.

Decimal amounts and percentages accept trailing zeroes ("0.50", "1.0"); positive amounts reject zero, including "0.00". Signs, exponents, separators and leading zeroes remain invalid. Raw integer quantities remain canonical ("1", not "01" or "1.0"). asset identifies a contract, mint, canonical native token, Hyperliquid coin or prediction outcome. Prediction buys spend pUSD, sells spend shares, and redemption rechecks the selected outcome’s positive redeemable holdings. EVM token casing normalizes; recipient checksum rules still apply and Solana mints are case-sensitive. Optional source URLs are provenance, never authorization. EVM calls supply complete parameters. Solana instructions name programAddress, ordered accounts (address, isSigner, isWritable) and ordered data parts: unsigned integer with 1/2/4/8/16 bytes, or address/utf8/hex/anchor with value. The engine supplies an initial blockhash for instruction intent; supplied transaction bytes remain unchanged and need a recent blockhash. Expiry requires fresh preparation and approval. Reductions omit side, optionally pin expectedSide, and resolve size: "max" or sizePercent against live positions. Only whole-position closes may be below 10 quote units. Spot buys support valueUsdc: "max"; prediction sells support shares: "max". Perp opens may specify marginUsdc with exposureMultiple. Preparation resolves USD sizing through Circuit’s current price reader; callers supply no valuation. Missing or expired prices reject preparation. Approval executes the exact prepared token amount. Hyperliquid spot/perp slippage is a decimal percentage: omission or null defaults to "1" (1%); overrides must be at least 0 and below 100. It bounds deviation from the live midpoint, including spread and price impact. Review pins the venue-rounded limit (buys down, sells up); the 10 quote units minimum uses rounded size × limit price, with the whole-perp-close exception above. IOC orders may partially fill or remain unfilled; Circuit never widens the limit or resubmits automatically. The same intents work through circuit operations create --file intent.json. Swap amounts specify source spend. Review shows the quoted destination amount and slippage minimum; approval pins the exact input and minimum output. Swaps do not size the input to fill a destination shortfall. Agent Start checks the resulting available balance separately. For example, this request creates a Base ETH-to-USDC swap for review:

{
  "idempotencyKey": "checkout-swap-1",
  "operation": {
    "kind": "swap",
    "walletId": 456,
    "swapIntent": {
      "from": { "network": "ethereum:8453", "asset": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" },
      "to": { "network": "ethereum:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
      "amount": "0.5",
      "slippage": "2"
    }
  }
}

Creation returns id, kind, state: "pending", approvalRequired: true, typed receipts, walletId, request: { action, review? }, and nullable continuation: { action, label, display?, walletId, operation }. The action may be a prerequisite such as token approval. Render that action for confirmation and the continuation as a waiting transaction card without controls. Creation never submits it. continuation.operation is null until prepared, then contains the successor resource recursively, including its status and error. GET, conversation history and the web cards share this resource. Failed swaps eligible for quote refresh offer “Review updated quote.” After prerequisite success, the web prepares the next review and enables its separate confirmation.

Lifecycle endpoints

All routes below use the operation’s UUID and return its current resource unless noted.

Method and path	Behavior
`POST /v1/operations/{id}/approve`	Confirms the stored action using the bearer permit; send an empty JSON object. Admits only that operation and waits up to its own 30-second deadline. Re-approval returns `409`. A genuine atomic smart-wallet batch is one chain transaction; a venue order is one venue request.
`POST /v1/operations/{id}/next`	After prerequisite success, prepares the intended action preserving its constraints. A reviewed swap with optional `quoteRefresh: "changed"` or `"expired"` can also prepare a new review: amount, tokens, recipient, provider and slippage stay fixed, while the previous minimum is replaced by the fresh quote’s guaranteed minimum. The new review requires separate approval, even if its minimum is lower. Concurrent/repeated requests return the same successor. Preparation errors leave the continuation uncaptured for another request; a Polymarket collateral shortfall returns error code `POLYMARKET_FUNDING_REQUIRED`, and the web re-requests preparation on a poll until funding arrives. No submission occurs.
`GET /v1/operations/{id}`	Reads durable engine evidence and the full successor sequence. Pending swaps can recover observation within their original deadline, including receipts, movements and terminal verdict; recovery never signs or resubmits. Historical error fields remain unchanged. Use after response loss with the known UUID. `404` means absent or not owned.
`GET /v1/activity/operation-lifecycle?operationId={id}&historical={boolean}`	Returns one operation’s card through indexed activity using the same engine observation. Positions are real EVM blocks or Solana slots; poll once per second until `complete`. `historical=true` reads indexed history.
`POST /v1/operations/{id}/discard`	Ends an owned inert review as `error` with `OPERATION_DISMISSED`. It cannot cancel an admitted operation. Lifecycle cards show neutral `kind: "dismissed"`, `complete: true`.

approvalRequired appears only while pending. Each successor needs separate approval; failure never changes earlier success. The web shows the waiting successor card immediately and prepares it automatically after prerequisite success. Clients may call next explicitly; failed or pending prerequisites cannot advance. LIFECYCLE_TIMEOUT means Circuit did not prove success before the deadline; the external effect may still settle. Inspect receipts before deciding to create a new operation. Never retry automatically. SUBMISSION_REJECTED and SUBMISSION_UNCERTAIN retain their codes at expiry, with the deadline explanation and original provider detail.

Activity details

GET /v1/activity/feed?scope=global is public and returns user_joined, agent_started, agent_stopped, and circuit_transaction entries, newest first. Optional kinds filters these event kinds. Agent activity includes private, unpublished, disabled and community agents; manual wallet transactions made through Circuit also appear. External wallet activity and pending operations are excluded. Every entry includes actor.username; transactions use the operation owner’s username and wrap the activity item in activity. Agent lifecycle entries include agent, whose isLinkVisible indicates whether its page is publicly accessible. Feed visibility does not grant access to private agent pages. GET /v1/activity/feed returns the same activity items used by GET /v1/activity/operation?operationId={id} and indexed lifecycle cards. Each item includes action, title, networks, nullable route: { source, destination }, isSuccess, error, and reason. A null outcome means activity without an operation verdict or indexed receipt verdict, not pending or failed. Failed attempts without observed on-chain transactions are omitted from transaction feeds; agent logs retain their operation diagnostics. assetChanges preserves exact decimal-string amount, account walletAddress, asset identity, and nullable valuation. feeAmount is signed and already included in amount; never subtract it again. A null fee means the breakdown is unavailable. kind: "fee" identifies a fee-only movement. references includes known receipts and proven source/settlement links with a readable label and nullable explorer url; retain references without links, including known hashes without an observation index. Source/destination labels require directional evidence. Receipt-proven Kyber movements can complete partial indexed swaps; relayer-funded deliveries show “Swap received” without attributing relayer spending to the recipient. Deposit/withdrawal titles name the underlying token and recognized protocol or vault; redemption titles include share quantity, outcome and market. Balance observations use action: "balance_change" and title Balance changed. They show observed amounts and time, with empty references and null transactionHash, transactionUrl and isSuccess; they do not identify a transaction. Transaction entries from GET /v1/agents/logs carry this activity item in metadata, including title, error, asset walletAddress, and exact approvals.

Terminal investigation

POST /v1/assistant/turn accepts UUID conversationId/turnId and text. History comes from the saved conversation unless an ordered history of up to 100 owned Turn UUIDs is supplied. Optional workspaceId selects an owned agent in that conversation; it supplies context while research, trading and building remain available. Optional selection pins a starter, token, perp or exact prediction outcome. Money requests prepare reviews without execution; explicit selections remain binding. The decision is stored before preparation. Independent reviews prepare concurrently, preserving their order, failures and successful results. Terminal and Builder preserve submitted text as prompt; selected-instrument and conversation context is separate. Builder Turn records expose nullable handoffContext, an opaque model-context document, instead of a display-prompt override. Build requests admit a build and return { kind: "build", build }, where build contains turnId, workspaceId, status, response, error, startedAt and finishedAt. The Terminal Turn completes after admission while the build continues. Poll the Turn or GET /v1/assistant/conversation/:conversationId for its current outcome. The conversation endpoint returns ordered Terminal and build/publish entries, including older workspace conversations. A deleted draft produces build: null and an explicit failure. Build handoffs recorded before this contract change fail explicitly because they have no recorded build operation. The response is { state: "complete", id, result } or { state: "pending", id, deadlineAt, message, suggestions }. result contains kind, one cohesive message, suggestions, sources, nullable failure and stored latencyMs. A suggestion retains its typed intent with state pending, prepared (including operation), or failed (including code/message). Kinds are message, operation, rejected, build (conversation prompt) and agents (ordered actions); Build and reviewed agent actions require separate user actions. Send Accept: application/x-ndjson to receive newline-delimited snapshots of this same resource as the saved message and individual reviews become available, ending with the completed resource. Without that header, POST returns one JSON resource. Admission conflicts and authorization failures retain their HTTP status codes. Prediction suggestions specify the outcome asset, with spendPusd for buys or shares for sells; the server finds that asset through its own Polymarket event search rather than accepting a market description. Redemption uses one live redeemable outcome per Review, up to ten per Turn; the Review names market, outcome and shares. Remaining positions need another Turn. Research scope and assumptions are disclosed; unspecified “top” uses market cap, while explicit ranking criteria win. GET /v1/assistant/turn/:turnId observes and closes expired investigations. Repeating identical POST observes the admitted Turn; changed input conflicts. Disconnection/preparation failure does not discard reviews. POST /v1/assistant/turn/:turnId/cancel closes capture and discards unapproved reviews. All Turn endpoints require the user’s write permit. Review and approve each operation separately; follow a successful prerequisite’s continuation through the next endpoint.

​Transcribe Terminal dictation

​Create Operation

​Lifecycle endpoints

​Activity details

​Terminal investigation

Transcribe Terminal dictation

Create Operation

Lifecycle endpoints

Activity details

Terminal investigation