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 | Load history, catch up, or poll | Oldest first |
| Stream a conversation's events | 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.
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
: 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), 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 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) | 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 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. For question.opened, read Get a question 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). approval.decided records an approval decision. For an audit trail, read the approval itself (Get an approval): 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): 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 (filter by runId or conversationId) or Get a 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.
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 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.
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.
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 lists every event.