Events & errors

A presence acts between requests. The stream is how you hear it — and how you answer when it asks.

GET/v1/events

An SSE stream of everything the presence does without you asking: replies from standing intents, on-chain actions, memory pins, and confirmations it is waiting on. If you build anything autonomous, you live here.

Event types

Event	Payload	Means
message	{ text, cause }	The presence spoke unprompted — usually an intent firing. cause names which.
tx	{ hash, block, intent }	An action executed within policy. The receipt.
memory	{ key, tier }	A keyword pinned, updated, or dropped by the compactor.
needs_confirm	{ confirm_id, summary, amount }	An action is prepared and held above your threshold. Awaiting your yes.

sse

event: needs_confirm
data: { "confirm_id": "cf_9b2…",
      "summary": "swap 0.08 ETH → USDC",
      "amount": "0.08 ETH" }

Resolving a confirmation

POST/v1/confirm/{confirm_id}

This is the only correct way to answer a held action — never by retrying the message or intent. The presence resumes from exactly where it paused, plan and context intact.

http

POST /v1/confirm/cf_9b2…
{ "approve": true }

# → a tx event follows on the stream

Confirmations expire. An unanswered needs_confirmtimes out and the action is dropped, not executed — silence is "no". The timeout is part of the held event.

Reconnecting

Send Last-Event-ID to resume without a gap; buffered events replay in order. Treat every handler as idempotent on the event id — at-least-once delivery means a duplicate is possible across a reconnect.

The error model

Conventional status codes; bodies are application/problem+json with a stable type you can branch on.

Status	type	Meaning
400	invalid_request	Malformed body or parameters. Don't retry unchanged.
401 / 403	auth / scope	Bad key, or missing scope — see Authentication.
409	policy_block	The action hit a policy deny or cap. Not retryable without a policy change.
429	rate_limited	Back off per the Retry-After header. Per-key, sliding window.
5xx	internal	Safe to retry with the same Idempotency-Key — actions never double-execute.

problem+json

{
  "type": "policy_block",
  "title": "over per_tx_cap",
  "detail": "0.08 ETH exceeds per_tx_cap 0.05 ETH",
  "status": 409
}

A 409 policy_block is the system working, not failing — the presence tried something you fenced off. Widen the policy only if you mean to.