Operations and Lifecycle#

Agent API write routes create an AgentOperation. The operation is the audit and tracking object for money-moving work.

Write Response#

Write responses return after broadcast with the current operation status.

jsonexample

{
  "ok": true,
  "operation_id": "00000000-0000-0000-0000-000000000000",
  "status": "submitted",
  "resource": {
    "type": "payment",
    "id": "00000000-0000-0000-0000-000000000000"
  },
  "fee_usd": "0"
}

Some responses may include additional fields such as human_message, policy_evaluation, repay_amount_usd, or estimated_ltv_after.

Waiting for Final State#

?wait=executed is not supported in Agent API v1.

Use one of these:

Poll GET /v1/agent/operations/{id}.
Subscribe to webhooks.
Use MCP notifications or the MCP agent_operations_wait_for_status tool.

Terminal statuses:

executed
execution_failed
policy_rejected
cancelled

Non-terminal statuses:

accepted
submitted

Any non-terminal status means the operation is still in flight. cancelled is reserved in the schema but is not reachable through Agent API v1 routes. Agents cannot cancel operations in v1; operation_not_cancellable exists in the error contract for cancellation attempts, but no public cancel route is currently exposed.

Onchain Details#

Operation-backed detail endpoints support:

textexample

?include=onchain

The optional onchain block can include:

chain_id
wallet_address
manager_address
agent_wrapper_address
agent_sender_address
tx_hash
user_operation_hash
bundler_hash
raw_destination_address
tx_calldata

Example:

jsonexample

{
  "ok": true,
  "operation": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "executed",
    "onchain": {
      "chain_id": 8453,
      "wallet_address": "0x...",
      "manager_address": "0x...",
      "agent_wrapper_address": "0x...",
      "agent_sender_address": "0x...",
      "tx_hash": "0x..."
    }
  }
}

Idempotency Hashes#

Operation read responses include idempotency_key_hash, a lowercase SHA-256 hex string for the accepted Idempotency-Key header, or null when the operation has no key or only a legacy raw-key value.

Raw idempotency keys are never exposed in read responses.

Finalization Effects#

For supported final statuses, Hightop:

updates the operation
creates wallet-owner Activity
sends owner-facing notifications according to the owner's notification settings
persists supported Agent API webhook events for delivery

Activity and Agent API webhooks are the reliable audit and delivery paths even when external owner notifications are disabled.

Account Deletion#

AgentOperation records are retained as audit history. On account deletion:

retained operation summaries are redacted
quotes are removed
idempotency rows are removed
rate-limit counters are removed
webhook endpoints are removed
webhook events are removed
webhook deliveries are removed