Skip to main content
The circuit operations namespace drives Circuit’s reviewed-operation surface headlessly: you submit a structured intent, the server quotes it and captures a reviewed operation, and nothing moves until you approve it. Creation never moves money - approval is the only step that admits an operation for execution. All commands need a signed-in session (circuit auth login, details) or CIRCUIT_TOKEN captured via circuit auth token. --env selects the target deployment as usual.

​
Create Operation

Reads a structured operation intent (JSON) from the file, or from stdin with --file -. The CLI validates the intent against the strict wire schema before anything leaves your machine, so a malformed file fails loudly with no network round trip. Do not put an idempotencyKey in the file - the CLI rejects one. It mints the key itself and retains it until the server’s durable answer arrives, so a retried create rejoins the same operation instead of minting a duplicate. A swap intent (tokens are contract addresses; null means the network’s native asset; quoteFloor is the reviewed worst case in base units):
A send intent (the recipient is an owned wallet id or a pasted address; "max" resolves from the live balance at approval, never a client snapshot):
perp and prediction intents follow the same shape: { "kind": "perp", "walletId": …, "perpIntent": … } and { "kind": "prediction", "walletId": …, "order": … }. Text output prints id, kind, state, and one line per reviewed action label - the exact actions the operation will execute once approved. With --wait, it prints the terminal state rather than the earlier working state. --json prints the captured resource under operation and the settled resource under terminal. If automatic approval fails after creation, the error document still includes operation, so its ID is never lost.

​
Approve Operation

Admits an operation that is awaiting approval. This is the step that moves money. --wait polls until the operation settles. If the approval request fails, the CLI re-reads the canonical resource. When the operation remains awaitingApproval, the CLI exits nonzero with OPERATION_APPROVAL_PENDING; retry circuit operations approve <operation-id> for the same operation. A dismissed or canceled operation returns its terminal resource and fails instead of claiming that approval succeeded.

​
Get Operation

One current-state read of the canonical resource. Same output shape as create. A read never maps the operation’s state to the exit code - only a --wait settlement does that.

​
Discard Operation

Dismisses an operation before admission. A discarded operation never moved money and never will.

​
Waiting and exit codes

--wait (on create --approve and approve) polls the action sequence until it settles. Only done exits 0. dismissed, canceled, failed, and failed_before_effect exit nonzero; failure states print the operation’s stored error in full (failed_before_effect proves nothing moved). Under --json the settled resource is included under terminal even when the command exits nonzero, so scripts can inspect the failure without a second read.