Messages

Send one message. The presence already has the thread — you never resend history.

POST/v1/messages

One user turn in, the presence's reply out. The server-side thread, recalled memory, and preferences are assembled for you — see How it works.

Request

Field	Type	Notes
textrequired	string	The user message. Plain text.
stream	boolean	If true, responds as SSE token events. Default false.
allow_act	boolean	Permit on-chain action this turn. Still gated by the policy. Default false.

http

POST /v1/messages
{ "text": "how's the ETH/USDC pool?" }

Response

A reply, plus what the presence did to produce it. Tool and chain calls happen server-side; you see the trace, not the plumbing.

json

{
  "reply": "Deep — ~$48M a side, calm today.",
  "used": [{ "tool": "chain.pools", "pair": "ETH-USDC" }],
  "memory": { "touched": ["pool:eth-usdc"] },
  "acted": false
}

Streaming

With ?stream=true the response is an SSE stream. Event types, in order:

Event	Payload	Notes
token	{ text }	Incremental reply text. Many of these.
tool	{ name, args }	The presence used the chain skill or its space. Informational.
needs_confirm	{ confirm_id }	An action crossed `confirm_over`. Resolve via events.
done	{ reply, used, acted }	Terminal. Same shape as the non-streamed body.

sse

event: token
data: { "text": "Deep — " }

event: tool
data: { "name": "chain.pools" }

event: done
data: { "reply": "Deep — …", "acted": false }

When it acts

With allow_act: true, a reply may include an on-chain action. Two terminal shapes:

acted — { "acted": true, "tx": "0x…" }. Done, within policy.
needs_confirm — { "confirm_id": "cf_…" }. Over the line; resolve it, don't retry the message.

A retried POST /v1/messages with the same Idempotency-Key returns the original result — it does not act twice. Confirmations are resolved on the events stream, covered next.