API essentials

Events

The journal and the stream carry one shape. On the stream, id is the journal seq, event is the type below, and data is a { delivery, seq, payload } frame; resume with Last-Event-ID or ?cursor=.

  • run.started — Opens a new run: the engine admitted it and is about to process the input, whether an ordinary turn or an automation firing. Emitted once, at admission — a run resumed after an approval does not get a second one. run.ended closes what this event opened.
  • run.ended — The root run reached a terminal state: completed, failed or aborted. Its runId is the same as run.started and every pause/resume. Waiting for approval emits run.paused instead. Accounting includes all continuation segments.
  • run.paused — The run is waiting for human input or approval. Its identity and original request remain unchanged.
  • run.resumed — An approval decision resumed the same root run. No new instruction or run identity was created.
  • run.steered — The agent read a message the user sent while the run was working (Steer a run). Emitted at the agent's next step, before its next reply, so it lands in the conversation where the agent saw it; steerId matches the run's steers entry. Several messages sent within one step each get their own event, in the order sent. The same run continues; a message the run ended before reading never gets one.
  • agent.entry — One durable message in the conversation: the user's message, the assistant's completed reply, or a tool's display text once it resolves. Streaming assistant text arrives first as agent.text_delta and lands here only when the turn completes.
  • agent.text_delta — A chunk of the assistant's reply while it is still generating. Delivered live only — never written to the durable journal or replayed on reconnect — and superseded by the complete text in the agent.entry that follows.
  • tool.call — The assistant asked to call a tool. Emitted once the call is committed to the conversation, before it runs; approval.opened follows if a human must decide first, otherwise the call proceeds straight to tool.result.
  • tool.result — One tool call resolved: outcome says what happened (completed, denied, parked for approval, or failed). Immediately followed by an agent.entry (role tool) carrying that outcome's own display text.
  • approval.opened — A tool call is parked, waiting on a human decision. Carries the terms the approval card renders: the call's input, a summary, and the authorization contract in effect, if any. approval.decided or approval.expired closes it.
  • approval.decided — The user, or a partner integration, approved or denied a parked approval. approve says which way; a denial may carry reason. Consuming the decision to execute the tool follows as approval.consumed, but only when the decision was an approval — a denial never reaches consumption.
  • question.opened — A questionnaire is waiting for the user. Its full content is durable and replayable.
  • question.answered — The user answered or skipped a questionnaire; its accepted result is durable.
  • question.closed — A pending questionnaire expired or was cancelled.
  • approval.consumed — The approval was spent to authorize its tool call, immediately before that call runs. This is when the call is authorized, not when it finishes: the call can still fail after this event lands, and nothing here rolls it back. Marks the approval used; it cannot authorize a second execution.
  • approval.expired — A parked approval lapsed before anyone decided: its deadline passed, or the run it belongs to stopped while it was still pending.
  • automation.fired — An automation triggered this conversation's run. Emitted once, immediately before the run.started it precedes, naming the automation and its name at fire time.
  • intents.settlement — A later, independently verified financial fact about one leg of an authorized swap — settled, refunded, or never executed — never inferred from the model's own tool result. Appended whenever the provider confirms the outcome, independent of the run that requested it; legId and operationId join it back to its financial request, progress and authorizing approval. Archived receipts retain their original occurrenceId.
  • intents.progress — Best-effort, display-only progress for an authorized swap, between approval and its settlement receipt: freezing the plan (planning), the frozen legs (planned), then each leg's own stage (stage). Never gates execution and may arrive out of order or not at all; an intents.settlement receipt always takes precedence, and a terminal outcome is never reported here.
  • perps.reconciled — A later, independently verified answer to an approved perps order, cancellation or withdrawal whose own tool.result was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; callId joins it to that call's tool.result, approvalId to its approval, and operationId to its financial request. result has the shape the tool itself returns; show it in place of the call's earlier unconfirmed result.
  • prediction.funding — Recovery's latest view of an approved prediction_fund call, appended whenever it changes, independent of the run that made the call: the first leg's verified 1Click outcome (native Base USDC delivered to Polymarket's bridge, refunded, or not executed) and every transaction the bridge reports at the pinned deposit address, each COMPLETED one checked against its canonical Polygon receipt. Delivery to the bridge is not pUSD funding, a bridge FAILED is not a refund, and attribution of any bridge transaction to this funding stays unknown. callId joins it to that call's tool.result; show the latest in place of it.
  • prediction.withdrawal — Recovery's latest view of an attempted owner-approved pUSD withdrawal, independent of the run: its outgoing Polygon transfer receipt, what the bridge reports, and arrival at the unique linked 1Click deposit address. Only that deposit's own receipt establishes a credit or refund into the agent's confidential Intents wallet. A bridge status alone is not a receipt. Replace the original tool result by callId; recovery never signs or resends.
  • composite.progress — Best-effort display snapshot of an approved basket's pieces (composite_execute), appended after a piece changes state: each piece todo, live, done, bad or skip. Revision orders snapshots for the same call; ignore an older one. The call's own tool.result is the authoritative outcome of every piece, and each piece's own venue events keep their meaning; progress grants no execution permission.
  • solana.progress — Best-effort display snapshot derived from committed Solana funding, swap or sweep facts. Revision orders snapshots; repeated unchanged observations are omitted. A confirmed funding phase is only delivered SOL, and a confirmed swap phase does not establish sweep settlement. Final tool outcomes and solana.reconciled remain authoritative; progress grants no execution permission.
  • solana.reconciled — A later, independently verified answer to an approved Solana buy, sell or withdrawal whose own tool.result was left unconfirmed — never inferred from the model's own tool result. Appended once, by recovery, in the same commit that records the request's final outcome, independent of the run that made the call; callId joins it to that call's tool.result, approvalId to its approval, and operationId to its financial request. result has the shape the tool itself returns, with its solana detail; show it in place of the call's earlier unconfirmed result.
  • prediction.order — The latest observation of a Polymarket order. Replace the original placement call's result, joined by callId, with result. A match is not settlement; cancellation stops only the unmatched part and does not reverse earlier fills. Observations can arrive after the run ends.
Fin documentation Built from the API contract · v1

Search all documentation