# Streaming & events

Everything that happens in a conversation is saved as an event, in order. You can read those
events as pages, or open a stream that replays them and then delivers new ones live.

## Pages or a stream

| Call | Use it to | Order |
| --- | --- | --- |
| [List a conversation's events](/api-reference/events/list) | Load history, catch up, or poll | Oldest first |
| [Stream a conversation's events](/api-reference/events/stream) | Show progress live | Saved events first, then live ones |

The list returns `data` and `nextCursor`. Pass `nextCursor` back as `cursor` until it is
`null`; more events can arrive later.

## Open the stream

Send both headers and `Accept: text/event-stream`. `cursor=0` replays everything; a higher
cursor replays only events after it.

```bash
curl --fail-with-body -sSN \
  "$FIN_BASE_URL/v1/users/$FIN_USER_ID/conversations/$FIN_CONVERSATION_ID/stream?cursor=0" \
  -H "X-Api-Key: $FIN_API_KEY" -H "Authorization: Bearer $FIN_TOKEN" \
  -H 'Accept: text/event-stream'
```

The browser's `EventSource` can't send these headers, so stream through your backend, which
keeps the key and token.

To show a conversation when it opens, read its history with the list and draw it once, then
open the stream with the last event's `seq` as `cursor`. Replayed from `cursor=0`, saved events
arrive a few at a time, and a view that draws each batch shows finished runs as if they were
still working.

## Saved and live events

```text
: connected

id: 42
event: run.started
data: {"delivery":"durable","seq":42,"payload":{"input":"Hello","runId":"…"}}

event: agent.text_delta
data: {"delivery":"live","payload":{"text":"Hello"}}
```

| `delivery` | Saved? | What to do |
| --- | --- | --- |
| `durable` | Yes. It has a `seq`, appears in history and replays on reconnect. | Apply it to your saved state. |
| `live` | No. No `seq`, never replayed. | Show it, then replace it. |

`agent.text_delta` carries the reply while the agent writes it. When the saved `agent.entry`
arrives, replace the temporary text with it. Lines starting with `:` are comments and
keep-alives; parse the SSE framing before reading `data` as JSON.

## Render a reply

An assistant `agent.entry` may carry `interrupted: true`: the model's response was cut off. Mark
that draft as interrupted while nothing follows it. When the same turn writes again after automatic
recovery the later words answer in full, so draw them in the draft's place and leave the draft out
of the final answer's Copy action. `transcriptEntries` and `threadTurns` do this, and also draw a
long reply once when a later reply of its turn says the same thing again with only reads between
them. The journal keeps every entry. The durable draft replaces its live deltas.

A reply's `text` is markdown that reads well as it is. If you render markdown, you can
draw more from it:

| The reply writes | What it means | You can show |
| --- | --- | --- |
| A table with an asset's symbol alone in the first column | Figures for several assets or periods | A table with each asset's logo |
| A signed figure: `+61.2%`, `−14.3%`, `+$18.08` | A change. Levels, rates and risk never carry a sign | Green for up, red for down, with the sign kept |
| A bold symbol: `**SUI**` | An asset the reply names | The asset's logo beside it |
| A link: `[DefiLlama](https://defillama.com/chain/Sui)` | The source of what the sentence says | The site's name and logo |
| A fenced block whose info string is `next` | Up to three replies the user could send next, one per line | A button per line that sends it as the user's next message |

The agent can ask for several tools in one step. Each `tool.call` carries `batch`: its `index`
among the calls asked for together and their `size` (1 for a call asked for alone). They arrive
together, in `index` order, and the agent reads every result before its next step, so you can draw
them as one group rather than as a chain. A call made before this field existed has none.

Up to four independent reads can run together. Their `tool.result` events arrive as
those reads finish, which can differ from the calls' `batch.index` order. Match each
result to its `callId`; keep `batch.index` for display order and `seq` for event replay.
One failed or stopped read does not erase another read's completed result. Actions,
approvals and questions wait for preceding reads, and no later inference starts until
the current batch has finished or the run has stopped.

The text never carries read times or a list of sources. Each `tool.result` names its
provider (`source` or `sources`) and when it read it (`fetchedAt`), so you can show
both, for example on a collapsed line in place of a card per tool. A `market_history`
result gives each asset a `trendUsdDecimal` list of up to 24 prices, oldest first, for
a trend line.

You can also draw trades, automations, the wallet, orders, saved contacts, grids and research reads from
the events and tool results themselves. Tell the agent which ones you draw with `context.renders` on each message
([Start a run](/api-reference/runs/start)), and it leaves those facts to you: a reply beside a
card is one line, not a restatement of the card. Without it the agent sums each one up in a
line or two, so an app that shows only text still has the facts.
Also send `context.country` from your server's edge geolocation with every message;
[Tokenized stocks](/concepts#tokenized-stocks) explains which countries can trade these assets
and the operator flag required for purchases. These assets can only be sold, never withdrawn or sent.

| `context.renders` | Draw it from | The reply leaves out |
| --- | --- | --- |
| `receipts` | `intents.settlement` events | What a trade spent and received |
| `automations` | `automation_create` results, and the automation itself ([Get an automation](/api-reference/automations/get)) | Its schedule or trigger, whether it may trade without asking, and when it ends |
| `balances` | `intents_balances` results | What the wallet holds and its worth |
| `orders` | `intents_orders` results | Each order's price, fill and expiry |
| `contacts` | `contacts_list` results with `status: "listed"` | Each contact's name, address and network |
| `research` | `market_sentiment`, `market_derivatives`, `market_news`, `market_screen`, `macro_series` and `protocol_fundamentals` results | Their readings: the crowd's mood, funding and positioning, headlines, the day's movers, macro figures and a protocol's fundamentals |
| `grids` | `grid_create` and `intents_grids` results | Each grid's levels, state, cycles and profit |

A `contacts_list` result holds only the contacts you sent as `context.contacts` with that
message. Skip a lookup made right before a payment's approval: the approval shows the address.

Add `placement` to `context.renders` when you draw a read's card only where the reply puts it,
instead of one card per read as each lands. The agent then writes each finding as soon as it has
it and puts a line such as `[card r7k2q]` right after the sentence the card backs, at most three a
turn; it says any figure from a read it doesn't place in words. The name is the read's call id
through `replyCardName` from `@nearai/financial-agents-react/model` (or `@fin/contracts`), so
`splitReplyCards(text)` splits a reply into its words and the names it places, and `threadTurns`
draws a whole turn that way. Without `placement` the agent writes no card lines, and
`MessageMarkdown` leaves any it finds out of the words it draws.

Add `show` instead when you draw a read's card where the agent's `show_cards` call stands, as
`threadTurns` does. A message that carries `show` offers the agent the `show_cards` tool (and
nothing else does: an automation's run, a partner's run and a message without `show` never see
it), and the agent writes no card lines. The call names up to three cards a turn by the same
names, with an optional `focus` (the token ids, mints or symbols that matter inside them), and its
result lists the names it `shown`. Only the result of a read that can draw a card carries a name. A
call that names any card the agent cannot show is refused whole and shows nothing, the cards it
could have shown included, with `unknown_card` (no completed result has that name), `no_card` (that
result draws no card), `over_limit` (more than three in the turn) or `focus_outside` (a focus entry
the named results do not contain). A reply whose last step holds only `show_cards` calls ends the
run there when every one was accepted or the turn has words, refused or not: the words before the
call are the answer, and the agent isn't asked again. Send `show` beside `placement` while
your app still draws card lines from older turns; `show` takes precedence.

Add `solana_sell_many` to `context.renders` when your app draws a multi-coin Solana sale's
approval card and its outcome (two to six coins sold under one approval, then one transfer back;
the `solana_sell_many` tool and `SolanaSellManyContract`). Only a run told so is offered that
tool, so an app that cannot show its card never meets its approval; without it the agent proposes
one `solana_sell` per coin.

Add `deposit` to `context.renders` when your app lets the user add money in place from a
`deposit_request` result. Only a run told so is offered that tool: the agent calls it when the agent
wallet cannot pay for what the user asked (a buy, swap, send, funding or basket buy) or holds
nothing yet, after one short sentence on what is missing, and then ends its turn. The result is
what the request lacks, every figure read by the server from the wallet, never the agent's own
arithmetic: `purpose` (the request in the user's words, one line without square brackets), `symbol`, `needed` (the whole amount),
`held` (what the wallet holds of it on every chain) and `short` (the gap, always above zero), with
an optional `smaller` (the same request at what the wallet already holds, for one button). It
moves nothing and opens no approval: the user deposits through your own flow. Draw it where the
call stands in the turn, as you would a saved rule: it asks something of the user. When the money
lands, send a message that says so and asks the agent to carry on with the request; it reads the
wallet again and proposes the request for approval as usual. Without `deposit` the agent says what
is missing in words.

Add `share` to `context.renders` when your app lets the user share an answer publicly. The agent
then ends an answer that reports what it read (a market, the news, odds, yields, a comparison) with
its share lines: a fenced block whose info string is `share` (`REPLY_SHARE_FENCE`), in the same
message as the answer, holding up to three lines a stranger can read with only the question beside
them. The first is the finding that answers the question (asked why something moved, the cause);
the others, what backs it with its figures, such as a market and its odds or a vault and its rate.
They never carry the user's own balances or amounts. `splitReplyNextSteps(text)` returns them as
`shareLines` and leaves them out of the `body`, so they never show in the reply; check them as you
would any model text before you post them. Without `share` the agent writes no such block.

Name only what you really draw: the agent trusts the list for that message alone, and an
approval is always yours to show whatever the list says.

A suggested next step only sends a message: anything it leads to that moves money still
arrives as `approval.opened`. Offer the steps of the latest reply only, while no run is
going. If you don't render them, drop the block. While a reply is still streaming, its
`next` block may be unfinished, so hide everything from its opening fence to the end.
Older replies may use none of these forms.

## Reconnect without missing anything

Remember the `seq` of the last saved event you applied. Reconnect with it in `Last-Event-ID`
(or `?cursor=`, which the header overrides). Ignore saved events you already have, by
conversation and `seq`. Live text never moves the cursor.

A stream can end at any time, and that is normal: when Fin replaces a server, it ends that
server's streams so they resume on another. Every stream opens with an SSE `retry:` field, the
number of milliseconds to wait before reconnecting; a browser `EventSource` honours it by itself,
and your own client should too. Reconnect the same way when the connection drops or a
reconnect answers `5xx`: with backoff and `Last-Event-ID`, never giving up after one failure. On
`429` wait for `Retry-After`. A stream needs a live session: when the session expires, create a
new one and reconnect. Streams count against their own limit.

## After reconnecting, read the resources

Events show what happened; resources show where things stand now. [Get a run](/api-reference/runs/get)
returns a run's status, reply, `pendingApprovals` and `pendingQuestions`, so you don't need
to rebuild them from events. For an `approval.opened` event, read
[Get an approval](/api-reference/approvals/get). For `question.opened`, read
[Get a question](/api-reference/questions/get) before enabling its answer controls.

## Approvals, questions and pauses

`run.paused` means the run is waiting for an approval or a questionnaire response;
`run.resumed` means it continued; `run.ended` is sent once, with the final status. When the
status is `failed`, `failure.code` says why, including which budget or spend limit had no room
for the run's next model request ([Budgets and limits](/concepts#budgets-and-limits)).
`approval.decided` records an approval decision. For an audit trail, read the approval itself
([Get an approval](/api-reference/approvals/get)): it keeps the action's `fingerprint` and, for an
approved money action, the wallet that signed it (`signedBy`).
`approval.consumed` means the approval was used to start the action, not that the
action succeeded: follow the run for the result.

`run.steered` marks where the agent read a message the user sent the working run
([Steer a run](/api-reference/runs/steer)): draw the user's message there, with its `steerId`
matching the run's `steers` entry. It arrives at the agent's next step, so it can follow tool
results that finished after the user sent it. A message sent while the run waited on an
approval arrives after that approval's `approval.decided` (a denial) and `run.resumed`; one the
run ended before reading never gets a `run.steered`.

`question.opened` contains the complete questionnaire and its deadline.
`question.answered` records the submitted answers, with none for a question the user skipped,
or a whole-card skip. `question.closed`
records expiry or cancellation. These are durable events: replay them on reconnect,
but use the question resource's current status and deadline to decide whether it can
still be answered. Question answers never authorize an action.

## Money events

Trade progress and settlement events are a signal to read the record again: the trade under
[List trades](/api-reference/wallets/list-trades) (filter by `runId` or `conversationId`) or
[Get a trade](/api-reference/wallets/get-trade). Direct wallet withdrawals, the user's own swaps
and limit orders have no conversation; read them directly. Venue chat withdrawals use their
original conversation's events below. See [Deposits, withdrawals and trades](/wallet-transfers).

A perps order, cancellation, margin change or withdrawal whose `tool.result` was unconfirmed
(Hyperliquid's or the provider's answer was lost) is resolved later by recovery, never sent again.
When the final answer is known, one `perps.reconciled` event arrives in the same conversation,
after that call's `tool.result` and usually after its run ended. Its `callId` names the call,
`approvalId` its approval and `tool` the tool (`perps_order_place`, `perps_order_cancel`,
`perps_margin_update` or `perps_withdraw`); `result` has the same shape the tool returns
(`applied` or `rejected` for a margin change). Show it in place of the call's
unconfirmed result, on the tool row and on its approval card. It is durable: replay it on
reconnect, and keep it over a `tool.result` for the same call that arrives after it.

A Polymarket funding has two stages, not one final swap receipt. A `prediction.funding` event
updates the approved call's first-leg result and the bridge observations, even after the run
ended. Its `callId` and `approvalId` identify the call and approval; `result` has the funding
tool's submitted-result shape. Replace that call's displayed outcome with the newest event
in journal order, and keep it over a later-arriving original `tool.result`. Replay these
updates on reconnect.

`delivered_to_bridge` means native Base USDC reached the bridge, not that pUSD funded
the account. The bridge's transactions are reported separately from `attribution`, as the
bridge reports them; their `txHash` is the bridge's own and names no Polygon transaction.
`credited` (with `creditRaw` and `transactionHash`, a Polygon transaction) means this funding's
pUSD arrived, reported only when Polygon shows exactly one finalized transfer of the delivered
amount out of the bridge address after the funding was signed, whose receipt credits the user's
Deposit Wallet; `unknown` names its `reason`. The funding call itself waits up to a minute for
that credit, so its result is usually `credited` already. Each event also carries
the wallet's live pUSD `balance`, which is the wallet's, not this funding's. Do not infer
completion from matching amounts, times or a balance change, or a refund from bridge `FAILED`.
See [Approve Polymarket funding](/wallet-transfers#approve-polymarket-funding) for consent
and estimated-output semantics.

A `prediction.withdrawal` event updates an approved Polymarket withdrawal's original
`callId` and `approvalId`; `result` has the tool's submitted-result shape with
`operationId`, `transfer`, `bridge` and `deposit` evidence. Apply the latest observation
in journal order, including after the run ends, replay it on reconnect and retain it
over a late original `tool.result`. Recovery only observes the original operation;
an uncertain transfer is never resent.
Only evidence changes append an event; a new polling timestamp alone does not.
Unsigned pre-key refusals remain refused rather than becoming submitted observations.
After a finalized source revert, or a confirmed source transfer and its linked final
deposit receipt, there are no further recovery polls for that withdrawal.

An outgoing pUSD receipt confirms only the source transfer. Bridge completion, matching
amounts/times and wallet balance changes do not attribute arrival. Only the retained
unique own-account deposit's final receipt does. Its arrival is the existing deposit
ledger credit, never a second credit from this event. The approved loss limit checked
the bridge estimate before transfer, not an on-chain or final-conversion minimum;
bridge liquidity can hold, fail or reduce delivery. See
[Approve Polymarket withdrawal](/wallet-transfers#approve-polymarket-withdrawal).

A running Solana request also emits best-effort `solana.progress` snapshots. Join them by
`operationId`, `approvalId` and the original `callId`; keep the highest `revision` for that
operation. `phase` is `funding`, `swap` or `sweep`, with `state` describing only that phase.
`preparing` and `prepared` precede dispatch, `submitting` and `pending` await confirmation,
`uncertain` retains an unresolved attempt, and `not_executed` or `failed` describes that
attempt rather than the entire request. Native attempts carry `transactionIndex`, which is
never an Intents plan leg index. A multi-coin sale's (`solana_sell_many`) swaps name instead the
`sale` they sell, its zero-based place in the approved `sells`, and its one sweep names neither.
A sweep's `delivering` means Solana confirmed its transfer
while 1Click delivery remains unconfirmed. `confirmed` funding means SOL arrived, not that
a purchase completed; a confirmed swap can still need a sweep. Once a single-coin sale's swap
lands, every later snapshot carries `paid`: what that swap sold, the same amount the final outcome reports as
`paid`. Show it in place of an estimate while the sale finishes; until then, what a share of a
holding sells is known only from a balance read before the approval. `refunded` funding or sweep
reports only that phase's refund. Use `intents.settlement` for funding receipt precedence,
and the final tool outcome or `solana.reconciled` for the operation's ending. Missing progress
means unknown progress, not failure or permission to retry. Replay snapshots like other
durable events, including after the model turn ends; observation uses no model inference.

A Solana buy, sale or withdrawal whose `tool.result` was unconfirmed (a transaction whose landing
was unknown, or a transfer back to the agent wallet that 1Click had not yet settled) is resolved the
same way: one `solana.reconciled` event arrives in the same conversation, after that call's
`tool.result`. It carries the same `callId`, `approvalId` and `operationId`, and a `result` in the shape the
tool returns: `settled`, `partial`, `refunded` or `not_executed`, with its `solana` detail (what was paid
and received, the SOL left in the account, and each transaction's signature, state and fee). Show it in
place of the call's unconfirmed result, exactly as for `perps.reconciled`. A funding (`solana_fund`, or the
funding step of a USDC buy) has no transaction of its own to reconcile: its late settlement arrives as an
`intents.settlement` event, like any other leg. See [Solana trades](/wallet-transfers#approve-solana-trades-and-transfers).

A `prediction.order` event updates the original Polymarket placement's `callId`,
`approvalId` and `operationId`, including after cancellation or after the run ends.
Replace its displayed result in journal order, as for funding. Open and partially
matched orders are not settled; `matched` still awaits settlement evidence.
A cancelled order can retain earlier fills whose settlement is not yet confirmed.
An uncertain placement is observed, never automatically placed again. A retained
owner cancellation request can be continued against that same order; this cannot
create or replace an order.

The [event catalog](/events) lists every event.
