# Components reference

Every block `@nearai/financial-agents-react` exports. Most apps place only `FinEntry`, `MessageMarkdown` and
`NextSteps`, as the [React quickstart](/react-quickstart) does, and `FinEntry` places the rest.
Place a block yourself to lay out a conversation your own way, or to show a card elsewhere.

Every block takes Fin's data as props, reports what the user does through callbacks, and never
fetches.

> [!TIP]
> Each block's root carries `data-fin-part="<block>"` and takes `className`. A block with named
> parts also takes `classNames`, and each part carries `data-fin-part="<block>-<part>"`. See
> [Theming](/react-theming).

## Entries

### `FinEntry`

Draws one transcript entry that is Fin's: an activity line and its cards, a trade, a receipt, a
question, an approval with the automation it saved or the grid it started, or a run's ending. A
`user` or `assistant` message is yours, so it draws nothing for one.

| Prop | Type | Description |
| --- | --- | --- |
| `entry` | `TranscriptEntry` | The entry to draw, from `transcriptEntries(thread)`. |
| `thread` | `ThreadState` | The thread the entry came from. Links a call to its approval, trade and run. |
| `approvals` | `ApprovalHandlers` | What deciding an approval does. |
| `questions` | `QuestionHandlers` | What answering a question does. Without it, questions can't be answered. |
| `automations` | `Record<string, Automation>` | Automations as they are now, by id, for saved automations' cards. `automationIdsOf(thread.items)` names them. |
| `grids` | `GridHandlers` | What a grid card's Pause, Resume and Stop do, and grids as they are now, by id. Without it a grid's card draws the snapshot its tool returned, with no controls. |
| `feedback` | `FeedbackHandlers` | What a thumb on a reply does. Without it, no thumbs are drawn under a reply. |
| `questionVariant` | `QuestionCardVariant` | How a question's choices are drawn, as `QuestionCard`'s `variant` takes it. `list` unless you pass `cards`. |
| `loadPriceHistory` | `PriceHistoryLoader` | Loads another range for a `PriceCard`'s range tabs from your own market data. Without it a price card draws only the window the agent read. |
| `resultCards` | `OptInResultCard[]` | The result cards to draw beyond the ones every chat draws: `market` for a `market_history` read (`PriceCard` or `ComparisonCard`), `vaults` for an `earn_vaults` read (`VaultsCard`), `predictions` for the prediction-market reads (`PredictionsCard`, `PredictionMarketCard`, `PredictionPreviewCard`, `PredictionOrdersCard`), `solana` for the four Solana reads (`TokenCandidatesCard`, `MemecoinsCard`, `SolanaTokenCard`, `SolanaHoldingsCard`). None by default, so a chat that upgrades draws what it drew before: those reads show only their activity line. |
| `walletVariant` | `"list" \| "holdings"` | How a balance read is drawn: `list` (the default) draws `WalletCard`, `holdings` draws `HoldingsCard`. |
| `predictionVariant` | `"default" \| "visual"` | How Polymarket cards are drawn. `default` keeps the existing funding/order rendering and shows withdrawal's exact consent rows and risk. `visual` draws a `prediction_fund` approval as a Pays → Holds hero with its risk facts above the buttons and its progress as stages (sending, at the bridge, bridge reports completed, a bridge failure's recovery, the endings where nothing moved); `prediction_withdraw` as exact pUSD Pays → estimated USDC Holds, with its estimate-only loss limit, own Polygon route and always-visible risk notice; a `prediction_order_place` approval as a Pays → Holds hero (the most it pays, the shares it holds, the payout, the implied chance and the order's lifetime) with its risk facts above the buttons, its open, settling, cancelled and unconfirmed states as a matched meter with rows, a filled order as a receipt, and declined, expired or unreviewable approvals as stopped stages; `PredictionOrdersCard` as rows with a status badge; and the research cards as outcome bars, a yes/no split and a fill meter. |
| `onDraft` | `(message) => void` | Puts a message in your composer for the user to edit and send: a vault deposit, Polymarket order cancellation, a visual order card's Check again, or next order page. Without it, these draft buttons are not shown. |
| `onSend` | `(message, card: { runId }) => void` | Sends a message as the user's next one, as your composer would: a `TokenCandidatesCard`'s Use this one, an open `MemecoinsCard` row's Buy…, or the next move a partly done Solana buy or sale offers (`SolanaReceipt`). Each names its token by mint and moves nothing: the agent goes on, and anything that moves money waits for its approval. `card.runId` is the run that drew the card (`null` when the thread can't tell). Steer the message into that run only while that same run waits on a question: the run skips the question, and nothing answers it. Never answer a question with it. Otherwise send it, or queue it behind a run that works or waits on an approval, which a steer would decline. Without it, no such buttons. |
| `sendDisabled` | `boolean` | Holds the buttons that call `onSend`. Pass `true` from a click until the message reaches `thread` (the run it starts, or its steer), so a double click sends once, and while you can't take another message, such as when your queue is full. They hold while a run works as well. |
| `loadSolanaToken` | `SolanaTokenLoader` | Reads a token for a `MemecoinsCard` row the user opens: `chart({ mint, interval, signal })` answers Get a Solana token's chart, `token({ mint, signal })` (optional) Get a Solana token, for its holders. Without it an open row shows the figures the list read carried, its warnings and its actions. |
| `runSummary` | `boolean` | Draws `RunProgress` above the first approval of a run that proposed moving money while it works and, at its ending, its finished steps and a `RunReceipt` when two or more swaps settled. Off by default. |
| `approvalAside` | `(approval: ApprovalView) => ReactNode` | Your own content inside a pending approval's card, between its terms and its buttons (the card's `aside`), such as how the proposal would have done on past prices. Return `null` for none. None by default, so the card draws as it always has. |
| `automationTerms` | `"disclosure" \| "summary"` | `disclosure` (default) retains an automation approval's Review terms and Exact terms controls. `summary` keeps its canonical headline, trade rows, limits, exit notes and decisions while omitting both controls, the terms grid and mobile terms sheet. A Solana standing grant always retains Exact terms with its full signed definition. Stored input, authorization and signing are unchanged. Other approval types are unchanged. |
| `requestText` | `(text: string) => string` | Turns a run's first user message into the request its `RunProgress` and `RunReceipt` name, so framing your app added to that message, such as page context, stays out of the card's title. The message as sent by default. |
| `className` | `string` | Classes for the block it draws. |

| Entry | Draws |
| --- | --- |
| `activity` | `ActivityGroup`, then a card per result that draws one: `AutomationCard`, `WalletCard` (or `HoldingsCard`), `OrdersCard`, `ContactsCard`, `GridCard` (one per grid an `intents_grids` read returned, compact when there are several); with `resultCards`, a `PriceCard` (one asset) or `ComparisonCard` (several) for `market_history`, `VaultsCard` for `earn_vaults`, `PredictionsCard`, `PredictionMarketCard` and `PredictionPreviewCard` for `prediction_markets`, `prediction_market` and `prediction_preview`, and `TokenCandidatesCard`, `MemecoinsCard`, `SolanaTokenCard` and `SolanaHoldingsCard` for `solana_token_search`, `memecoins_top`, `solana_token` and `solana_account` |
| `item` of kind `tool` | `ToolCallCard`: a trade, through to its settlement |
| `item` of kind `settlement` | `SettlementReceipt` |
| `item` of kind `question` | `QuestionCard` |
| `item` of kind `approval` | With `runSummary`, `RunProgress` above a run's first approval while it works; then `ApprovalCard`, then the `AutomationCard` of the automation it saved, the `SolanaReceipt` of a Solana call whose outcome recorded what it did, or the `GridCard` of the grid `grid_create`, `grid_pause`, `grid_resume` or `grid_cancel` returned |
| `item` of kind `run` | With `runSummary`, a money run's `RunProgress` and, with two swaps settled or more, its `RunReceipt`; then `RunFooter`, with the user's thumbs under the reply when `feedback` is passed |
| `item` of kind `user` or `assistant` | Nothing: your messages |

`AutomationCard` also draws an `automations_archive` receipt: Archived, future
work disabled, retained history, and honest pending/confirmed remote contract
revocation. It warns that future exits stop without selling a position or
undoing submitted transactions. An archive receipt outranks stale pre-archive
automation props. Archiving opens no approval, so the receipt is the only card it draws. The
same `automations` map refreshes management detail after reload; no additional route or SDK
method is needed.


`ApprovalHandlers` are `{ decidingId, conflicts, onDecide, onDismissConflict, onProposeAgain?, onReviewRemaining?, remainingReviewStates?, remainingReviewErrors?, holdings?, vaultRates?, predictionBalance? }`:

| Field | Type | Description |
| --- | --- | --- |
| `decidingId` | `string \| null` | The approval being decided now; its card shows the decision in progress. |
| `conflicts` | `Record<string, string>` | Fin's refusals by approval id, until dismissed. |
| `onDecide` | `(approvalId, approve) => void` | The user approved (`true`) or denied (`false`). Call `approvals.approve` or `approvals.deny`. |
| `onDismissConflict` | `(approvalId) => void` | The user dismissed a refusal. |
| `onProposeAgain` | `(approval) => void` | The user pressed an expired card's Propose again. Send the agent a message asking for it again, such as one naming `approvalContent(approval).headline`; it proposes afresh at current prices. Without it the expired card offers no button. |
| `onReviewRemaining` | `(operationId, options?) => void` | Prepare a fresh review of proven unclaimed actions. `options` may select `originalIndices` and an explicit higher `maxValueLossBps`; pass it as the third argument to `wallets.prepareRemainingTrade(operationId, {}, options)`. The server rechecks claims and ownership before creating new signed terms. |
| `remainingReviewStates` | `Record<string, "preparing" \| "opened">` | Review status by operation id, disabling the button while pending or accepted. |
| `remainingReviewErrors` | `Record<string, string>` | Review refusals by operation id. |
| `holdings` | `PricedHolding[]` | The agent wallet's priced holdings, to value a contract's terms today. |
| `vaultRates` | `VaultRate[]` | The curated vaults' current rates (`{ assetId, rate }`, an entry of the Earn vaults route's `vaults`), so a deposit into a vault states its yield. |
| `predictionBalance` | `{ pusd, readAt } \| null` | The live pUSD balance of the agent's own Polymarket deposit wallet, from Get the Polymarket account's observed `balance` (`pusd`, and `observedAt` as `readAt`). With `predictionVariant="visual"`, a funding whose bridge reports completed leads with it when it was read after that report, as the wallet's balance and never as this funding's credit. |

`QuestionHandlers` are `{ busyQuestionId, errors, onAnswer, onDismissError }`:

| Field | Type | Description |
| --- | --- | --- |
| `busyQuestionId` | `string \| null` | The question being answered now. |
| `errors` | `Record<string, string>` | Fin's refusals by question id, until dismissed. |
| `onAnswer` | `(questionId, answer) => void` | The user answered or skipped. Call `questions.answer` with it. |
| `onDismissError` | `(questionId) => void` | The user dismissed a refusal. |

`GridHandlers` are `{ current?, busy?, onPause?, onResume?, onCancel? }`. A control is drawn only
when you pass its handler:

| Field | Type | Description |
| --- | --- | --- |
| `current` | `Record<string, Grid>` | Grids as they are now, by id: a card draws whichever of this and its tool's snapshot is newer (`updatedAt`). `gridIdsOf(thread.items)` names them; refetch with `wallets.getGrid`. |
| `busy` | `{ gridId, action } \| null` | The control being sent now (`action` is a `GridAction`: `pause`, `resume` or `cancel`); its button waits and the card's others hold. |
| `onPause` | `(gridId) => void` | The user pressed Pause on a running grid. Call `wallets.pauseGrid`. |
| `onResume` | `(gridId) => void` | The user pressed Resume on a paused grid. Call `wallets.resumeGrid`. |
| `onCancel` | `(gridId) => void` | The user pressed Stop. Confirm first if your app asks, then call `wallets.cancelGrid`. |

`FeedbackHandlers` are `{ ratings, busyRunIds, errors, onRate, tooltip? }`:

| Field | Type | Description |
| --- | --- | --- |
| `ratings` | `Record<string, RunRating \| null>` | The user's feedback on each run by id, as Fin returned it (the run's `feedback`). A run that is missing or `null` has none. |
| `busyRunIds` | `readonly string[]` | The runs whose feedback is being saved now; each one's thumbs hold until it lands, and the others stay free. |
| `errors` | `Record<string, string>` | Fin's refusals by run id, in words, shown beside that run's thumbs until the next tap. |
| `onRate` | `(runId, feedback) => void` | The user sent, changed or deleted feedback. Call `runs.sendFeedback` with it, or `runs.deleteFeedback` when `feedback` is `null`. |
| `tooltip` | `ControlTooltip` | Wraps each icon-only control under a reply (the thumbs, the reasons' Skip) in your own tooltip. Without it they draw as they always have. |

Build `holdings` from the wallet's balances. Fin names held assets by opaque `assetId`s and
contracts name tokens by id, so map each through `catalogTokenId`:

```ts
import { catalogTokenId, type PricedHolding } from "@nearai/financial-agents-react/model";

const holdings = balances.assets.flatMap((asset): PricedHolding[] => {
  const tokenId = catalogTokenId(asset.assetId);
  return tokenId
    ? [{ tokenId, decimals: asset.decimals, amountRaw: asset.amountRaw, priceUsdDecimal: asset.priceUsdDecimal }]
    : [];
});
```

## Replies

### `MessageMarkdown`

The agent's reply in your product's prose, drawn richer where its text says so: signed changes
coloured (`+4.2%` green, `-1.3%` red), tables as panels with figures aligned, linked sources as
chips with the provider's logo, and bolded assets with their icon and trend line. With
`routes.asset` set, a ticker in the reply links to your page for the token: only one spelled
exactly as the thread or the token list spells it (`NEAR`, never "near the price"), and never
inside code or a link. It leaves out the suggested next steps, which you offer with `NextSteps`, the
share lines Fin writes for an app that shares answers (`splitReplyNextSteps(text).shareLines`), and
any line that places a card (`[card r7k2q]`), which you draw where `threadTurns` puts it.

| Prop | Type | Description |
| --- | --- | --- |
| `text` | `string` | The reply as Fin wrote it, next steps included. |
| `streaming` | `boolean` | Live text: draws the caret after the last line. |
| `size` | `"sm" \| "md"` | `md` (the default) in a conversation, `sm` in a narrow panel. |
| `context` | `ReplyContext` | What the thread knows about the assets a reply names: `replyContext(thread.items)`. |
| `className` | `string` | Classes for the prose. |
| `classNames` | `{ code?, table?, link?, word?, asset?, assetIcon? }` | Classes for its code blocks, tables and source links; drawn as words, each word, a bolded asset and its icon. |
| `words` | `boolean` | Draws the reply as words, for an app that shows them arriving: while it streams, each word is its own part with the spaces left between them and live text carries no caret; a change keeps its direction as `data-change`, and a bolded asset is its own part with its icon before its name. A finished reply keeps its text whole. Off by default. |

Parts: `message-markdown-code`, `message-markdown-table`, `message-markdown-link`, and with `words`,
`message-markdown-word`, `message-markdown-asset` and `message-markdown-asset-icon`.

### `NextSteps`

The replies the agent suggests sending next, each a button that sends it as the user's message.
Offer them under the latest reply only. A step only sends text: anything it leads to still meets
its approval card.

| Prop | Type | Description |
| --- | --- | --- |
| `steps` | `readonly string[]` | `splitReplyNextSteps(text).nextSteps`. Draws nothing for none. |
| `onPick` | `(step: string) => void` | Send the step as the user's message. |
| `disabled` | `boolean` | Holds the buttons while a message is sending or a run is going. |
| `className` | `string` | Classes for the root. |

## Agent activity

### `ActivityGroup`

The tool calls between two parts of a reply, as one quiet line: what the agent is doing now, or
what it checked, with the providers' logos. Opened, it lists each step with its provider and read
time, down to the exact input and result.

| Prop | Type | Description |
| --- | --- | --- |
| `steps` | `readonly ActivityStep[]` | The calls, each from `activityStep(item, runEndedAfter(thread, item))`. |
| `className` | `string` | Classes for the root. |

### `ToolCallCard`

A trade the agent ran, followed to the journal's proof of its ending: the exact input and result,
provider references once completed, and Fin's reason otherwise.

An automation's tool row can offer the same failed-action recovery as an approval card.
`FinEntry` forwards the review handler, original-operation mapping and review state to both.
The server-prepared review opens a normal run for a fresh owner signature; it grants no
additional authority to the automation.

| Prop | Type | Description |
| --- | --- | --- |
| `item` | `ToolItem` | The tool call, as the thread holds it. |
| `execution` | `ExecutionView` | The execution it drove, if any: `executionForTool(thread, item)`. |
| `ended` | `boolean` | The run ended after this call without an outcome. |
| `onReviewRemaining` | `(options?) => void` | Prepare a fresh review of proven unclaimed Intents actions. `options` contains `originalIndices?` and an explicitly chosen `maxValueLossBps?`. Pending or uncertain submissions expose no recovery controls. |
| `remainingReviewStatus` | `"preparing" \| "opened"` | Holds the review controls while the request is pending or accepted. |
| `remainingReviewError` | `string` | A visible refusal from preparing the review. |
| `className` | `string` | Classes for the row. |
| `classNames` | `{ details?, swaps?, recovery? }` | Classes for the opened details, execution rows and failed-action recovery panel. |

Parts: `tool-call-card-details`, `tool-call-card-swaps`, `tool-call-card-recovery`.

## Approvals and questions

### `ApprovalCard`

Shows the exact action before anything moves, then shrinks in place and follows it to the
journal's proof of its ending. A money action reads as the terms of the contract Fin derived,
never the model's words. The stored input, contract, result and receipts stay word for word
behind a disclosure.

For `automations_edit`, the frozen stored action renders the exact target snapshot,
current definition, requested patch and complete result visibly before deciding.
Prior spent/used/reserved and resulting remaining allowance are shown without
recomputing or renewing them in the browser. If the old or new definition has a
contract, retain your existing owner-signature authorization handler; `onDecide`
reports a decision, not a substitute for the signed exact request. An unreadable
frozen edit can be canceled but never approved.

`composite` is deliberately **Cancel-only** in this packaged card, including a valid contract:
the shared block does not draw its pieces. Its approval action is guarded independently of
`approvalConsent`. A missing composite grant is also refusal-only. The fin app's enabled basket
feature owns its own exact piece renderer; upgrading this package does not make baskets,
funded orders or cash-outs approvable in a partner's existing UI. Keep signing the server-issued authorization message;
neither an approval summary nor progress events can substitute for its terms.

For `prediction_withdraw`, `ApprovalCard` draws the withdrawal card from a matching
one-shot `prediction_withdraw` grant and exact `{ amountRaw, maxLossBps }` input.
It shows the full six-decimal pUSD debit, own-account native Polygon USDC route,
explicit loss limit and expiry; malformed or mismatched terms permit refusal only.
The risk notice remains visible before approval: the limit checks the bridge's
estimate before transfer, not an on-chain minimum or a guaranteed final conversion
or Intents credit. Bridge liquidity can hold, fail or reduce delivery.

`predictionVariant="visual"` uses an exact pUSD Pays → estimated USDC Holds hero
with loss-limit, quote and Polygon-route facts and a Details disclosure. Progress
remains open while unresolved; terminal decisions use a one-line fold. A confirmed
outgoing transfer and bridge-reported completion are not arrival. Only the unique
own-account deposit's final receipt proves attributed arrival or refund, credited
once by the existing deposit ledger. `prediction.withdrawal` events update the
original card, including after the run ends, and outrank a late original
`tool.result`; uncertainty never offers an automatic resend. Apps drawing their
own cards can use `derivePredictionWithdrawView`, `PredictionWithdrawView`,
`predictionWithdrawProgress`, `PredictionWithdrawProgress` and
`PREDICTION_WITHDRAW_RISK` from the model exports.

For `prediction_order_place`, the card shows the exact market, outcome, side, price,
quantity, order type and fee/spend checks from its matching `prediction_order` grant.
The risk notice remains visible before approval: price is signed, but fees are checked
before submission and lifetime is enforced by the venue. Missing or mismatched grants
permit refusal only. `prediction.order` observations update the original call's result.
A partial match is not settlement, and cancellation does not reverse earlier fills.
With `predictionVariant="visual"`, the approval's secondary button reads Decline (Cancel is
reserved for cancelling an order), a sell shows what it receives at its floor rather than a
zero spend limit, and a failed trade is never drawn as success.

| Prop | Type | Description |
| --- | --- | --- |
| `approval` | `ApprovalView` | The approval: `thread.approvals[approvalId]`. |
| `busy` | `boolean` | A decision is being recorded; holds the buttons. |
| `onDecide` | `(approve: boolean) => void` | The user approved (`true`) or denied (`false`). |
| `outcome` | `ToolItem["outcome"]` | The linked call's result: `toolForApproval(thread, approval)?.outcome`. |
| `running` | `boolean` | The linked call is still running. |
| `ended` | `boolean` | The run ended after the call without an outcome. |
| `execution` | `ExecutionView` | The execution the approval produced. |
| `predictionVariant` | `"default" \| "visual"` | Opt-in Polymarket heroes and progressive disclosure: consent remains visible while pending, secondary figures live under Details, and decided funding / observed orders start closed to their state and key figure. Defaults to the original rendering. |
| `predictionBalance` | `{ pusd: string; readAt: string } \| null` | Host-read exact decimal pUSD balance of the agent's own deposit wallet. Only shown after a route-matching bridge COMPLETED report, when `readAt` is not earlier than that observation's `observedAtMs`; never attributed to this funding. |
| `onDraft` | `(message: string) => void` | With `predictionVariant="visual"`, a placed Polymarket order's Cancel order (open or partly matched) and Check again (failed, rejected or unconfirmed) put a request in your composer, outside the fold; the card executes neither. Without it, those buttons are not drawn. |
| `reference` | `string` | The request id to quote for a failure or a hold. |
| `conflict` | `string \| null` | Fin refused the decision; shown until dismissed. |
| `onDismissConflict` | `() => void` | The user dismissed the refusal. |
| `holdings` | `PricedHolding[]` | The wallet's balances and prices, for estimates. |
| `vaultRates` | `VaultRate[]` | The curated vaults' current rates. A deposit into one notes the provider's rate as variable, and with a scheduled harvest roughly what each period earns on the deposit at that rate. No rate, no note. |
| `tokenRisks` | `ReadonlyMap<string, SolanaRisk>` | What the chat's reads found of each Solana token's risk, by mint (`solanaRisks(thread.items)`): a Solana ticket wears its token's worst warning beside its title. `FinEntry` passes it. |
| `ruleConflict` | `RuleConflict \| null` | Another rule drawing on the same asset; the card asks first. |
| `expanded` | `boolean` | Terms open. Uncontrolled when absent. For visual Polymarket approvals, also initializes the status and secondary-figure Details folds open; later disclosure toggles are local. |
| `automationTerms` | `"disclosure" \| "summary"` | `summary` omits a standing automation's Review terms and Exact terms controls, terms grid and mobile terms sheet, retaining its canonical summary, trade rows, limits, exit notes and decisions. A Solana standing grant always retains Exact terms with its full signed definition. Stored input, authorization and signing are unchanged. `disclosure` is the default. Other approval types keep their existing terms behavior. |
| `onToggleTerms` | `(open: boolean) => void` | The terms opened or closed; pair with `expanded`. |
| `decidedAt` | `string` | When a final state happened, for the status band. |
| `onRetry` | `() => void` | A failed card's Try again. |
| `onProposeAgain` | `() => void` | An expired card's Propose again. |
| `onReviewRemaining` | `(options?) => void` | Review only selected unstarted actions, optionally with an explicitly entered higher total-loss bound. Price-limit, insufficient-funds and availability failures have separate recovery panels; no uncertain submission can enter recovery. `options` contains `originalIndices?` and `maxValueLossBps?`. |
| `remainingReviewStatus` | `"preparing" \| "opened"` | Disables the review button while the request is pending or accepted. |
| `remainingReviewError` | `string` | A visible refusal from preparing the review. |
| `onMakeRule` | `() => void` | A settled card's Make this an automation. |
| `onSendToOneFirst` | `() => void` | For a send to several addresses: send to one first. |
| `now` | `number` | The clock for validity text; stories and tests pin it. |
| `holdProgress` | `number` | Pins the hold-to-approve fill, for stories. |
| `aside` | `ReactNode` | Your own content inside a pending trade, automation or order card, between its terms and its decision buttons. Drawn only while the card waits for a decision; it never replaces the terms, and the card's buttons stay the only way to decide. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ band?, body?, headline?, terms?, actions?, evidence?, hero?, figures?, rail?, footnote?, details?, trigger?, limits?, recovery? }` | Classes for its parts. |

A follow-up button (`onRetry`, `onProposeAgain`, `onMakeRule`, `onSendToOneFirst`) appears only
when you pass its handler. A `RuleConflict` names the other rule (`ruleName`) and, when known,
what both draw on (`asset`, such as `0.175 BTC`).

A limit order's card reads the order itself. One that pays with a stablecoin is a buy, priced per
the asset bought (`Buy NEAR with 10 USDC at ≤ 4 USDC per NEAR`); any other is the sale it is.
Once decided, the card says what happened to the order (placed, not placed and why, or
unconfirmed when 1Click's answer was lost), never that it executed. Cancelling an order opens no
approval; a cancel card from an older conversation still says whether the cancel was requested.

A Hyperliquid order's card (`perps_order_place`) reads its one-shot `perps_order` grant and
leads with a trade ticket: a side chip (`Long`, `Short`, `Close long`, or `Exits` for a
take-profit, stop-loss or trailing stop on the position already held) beside the coin and its
leverage with the margin mode the user chose (`3× cross`, `3× isolated`; an order approved before
margin modes existed reads as cross), and the exact size large with its exact notional under it.
An order that opens or adds to a position adds a grid of the order type (market within a worst
price, limit `Gtc` or post-only `Alo`), the leverage, the margin (notional ÷ leverage, rounded up
to the cent; `Isolated margin` for an isolated order) and, when no rail places it, the worst or
limit price. An order with exits adds a price rail: stop, entry, take-profit and a trailing stop's
activation price (`Trails from 85,000`) placed by their approved prices, each exit's trigger →
worst-fill zone shaded, never a live mark; exits on an existing position read `On your position`
in place of an entry. A trailing stop follows the mark, so its retracement is read under the rail
(`Trails 2% from the best price once the mark reaches 85,000`, or `Trails 1,500` for a fixed
distance); without an activation price it has no fixed price and no marker. The rail is
decorative, and each exit's exact trigger and worst price, and the trailing stop's retracement,
are also read as words. One muted line closes the face: when the approval lapses, or for a
reduce-only close its bound (`Worst price up to 80,000 · reduce-only`); a close is the hero and
that line, with no grid or rail. Everything else is behind one `Details` disclosure: the headline
sentence, which names the mode too (`Long BTC · 0.001 at up to 82,000 · 3× isolated`), every
approved term word for word and never rounded (the `Margin mode`, and near.com's 0.07% builder
fee, none on a trailing stop and `No builder fee` when the trailing stop is the only exit, among
them), and the raw grant and input. A trailing stop alone heads its card `Trailing stop on long
BTC`. A cancellation (`perps_order_cancel`) names its order (`Order #123`, headline `Cancel BTC
order #123`) over its deadline, and its dismiss button reads `Keep order`. A grant missing,
malformed or not matching the stored input offers only Cancel, and `approvalContent` reports it
unreadable. Once decided, the card says what Hyperliquid did: placed (each placement filled with
its size and average price, resting, waiting for its trigger, or rejected; the trailing stop with
its Hyperliquid order number, since it has no client order id), with the average fill on the rail
and each exit's answer under it, rejected with Hyperliquid's reason, not signed, cancelled, not
cancelled, or waiting for Hyperliquid's answer, which is never resubmitted. It never says
executed; a decided card keeps its terms under `Exact terms`.

An automation whose grant is a standing `perps_automation` (`automation_create`) leads with one
firing as the order card's ticket: a side chip (`Open long`, `Reduce long`, `Close long` or `Add
margin`) beside the coin, and the notional, share or exact USDC amount large (`$200.00 notional`
with `3× cross`, `50% of the position`, `25 USDC`). Under it,
the trigger on a compact gauge with one label (`When liquidation distance < 10%`, `When margin
ratio > 60%`, `When funding rate > 0.05%/h`; a rule over any other field reads as its clause in
words), then one muted line of limits (`3 runs · until Sep 12`). Everything else is behind one
`Details` disclosure: the rule's whole sentence and the deadline, then every term (the order and
its worst price, an open's leverage and native exits, or the transfer and its max loss; what it
may do to exposure, `Never opens or adds to a position` or that an open acts only while nothing
is held on the coin; the checks and the policy service's reread of Hyperliquid, the builder fee
on an order, an open's or added margin's region gate), then the raw grant and input. The rule's sentence also names the card for a
screen reader. `expanded` opens `Details`, and `onToggleTerms` reports it. The request must carry
exactly its grant: a request whose contract differs from the grant, a grant this version cannot
read, or a request that does not parse offers only Cancel, and `approvalContent` reports it
unreadable.

The gauge draws only approved numbers and fixed points, with decimal arithmetic: liquidation
distance runs from liquidation at 0% to twice the threshold, margin ratio from 0% to liquidation at
100%, and funding (in percent an hour) from one threshold's width past zero to twice the
threshold, with zero marked. The side the rule acts on is shaded. A reading recorded by a firing's
decision widens the scale to fit when it falls outside. The drawing is decorative
(`aria-hidden`); the trigger and any reading are in words beside it.

A margin change's card (`perps_margin_update`) reads its one-shot `perps_margin` grant and uses the
same ticket: an `Add margin` or `Remove margin` chip beside the coin and `isolated`, the exact USDC
large, where it goes and what it does to the liquidation risk under it, the market and its index,
the deadline in its muted line, and `Builder fee: None` under `Details`. It is headed `Add 250 USDC margin to BTC` or `Remove 12.5
USDC margin from BTC`, under a `Perps margin · needs approval` eyebrow, and approved with `Add
margin` or `Remove margin`. Once decided it reads `Applied` (Hyperliquid added or removed the exact
amount), `Not applied` with Hyperliquid's or Fin's reason (the position's margin is unchanged), or
waiting for Hyperliquid's answer, which is never resubmitted.

A Solana buy, sale, funding or withdrawal (`solana_buy`, `solana_sell`, `solana_fund`,
`solana_withdraw`) reads its one-shot grant, tool-bound like a perps transfer, and every term is
the host's own derivation of the call, never the model's words. It is a venue's ticket, as a perps
order's is: the token's disc and a title (`Buy BONK`, `Sell BONK`, `Fund your Solana account`,
`Withdraw SOL`), then one well of figures, `You pay` (or `You sell`, `You send`), `You get` and
`Max loss` (`8% · at least $46.00` for a buy paid in USDC or USDT, the floor in dollars cut at the
cent and never rounded up; `8% of the value` otherwise), the bound in the caution ink above 300
basis points, the Intents default. A buy or funding paid in dollars names its debit `USDC or USDT`
(`You pay 50.00 USDC or USDT`) with a `From` detail saying it comes from one holding of either that
covers it, USDC first, because the source is chosen only when it runs. One the user approved to pay
with a coin (`payWith`) names that coin and the most of it it may spend instead (`You pay $50.00 of
NEAR`, `From: Your agent wallet's NEAR, at most 22.3125 NEAR`), and so do the perps funding card's
`Amount` and `From` and the visual Polymarket funding card's `Pays` side. The band's countdown is the one deadline it shows. A token the chat's
reads found a warning on wears its worst one beside the title, from `tokenRisks`
(`solanaRisks(thread.items)`, which `FinEntry` passes). SOL itself, which a funding or a withdrawal
moves, wears no network badge. `You get` is an estimate (`≈
1,512,402 BONK`) only where `holdings` prices both sides, a Solana token by `solana:<mint>`;
otherwise it names the asset. The route (`USDC → SOL (1Click) → BONK (Jupiter)`), a USDC buy's
`Top-up` kept as SOL for network fees, the most a transaction pays the network (0.001005 SOL: the
base fee and the priority-fee ceiling, from the reviewed constants), that a buy or a funding opens
the agent's Solana account if it is new, the
shortened token address with a button that copies it whole, the token program and the one
execution sit behind Details. The token's symbol, name and icon come from the resolver by
`solana:<mint>`; a token it does not know reads as its shortened mint, and a token without an
icon wears its first letter on a colour taken from its mint. A grant missing, malformed, for
another tool, for more than one execution or not matching the stored input offers only Cancel, and
`approvalContent` reports it unreadable. Once decided, the eyebrow and status line follow the journal in Solana's words:
`Funding your Solana account` while the 1Click funding leg works, `Swapping on Solana` once that
leg's receipt has settled, `Sending back to your wallet` for the leg that returns USDC, `Done`,
`Partly done: SOL is in your Solana account` (the reason the next step never started is the
outcome's own, when it states one) or, for a sale or a withdrawal whose SOL 1Click took without
completing the transfer, `Partly done: SOL is with 1Click` (its transfer to 1Click landed and the
outcome left no SOL in the account, so it is with 1Click until it refunds it), `Didn't run
(expired)`, or waiting for Solana, never to be approved again. A partial sale or withdrawal whose
outcome says neither reads `Partly done` and sends the user to check their Solana account; it never
guesses where the SOL is. A sale that asked to keep its SOL is `Done` although its outcome is partial by
design. A `solana.reconciled` answer replaces the call's own unconfirmed result, as for perps, so
the card moves from waiting to its final state live and on replay. An occurrence under a standing
grant keeps a financial tool card and its result receipt even when it opens no approval in this
chat: pending, partial, refused and not executed results never inherit the generic completed check.

A Solana buy or sale approved once for every time an automation fires is an `automation_create`
approval whose stored definition carries a `solana_buy` or `solana_sell` contract, and the card
reads it as the automation it is: the eyebrow says `New automation · needs approval`, the ticket's
title is the rule's own sentence (`Every day at 9:00 AM, buy 20.00 USDC of BONK`, `When BONK price
is at or above $0.00003, sell 50% of your BONK for USDC`: every threshold digit is shown,
so `$1.804999` never becomes `$1.80`) and the primary is `Approve automation`.
Its figures are the loss bound `each time` (in the caution ink above 300 basis points) and `Times`
(`Up to 30 times · until Oct 11, 2026, 12:00 PM`). Behind Details: what each run pays or sells (a
sale is a share of what the account holds when it runs, never today's amount), the SOL top-up, for
a condition `Checks` (how often, and that a move between two checks can be missed) and `Execution`
(the market price when it runs, not the level in the condition), the route and the fees, the token
address and program, the signing window and how to revoke. A condition names the token, never its
mint. The grant is drawn only when the host's
contract and the stored definition agree on every term and the rule is one a standing Solana grant
may have (a polled `jupiter.token_price` of the grant's own token, no event wake or exit watch);
otherwise the card offers only Cancel and `approvalContent` reports it unreadable. Once decided it
ends as any saved automation's does, since approving trades nothing. Its Exact terms control remains
available even with `automationTerms="summary"`, showing the complete stored definition the owner
signs, including the rule, grant, limits and signing window.

With `predictionVariant="visual"`, pending Polymarket funding and order approvals keep the
headline, hero, risk notice and decisions visible. Funding's three step-1 tiles move under
`Details`; an order's payout, implied chance and lifetime sit under
`Details · payout, chance, lifetime`. Exact terms retains its existing disclosure.
Decided funding cards and observed orders start closed to their title, status chip and key
figure (delivered USDC or wallet pUSD, matched shares, or a settled receipt's paid/proceeds
and average). Opening reveals the existing figures, stages, rows, receipt and notes. Bridge
failures, held / refunded / refused funding, failed trades, rejected orders and uncertain
states keep their explanation in the summary. An open order's Cancel order and a problem
state's Check again stay outside the fold. Declined / expired funding one-liners and order
stopped stages, submitting and blocked states are unchanged. The `default` variant is unchanged.
Visual funding adds `prediction-fund-card-fold`, `prediction-fund-card-fold-summary` and
`prediction-fund-card-fold-panel`; visual orders add `prediction-order-card-fold`,
`prediction-order-card-fold-summary` and `prediction-order-card-fold-panel`, alongside the
existing hero-side, tile, meter, rows, note and timeline hooks under the corresponding prefix.
Each fold is a keyboard-operable button; reduced motion removes chevron transitions.

A grid's card (`grid_create`) reads the grid contract the owner signs, never the model's words:
its pair and range, a `GridBand` drawn to scale (the price now as a dot when `holdings` prices
both assets, an estimate only), what one cycle earns at least (the sale's minimum receive less
the buy's cost, before fees), the quote its buys use at the start, each order's size, and what
happens outside the range, where the idle cells never place an order. Review terms lists every
level, the cells that start buying, what it uses at the start and when the grid ends; the button
reads Approve grid, and the footnote counts the orders it places at the start (`3 orders`). A
grid contract this version cannot read offers only Cancel. Once decided, the band reads
`Grid · started` (or paused, resumed, stopped for the other grid tools) and the line says where
the grid stands, never that a trade executed.

Parts: `approval-card-band` (the status band), `approval-card-body`, `approval-card-headline`,
`approval-card-terms`, `approval-card-actions` and `approval-card-evidence` (the exact terms; on a
pending perps order, cancellation, margin change or automation, the `Details` disclosure that holds
them). A perps order's, cancellation's, margin change's or automation's ticket adds
`approval-card-hero` (side, coin and size); an order that opens and a margin change add
`approval-card-figures` (the grid), an order adds `approval-card-rail` (the price rail, when it has
exits) and `approval-card-footnote` (its one muted line); a perps automation adds
`approval-card-trigger` (the trigger and its gauge) and `approval-card-limits` (its one limits
line). A Solana ticket uses `approval-card-hero` (the disc and title), `approval-card-figures` (what
it pays and gets and its loss bound, the caution one carrying `data-tone="caution"`) and
`approval-card-details` (the rest).
Inside, `decision-countdown` is the time left to decide and `execution-swaps` a multi-swap
execution's swaps.

> [!NOTE]
> Below 480px wide, the terms open in a sheet portalled to the end of `body`. Theme it page-wide:
> `--fin-*` variables on `:root`, dark mode on `html`, and CSS by `data-fin-ui` rather than a
> selector under the card.

### `ApprovalRecovery`

What an approved request offers once part of it could not run, for an app that draws its own
approval card: the same fresh review `ApprovalCard` offers (a higher price limit, a retry, the
remaining transfers), resuming only the failed branch. Completed actions stay complete, and the new
terms are checked again and signed by the owner as any approval is. It draws nothing until every
claimed action has ended, or when nothing is left to recover.

| Prop | Type | What it does |
|---|---|---|
| `approval` | `ApprovalView` | The approval as the thread holds it. |
| `approvals` | `ApprovalHandlers` | The handlers `FinEntry` takes: `onReviewRemaining` with its states, errors and evidence. Without `onReviewRemaining` it draws nothing. |
| `outcome` | `ToolCallOutcome` | The linked call's result (`toolForApproval(thread, approval)?.outcome`). |
| `running` | `boolean` | The linked call is still running. |
| `ended` | `boolean` | A run boundary came after the linked call (`runEndedAfter`). |
| `execution` | `ExecutionView` | `executionForApproval(thread, approval)`. |
| `className` | `string` | Classes for its block. |

`approvalRecovery(props)` returns what it would offer (the actions, the bound they ran under, and
the review handlers), or `null`: use it to leave out a retry of your own while the review is offered.

### `ApprovalExpansionProvider`

Keeps one approval card's terms open at a time inside it. Wrap your transcript in one. Its only
prop is `children`.

### `ContractTerms`

Every term of a NEAR Intents contract: the actions in their approved order, then the bounds,
allowance and validity. The approval card draws it; place it yourself on an automation's page.

| Prop | Type | Description |
| --- | --- | --- |
| `contract` | `NearIntentsContract` | An approval's `contract` of type `near_intents_transfer`, or an automation's grant. |
| `density` | `"card" \| "compact"` | `card` lists every fact; `compact` is a page's summary. |
| `noun` | `"execution" \| "run"` | `execution` in chat, `run` for an automation. |
| `executionsUsed` | `number` | Executions that used allowance, on an automation's page. |
| `revokedAt` | `string \| null` | When the grant was revoked. |
| `spendProgress` | `string \| null` | Spend against the cap, such as `2 of 5 USDC spent`. |
| `holdings` | `AgentHolding[]` | The wallet's balances, so a share-of-balance term shows today's amount. |
| `now` | `number` | The clock; stories and tests pin it. |
| `className` | `string` | Classes for the root. |

An `AgentHolding` is a holding by `tokenId`, with its `decimals` and its `amountRaw` in the
smallest unit. A `PricedHolding` adds its price, as built under `FinEntry`.

### `GridBand`

A grid drawn to scale: a tick at every level, each cell tinted by its side (buys green, sells
yellow), a dashed tick where no order rests, the price now as a dot, and a dot over each cell
that completed a cycle. Every position comes from the exact prices. The drawing is
`aria-hidden`; a sentence beside it says the same. A grid's `ApprovalCard` and `GridCard` draw
it; place it yourself from `gridView(grid).band` or `gridApprovalView(approval).band`.

| Prop | Type | Description |
| --- | --- | --- |
| `levels` | `readonly string[]` | The levels, lowest first: quote units per one base unit, exact decimals. |
| `cells` | `readonly GridBandCell[]` | One per cell, lowest first: `{ side, resting?, cycles? }`, its `side` `buy`, `sell` or `idle`. A cell that is not `resting` draws dashed; one with `cycles` carries a fill dot. |
| `price` | `string \| null` | The price now, an exact decimal in the same unit: the now dot. None without it. |
| `unit` | `string` | What the prices are in, such as `USDC per ZEC`, for the sentence beside the drawing. |
| `size` | `"sm" \| "lg"` | `lg` (the default) with its price labels; `sm`, a strip for a compact row. |
| `className` | `string` | Classes for the drawing. |
| `classNames` | `{ rail?, ticks?, now?, labels? }` | Classes for its parts. |

Parts: `grid-band-rail` (with each cell's zone), `grid-band-ticks` (with the fill dots),
`grid-band-now` and `grid-band-labels`. Each tick carries `data-tick` (`buy`, `sell`, `both` or
`gap`) and each fill dot `data-fill`.

### `PendingApprovalChip`

A chip above your composer naming the proposal that waits for the user, with its clock.

| Prop | Type | Description |
| --- | --- | --- |
| `pending` | `PendingApproval` | The proposal: its `approvalId`, its `headline` and when it `expiresAt`. |
| `onOpen` | `() => void` | Scroll its card into view. |
| `now` | `() => number` | The clock; stories and tests pin it. |
| `className` | `string` | Classes for the root. |

`pendingApprovals(thread)` lists what waits, and `contractHeadline` words one as the card does.

### `QuestionCard`

The agent's questions, one at a time. A single choice answers with one tap; a multiple choice,
an amount or the user's own words wait for Send, and Skip passes over the question on screen.
After the last, it sends every answer given, or skips the card when the user skipped every
question. Answered, it shrinks to one line.

An option the agent marked `recommended` carries a Recommended badge, and is never chosen for the
user. A question with `amount` draws an amount picker instead of choices: the figure, a slider
from `amount.min` to `amount.max` in steps of `amount.step`, its presets as buttons, and
"Use $100". A preset sends its value; any other amount sends `customText`, its exact decimal.
Amounts are exact decimals throughout; the slider counts whole steps.

| Prop | Type | Description |
| --- | --- | --- |
| `question` | `Question` | The questionnaire: `thread.questions[questionId]`. |
| `onAnswer` | `(questionId, answer) => void` | The user answered or skipped. Send it with `questions.answer`. |
| `busy` | `boolean` | An answer is being sent; holds the buttons. |
| `error` | `string \| null` | Fin's refusal of the last answer, until dismissed. |
| `onDismissError` | `() => void` | The user dismissed the refusal. |
| `variant` | `QuestionCardVariant` | `list` (the default): chips, or one row per described choice. `cards`: two to four described choices side by side as cards (ticked in a multiple choice), rows again when the card is narrower than 480 px, and number keys 1–9 that answer while the card has focus, never while the user types. The key caps hide on a touch screen. |
| `className` | `string` | Classes for the card, or its answered line. |
| `classNames` | `{ header?, prompt?, options?, amount?, error?, actions? }` | Classes for its parts. |

Parts: `question-card-header` (the step line), `question-card-prompt`, `question-card-options`,
`question-card-amount` (the amount picker), `question-card-error`, `question-card-actions`.

## Result cards

The cards a run's results draw. Send `RENDERED_CARDS` as `context.renders` when starting a run,
and the reply leaves these facts to them. Add `placement` to draw a read's card only where the
reply places it, or `show` to draw it where the agent's `show_cards` call stands, as the agent
finds what the question needs: draw each turn from `threadTurns(thread)`
([The model](/react-model#the-transcript)), and these cards where its `card` and `cards` parts
name them.
Send `context.country` from your server's edge geolocation with every message too;
[Tokenized stocks](/concepts#tokenized-stocks) explains the country and purchase restrictions.

### `AutomationCard`

A saved automation: its status, what it waits for, whether it may trade without asking, and when
it ends. Its Manage link goes to `routes.automation(id)`.

| Prop | Type | Description |
| --- | --- | --- |
| `receipt` | `AutomationReceipt` | What `automation_create` or `automations_edit` returned after commit. |
| `automation` | `Automation` | The current owner-scoped read; an older version cannot overwrite a committed edit receipt. |
| `now` | `number` | The clock for times and validity; stories and tests pin it. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, title?, details?, action?, hero?, trigger?, runs? }` | Classes for its parts. |

Parts: `automation-card-header`, `automation-card-title`, `automation-card-details`,
`automation-card-action` (the Manage link). A perps automation adds `automation-card-hero` (what
one firing does, with its bound), `automation-card-trigger` (the trigger's gauge, with the reading
the latest run's decision recorded when its evidence holds one) and `automation-card-runs` (the
grant's runs used of its maximum, and the latest run's state, or when it ends if it has not run).

Edit receipts show the committed definition version and webhook sender setup notice.
Until the complete current read arrives, they do not reconstruct the rule or
claim live financial authority. Keep the page and thread on the same resource cache,
invalidate that cache on a completed edit (also when replayed after reconnect),
and refetch by `automationIdsOf(thread.items)`. The receipt retains its committed
revision even if a later edit has advanced the current definition.
A receipt's `approvalPolicy:"standing_contract"` describes signed terms at commit,
not policy acknowledgement or live signing authority. Recovery reads only the
retained receipt; the separate durable transition carries policy acknowledgement.
Read current grant status before claiming that unattended execution is active.


### `PerpsFiringCard`

One firing of a perps automation in its conversation: the sealed reduce order the automation's run
placed (`perps_order_place`), drawn beneath that run's activity line. `FinEntry` draws it for a
call the thread stamped with its run's automation; pass the automation by id in `automations`
(`automationIdsOf(thread.items)` includes it).

| Prop | Type | Description |
| --- | --- | --- |
| `item` | `ToolItem` | The run's `perps_order_place` call, with Hyperliquid's answer. |
| `automation` | `Automation` | The automation whose run it was, when read: the card counts the run and shows why it fired. |
| `now` | `number` | The clock for times; stories and tests pin it. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ band?, body?, hero?, rail?, trigger?, status? }` | Classes for its parts. |

It reads the order and Hyperliquid's answer from the call itself: the order's hero (`Reduce long`,
the filled size, `Filled at an average 74,980.5 USDC`), and the fill on a rail between the order's
bound (`Floor 74,250 · never sold below` for a long) and, when the decision recorded one, the mark
(`Mark 75,000 · at the check`). With the automation it adds `Run 1 of 3` (only when this call's run
is the automation's latest and the order was placed: the grant's executions used of its maximum)
and `Why it fired` on the trigger's gauge, with the reading the run's decision recorded. A figure
the card was not given is left out. Placed and filled, Hyperliquid's sentence stays for a screen
reader; any other answer is in words.

Parts: `perps-firing-card-band`, `perps-firing-card-body`, `perps-firing-card-hero`,
`perps-firing-card-rail`, `perps-firing-card-trigger`, `perps-firing-card-status`.

### `WalletCard`

The agent wallet as a balance read found it: the total and each asset, valued exactly and rounded
once. When the read says how each price was found (`priceStatus`), the total is what is priced,
with the count of unpriced assets under it ("1 unpriced"), and a row whose price is carried, the
owner's last trade or missing says so under its value ("Carried", "Last trade", "No price"). A read
without `priceStatus` draws as before: no total while any asset is unpriced. Its link goes to
`routes.assets()`.

| Prop | Type | Description |
| --- | --- | --- |
| `reading` | `WalletReading` | The read's balances, priced where a price was known, each with how its price was found where the read says. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, holdings?, action? }` | Classes for its parts. |

Parts: `wallet-card-header` (with the total and the unpriced count), `wallet-card-holdings`,
`wallet-card-action`.

### `OrdersCard`

Limit orders, one line each: what it buys or sells and at what price, where it stands, and when it
lapses.
A fill never reads as done while its payout can change. Its "Manage orders" link goes to
`routes.orders()`, your page for the user's limit orders, where a cancel button calls Cancel a
limit order.

| Prop | Type | Description |
| --- | --- | --- |
| `orders` | `readonly LimitOrderView[]` | The orders, each with its fill and payout status. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, orders?, action? }` | Classes for its parts. |

Parts: `orders-card-header` (the count), `orders-card-orders`, `orders-card-action`.

### `PredictionOrdersCard`

The owner's retained Polymarket orders, with exact approved prices and quantities,
observed matched/unmatched shares and settlement status. `FinEntry` draws this for
`prediction_orders` when `resultCards` includes `predictions`. An empty result shows
that this page has no orders. The card never fetches or cancels an order itself.

| Prop | Type | Description |
| --- | --- | --- |
| `orders` | `readonly PredictionOrderRow[]` | Each row contains `operationId`, the approved `order` and its latest `observation`. |
| `nextAfterId` | `string \| null` | Optional tool-page continuation id. A non-null id shows that more orders are available; `onDraft` adds a next-page draft button. |
| `onDraft` | `(message: string) => void` | Optional cancellation draft for an open, partially matched or uncertain order, or next-page request. The host puts it in the composer; it executes neither request. |
| `variant` | `"default" \| "visual"` | `visual` groups Open and Needs checking orders above a closed Finished fold. Each row starts closed to side, quantity, limit, status chip and market question; opening reveals the thin partial-fill meter and figures. Failure / uncertainty explanations and Cancel order remain visible without opening a row. `FinEntry` passes its `predictionVariant`. Defaults to the original rendering. |
| `now` | `number` | The clock the visual header's "checked" time is read against. Defaults to `Date.now()`. |
| `defaultOpen` | `boolean` | Initially opens every visual order row and the Finished group. Defaults to `false`; no effect on the default variant. |
| `className` | `string` | Classes for the root. |
| `classNames` | `PartClassNames<PredictionOrdersCardPart>` | Classes for the named parts. |

Parts: `prediction-orders-card-header`, `prediction-orders-card-orders`,
`prediction-orders-card-order`, `prediction-orders-card-terms`,
`prediction-orders-card-status`, `prediction-orders-card-actions`, `prediction-orders-card-pagination`.
The visual root carries `data-fin-variant="visual"` and adds
`prediction-orders-card-group`, `prediction-orders-card-figures`,
`prediction-orders-card-meter`, `prediction-orders-card-fold`,
`prediction-orders-card-fold-summary` and `prediction-orders-card-fold-panel`.
The header keeps open / needs-checking counts and the checked time visible. Live and partly
filled orders belong to Open; uncertain, cancel-unconfirmed, settling / settlement-unconfirmed
and cancelled / expired orders with unsettled or failed trades belong to Needs checking.
Everything else belongs to Finished. Show older orders and the empty state are unchanged.

### `GridCard`

A grid of resting limit orders as it runs, beside the message that started, changed or read it:
its state badge, what it earned, how many buys and sells rest now and the base it holds, its
`GridBand` with the cells that filled, its completed cycles, and its controls. Pause shows on a
running grid, Resume on a paused one, Stop until it ends, each only when you pass its handler;
your server then calls Pause, Resume or Cancel a grid.

| Prop | Type | Description |
| --- | --- | --- |
| `grid` | `Grid` | The grid as a grid tool or Get a grid returned it. |
| `variant` | `"full" \| "compact"` | `full` (the default), or `compact`: one row with its earnings, a strip of its band and what rests, for a list of several. |
| `price` | `string \| null` | The price now, quote per one base as an exact decimal, when your app has it: the band's now dot. |
| `now` | `number` | The clock for the grid's day count; stories and tests pin it. |
| `busy` | `GridAction \| null` | The control being sent now: its button waits and the others hold. |
| `onPause` | `() => void` | The user pressed Pause. Without it, no Pause button. |
| `onResume` | `() => void` | The user pressed Resume. Without it, no Resume button. |
| `onCancel` | `() => void` | The user pressed Stop; confirm it first if your app asks. Without it, no Stop button. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, title?, band?, stats?, fills?, actions? }` | Classes for its parts. |

Parts: `grid-card-header` (with the state badge), `grid-card-title`, `grid-card-band`,
`grid-card-stats` (the figures, or a compact card's line), `grid-card-fills` (its completed
cycles) and `grid-card-actions`. The root carries `data-state`, the grid's `state`, and
`data-variant`.

### `ContactsCard`

The user's saved contacts as a `contacts_list` lookup found them, one row each, as a contacts page
shows them: the name, the address shortened with a button that copies it whole, and the network.
Five show at first and a button shows the rest. When the user has none saved, it says so. Its link
goes to `routes.contacts()`, your app's own contacts page; unset, it draws no link. It draws only
the contacts your server sent as `context.contacts` with that message, and none for a lookup right
before a payment approval, whose card shows the full address.

| Prop | Type | Description |
| --- | --- | --- |
| `lookup` | `ContactsLookup` | The contacts the lookup returned, how many `matched`, whether it was `truncated`, and what it searched for (`search`, `network`). |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, contacts?, more?, action? }` | Classes for its parts. |

Parts: `contacts-card-header` (the count, and what was searched for), `contacts-card-contacts`,
`contacts-card-more` (shows the rest), `contacts-card-action`.

### `PriceCard`

One asset's price over the window a `market_history` read covered: the price and its change, a
chart, and the window's figures (its return, biggest drop with its dates, best and worst day)
exactly as the tool reported them, with the source and when it was read. The chart's readout
starts pinned to the low of the biggest drop when the read included the daily `series`; a hidden
"History point" slider moves it for the keyboard. With `loadHistory`, range tabs (1W, 1M, 3M, 1Y)
redraw the chart and its change over another window your server loads; the tool's figures stay
with the tool's own window. Prices become pixel positions only to draw the line; every figure is
an exact decimal. `FinEntry` draws it when `resultCards` includes `market`.

| Prop | Type | Description |
| --- | --- | --- |
| `history` | `PriceHistory` | One asset's history, from `toolBlock` (`kind: "price"`). |
| `loadHistory` | `PriceHistoryLoader` | `({ assetId, range, signal }) => Promise<PricePoint[]>`: loads a `PriceRange` for the range tabs, oldest first; reject when it is unavailable. Without it, no tabs. `PriceCard` asks for 1W to 1Y; a range type that also names `1D` lets one loader serve a card of your own that offers the day. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, chart?, ranges?, figures?, source? }` | Classes for its parts. |

Parts: `price-card-header` (the price and its change), `price-card-chart`, `price-card-ranges`,
`price-card-figures`, `price-card-source`.

### `ComparisonCard`

Several assets from one `market_history` read side by side: each one's trend line, price now, move
today (since the last daily price), return over the window and worst drop, as the tool reported
them. Assets the read could not reach are named beneath. It ranks nothing; the reply says which
did best. `FinEntry` draws it when `resultCards` includes `market`.

| Prop | Type | Description |
| --- | --- | --- |
| `comparison` | `MarketComparison` | The read's assets, from `toolBlock` (`kind: "comparison"`). |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, table? }` | Classes for its parts. |

Parts: `comparison-card-header` (the assets and the source), `comparison-card-table`.

### `PredictionsCard`

The events a `prediction_markets` search found, each linked to its venue page with its end date
and volume, and up to four of its markets. For an open search a market shows the chance traders
price on its first outcome (its price, read as a percentage, beside a bar) and the bid-ask spread,
or Thin when the tool marked the quote weak; for a settled search (`status: "settled"`) it shows
the outcome the market resolved to, or Not settled, and the day it closed. Days are the venue's,
in US Eastern time and marked ET ("Ends Dec 9, 2026 ET"), wherever the reader is. Markets the
tool left out are counted beneath each event, and the note says a price is a market-implied
chance, not a forecast (or that settled prices are final), and that the research read places
no order. It ranks nothing and suggests no trade. A search that found no event draws nothing.
`FinEntry` draws it when `resultCards` includes `predictions`.

`variant="visual"` makes the header a card-level fold, initially open, with the query, source,
read time and event count. Events start closed to their question, leading outcome with a thin
green bar and chance, end date, volume and market count. Opening one shows its first four
markets; “N more markets” opens any remaining returned markets. Only the leader is green, and
a weak quote is marked on its row without opening quote details. “Quote details · spreads”
holds the bid–ask figures and explains that a spread above $0.10 deserves little weight.
Each event retains its venue link and the count of markets omitted from the read. Settled
searches name resolved outcomes instead of showing percentages. The original table remains
the default. Visual cards state monetary figures to four significant digits.

| Prop | Type | Description |
| --- | --- | --- |
| `search` | `PredictionSearch` | The search's events, from `toolBlock` (`kind: "predictions"`). |
| `variant` | `"default" \| "visual"` | Original table (default), or outcome-bar rows. |
| `defaultOpen` | `boolean` | Visual only: initially opens the first event (default `false`); the card-level fold always starts open. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, events?, note? }` | Classes for its parts. |

Parts: `predictions-card-header` (the query and the source), `predictions-card-events`,
`predictions-card-note`.
Visual-only styling hooks: `predictions-card-event`, `predictions-card-outcome-row`,
`predictions-card-bar`, `predictions-card-spread`. Visual roots carry `data-fin-variant="visual"`.
Visual folds expose `predictions-card-fold`, `predictions-card-fold-summary` and
`predictions-card-fold-panel`; `data-fin-fold="card"`, `"row"` or `"quiet"` identifies the level.
Summary buttons support Enter and Space; mounted panels retain nested disclosure state.

### `PredictionMarketCard`

One market a `prediction_market` read found: its question, where it resolves from, its end date
(in US Eastern time, marked ET) and volume, both outcomes with the chance and share price each
implies, and the venue's own settlement rules folded under Settlement rules, with the note that
clarifications the venue posts later are not shown. A closed market shows the outcome it resolved
to and the day it closed in place of prices, or says it has not cleanly settled when its final
prices name no winner; a market the venue is not trading but has not closed reads Inactive, never
closed or settled. Its footer marks the result as research with no order placed and links to
the venue page.
`FinEntry` draws it when `resultCards` includes `predictions`.

`variant="visual"` starts closed to the question, Yes/No split, status, end date and source.
Both chances and per-share prices remain in the split's legend. Opening the card adds volume,
liquidity, whether the market accepts orders, its resolution source and the venue link.
Settlement rules are a nested quiet fold. A missing price is not invented; a settled market
names its winner instead of showing prices. Closed and inactive markets keep their status
and explanation visible even while closed. The default variant keeps its original tiles
and settlement-rules Disclosure.

| Prop | Type | Description |
| --- | --- | --- |
| `market` | `PredictionMarketDetail` | The market, from `toolBlock` (`kind: "predictionMarket"`). |
| `variant` | `"default" \| "visual"` | Original outcome tiles (default), or Yes/No split. |
| `defaultOpen` | `boolean` | Visual only: initially opens the card's facts (default `false`); rules remain closed. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, outcomes?, facts?, rules?, footer? }` | Classes for its parts; `facts` is visual-only. |

Parts: `prediction-market-card-header` (the question, the source and the facts),
`prediction-market-card-outcomes`, `prediction-market-card-rules`,
`prediction-market-card-footer`.
Visual-only parts: `prediction-market-card-facts`, with additional styling hooks
`prediction-market-card-split` and `prediction-market-card-legend`.
Visual folds expose `prediction-market-card-fold`, `prediction-market-card-fold-summary` and
`prediction-market-card-fold-panel`, with `data-fin-fold` identifying card and quiet levels.

### `PredictionPreviewCard`

What a stake on one outcome would buy against the venue's displayed offers, as a
`prediction_preview` walk found it: the shares, the average price and what they pay if the
outcome happens ($1 a share), with how fully the book took the stake (Fully placed, Book too thin,
Below minimum or No offers) and, when it did not, how much found no offer or the venue's minimum.
Shares and the payout are rounded down to the cent, so the card never shows more than the walk
bought. The note says when the order book was read, that fees are not included, that it is not
a quote, and that no order was placed.
`FinEntry` draws it when `resultCards` includes `predictions`.

`variant="visual"` starts closed to “$X on outcome → N shares”, the depth chip, average price,
payout if right, source and read time. A thin book's unplaced amount and a below-minimum
explanation with its unplaced amount remain visible in the summary. Opening the card adds
the fill meter (green is reported cost, red is unspent stake), both figures in its legend,
and best-ask, worst-price and book-level tiles. The warning records the read time, “not a quote”
and fees not included. Meter width uses exact decimal arithmetic, not floating-point money.
Stated amounts are cut to four significant digits, never rounded up. No orders are placed.

| Prop | Type | Description |
| --- | --- | --- |
| `preview` | `PredictionPreview` | The walk, from `toolBlock` (`kind: "predictionPreview"`). |
| `variant` | `"default" \| "visual"` | Original figures (default), or fill meter and stat tiles. |
| `defaultOpen` | `boolean` | Visual only: initially opens the fill meter, tiles and preview warning (default `false`). |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, figures?, meter?, legend?, warning?, footer?, note? }` | Classes for its parts; meter, legend, warning and footer are visual-only. |

Parts: `prediction-preview-card-header` (the stake and how fully it was placed),
`prediction-preview-card-figures`, `prediction-preview-card-note`.
Visual-only parts: `prediction-preview-card-meter`, `prediction-preview-card-legend`,
`prediction-preview-card-warning`, `prediction-preview-card-footer`; tiles expose the
`prediction-preview-card-tile` styling hook.
The visual fold exposes `prediction-preview-card-fold`, `prediction-preview-card-fold-summary`
and `prediction-preview-card-fold-panel`, with `data-fin-fold="card"`.

### `SettlementReceipt`

One swap's settlement as the journal recorded it: what was received or returned.

| Prop | Type | Description |
| --- | --- | --- |
| `receipt` | `EventPayload<"intents.settlement">` | The journal's settlement record. |
| `className` | `string` | Classes for the receipt. |
| `classNames` | `{ header?, details? }` | Classes for its parts. |

Parts: `settlement-receipt-header` (the confirmation line), `settlement-receipt-details`.

### `SolanaReceipt`

What a Solana buy, sale, funding or withdrawal did, drawn under its approval from the call's own
outcome (`FinEntry` places it), its figures in one well as the approval's ticket draws its terms.
Every figure is the host's record, read with exact arithmetic:
what was paid and received, the average price that came to (paid ÷ received, in dollars as every
token price reads, `$104.20` or `$0.0₄3306`, or in SOL), the network fees the landed transactions paid, and any SOL the operation left in the
Solana account, then a row per transaction it signed (`Swap`, `Send back`) with where it stands:
landed, landed with an error, expired before it landed, or not confirmed yet. A transaction links
to your explorer through `routes.transaction("solana", signature)`; without one the signature is
shortened with a button that copies it whole. The title says what it was (`Bought BONK`, `Sold
BONK`, `Funded your Solana account`) once it is done, and a neutral noun (`Your BONK buy`) while it
is not; the badge is the outcome's own status. A buy that only funded the account, or a sale
whose SOL stayed in the account, offers its next moves as buttons (`Buy BONK with it`, `Move it back
as USDC`) that send a message as the user's next one through `onSend`; they move nothing. A sale
that asked to keep its SOL is `Done`, although its outcome is partial by design.

| Prop | Type | Description |
| --- | --- | --- |
| `receipt` | `SolanaReceiptView` | The receipt, from `deriveSolanaReceipt(approval, outcome)`: `null` for an outcome without a Solana detail, so draw nothing then. |
| `onSend` | `(message) => void` | Send the message as the user's next one. Without it, no follow-up buttons. `FinEntry` passes its `onSend`. |
| `disabled` | `boolean` | Holds the follow-ups while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, figures?, transactions?, actions? }` | Classes for its parts. |

Parts: `solana-receipt-header` (the title and its status), `solana-receipt-figures`,
`solana-receipt-transactions`, `solana-receipt-actions` (the follow-ups).

### `HoldingsCard`

The agent wallet as a balance read found it, as a breakdown: a donut of each asset's value beside
a list, largest first, of each asset's amount, exact value and share of the total. Shares are
rounded once, to a tenth of a percent, from integer cents. An asset without a price is listed
without a value and left out of the total, which says so. When the read says how each price was
found (`priceStatus`), a row whose price is carried, the owner's last trade or missing names it
after its amount ("· Carried", "· Last trade", "· No price"), and the unpriced are counted in the
donut under the asset count ("1 unpriced") rather than marked with a "+". Its link goes to
`routes.assets()`.
`FinEntry` draws it in place of `WalletCard` with `walletVariant="holdings"`.

| Prop | Type | Description |
| --- | --- | --- |
| `reading` | `WalletReading` | The read's balances, priced where a price was known, each with how its price was found where the read says. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, chart?, holdings?, action? }` | Classes for its parts. |

Parts: `holdings-card-header`, `holdings-card-chart` (the donut and the total),
`holdings-card-holdings`, `holdings-card-action` (the Assets link).

### `VaultsCard`

The curated vaults an `earn_vaults` read listed, one each: the vault, its share token and chain,
what it pays with, its minimum, its share price and its three fees verbatim, the rate its provider
states now ("5.40% APY now (Yield.xyz) — variable, not guaranteed", worded as the approval card's
vault yield note), and how many vaults are not tradable right now. A vault whose rate could not be
read shows none, and the card never projects a yield of its own. Beside the warning that each vault
is a third-party strategy whose value can fall, it says a rate is the provider's figure now and can
change, or that no live rate is available when no vault has one. Deposit moves nothing: it hands
your composer a message ("Deposit 1,000 USDC into Gauntlet USDC", the largest power of ten of the
payment asset the wallet holds, or no amount when it holds less than one) for the user to edit and
send; the deposit itself is an ordinary swap they approve.
`FinEntry` draws it when `resultCards` includes `vaults`.

| Prop | Type | Description |
| --- | --- | --- |
| `earn` | `EarnVaults` | The vaults, from `toolBlock` (`kind: "vaults"`). |
| `holdings` | `PricedHolding[]` | The agent wallet's holdings, to name a Deposit's amount. `FinEntry` passes the `holdings` of its `ApprovalHandlers`. |
| `onDeposit` | `(message) => void` | Put the message in your composer. Without it, no Deposit buttons. `FinEntry` passes `onDraft`. |
| `disabled` | `boolean` | Holds Deposit while a run works. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, vaults?, note? }` | Classes for its parts. |

Parts: `vaults-card-header`, `vaults-card-vaults`, `vaults-card-note` (the risk and rate note).

### `TokenCandidatesCard`

The tokens a `solana_token_search` found, to choose between: the card is the question (`Which
WIF?` when two of the candidates it offers first share a symbol), and the agent asks no other.
First the candidates that share the name or symbol asked about, those Fin would buy before those it
wouldn't, verified first and then by the liquidity in their pools, deepest first; the rest of what
the search found waits behind **Show N more** (`searchContenders(search)` orders them). A ticker is not unique on Solana, so each row carries what tells the candidates
apart: the token's disc, name and symbol, its mint shortened with a button that copies it whole,
the venue's **Verified** mark, and one warning chip only where Fin's checks raised a flag (never a
mark that says it is safe). **Use this one** sends a message naming the token and its whole mint as
the user's next one; it approves nothing. The name links to `routes.asset`. A search that found
nothing draws nothing. `FinEntry` draws it when `resultCards` includes `solana`.

| Prop | Type | Description |
| --- | --- | --- |
| `search` | `SolanaTokenSearch` | The search, from `toolBlock` (`kind: "tokenCandidates"`): the query, whether it was `ambiguous`, the candidates and where they were read. |
| `onSend` | `(message) => void` | Send the message as the user's next one. Without it, no Use this one buttons. `FinEntry` passes its `onSend`. |
| `disabled` | `boolean` | Holds the buttons while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, candidates?, more? }` | Classes for its parts. |

Parts: `token-candidates-card-header` (the question and the source),
`token-candidates-card-candidates`, `token-candidates-card-more` (Show N more). Inside,
`mint-address` is a mint beside its copy button.

### `MemecoinsCard`

The sampled Solana candidates a `memecoins_top` read ranked for one lane and window, as
`ComparisonCard` lists coins: a title line (`Trending memecoins`, with `Jupiter` and the time of
the read) and ranked rows of rank, disc, name and symbol, price (four significant digits below a
dollar) and the move over the window, with one warning chip only where Fin's checks raised a flag.
A row whose symbol another row shares shows its shortened mint. On a narrow card the move sits
under the price. Seven rows show and the rest wait behind **Show more**. A row opens in place, one
at a time, as the activity line's steps do (a button that names the row and the region it
controls, by keyboard too): the token's last day as a chart (an hour a point, read through
`loadToken`), its market cap, liquidity, 24-hour volume, holders (with `loadToken.token`) and age,
every warning it carries, its mint with a copy button, **Open token page** (`routes.asset`) and
**Buy…**, which sends a message naming the token by its mint through `onSend` (none for a token Fin
will not buy, whose warning says why). The row's reads are kept for the card's life, and one that
failed is asked again when the row opens again. A list with no rows draws nothing. `FinEntry` draws it when
`resultCards` includes `solana`.

`list` can additionally carry classification, evidence gaps, source coverage and a next-page
cursor. Preserve those facts when composing a broader discovery page: an unclassified launch
is not a confirmed meme, and an activity rank is not a buy recommendation. The read-only
`solana_token_history` tool contributes research activity without a separate result card.

| Prop | Type | Description |
| --- | --- | --- |
| `list` | `SolanaTokenList` | The ranked list, from `toolBlock` (`kind: "memecoins"`): its `lane`, `interval`, `items` and source. |
| `loadToken` | `SolanaTokenLoader` | Reads an open row's chart (`chart`) and, optionally, its holders (`token`). Without it an open row shows the list's own figures, its warnings and its actions. `FinEntry` passes its `loadSolanaToken`. |
| `onSend` | `(message) => void` | Send an open row's Buy… message as the user's next one. Without it, no Buy…. `FinEntry` passes its `onSend`. |
| `disabled` | `boolean` | Holds Buy… while a run works or a message is on its way. `FinEntry` passes it from `sendDisabled` and the run's state. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, tokens?, detail?, more? }` | Classes for its parts. |

Parts: `memecoins-card-header`, `memecoins-card-tokens` (the rows), `memecoins-card-detail` (an
open row), `memecoins-card-more`.

### `SolanaTokenCard`

One token a `solana_token` read found, as `PriceCard` draws a coin: `BONK price` with the mint
shortened beside its copy button, the price (four significant digits below a dollar) and the
day's move in dollars and percent, the token's warnings as one row of chips only where Fin's
checks raised any (`Unknown risk` first when Fin could not read its setup, then each flag, the
ones that refuse a buy in the danger tone), its market cap, liquidity, 24-hour volume and holders,
and the source line (`Jupiter · read 4:14 PM`). A figure the venue did not give is a dash, never
zero, and a token with no flag raised shows no chip, never a mark that says it is safe. `FinEntry`
draws it when `resultCards` includes `solana`.

| Prop | Type | Description |
| --- | --- | --- |
| `token` | `SolanaTokenDetail` | The token, from `toolBlock` (`kind: "solanaToken"`). |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, risk?, figures?, source? }` | Classes for its parts. |

Parts: `solana-token-card-header` (the price and its move), `solana-token-card-risk` (only when
there is a warning), `solana-token-card-figures`, `solana-token-card-source`.

### `SolanaHoldingsCard`

The agent's Solana account as a `solana_account` read found it, as `WalletCard` draws the agent
wallet: what it is worth (with `2 not valued` beneath when some holdings have no price, which the
total leaves out), when it was read, a table of its SOL and each token with the Solana badge by
amount (`formatAssetFigure`) and value, and an **Assets** link (`routes.assets`). A holding with no
price stays listed with a dash, never zero. A token with no symbol is named by its shortened mint,
and one whose symbol another holding shares shows its shortened mint too, each with a copy button.
When the agent has no Solana account yet, or the read failed, the card says so in a line. The SOL
links to your page for the account's SOL (`routes.asset` with `SOLANA_SOL_ID`), never SOL's market.
`FinEntry` draws it when `resultCards` includes `solana`, except in the middle of a trade, where it
is the agent checking the account: before an approval, a question or a Solana trade, and beside
the candidates a search found, which are the question.

| Prop | Type | Description |
| --- | --- | --- |
| `account` | `SolanaAccountRead` | The answer, from `toolBlock` (`kind: "solanaHoldings"`): the account with its holdings, or the typed `no_account` or `unavailable` answer. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, holdings?, action? }` | Classes for its parts. |

Parts: `solana-holdings-card-header` (with the total), `solana-holdings-card-holdings`,
`solana-holdings-card-action` (the Assets link).

## Run outcome

### `RunProgress`

A run that proposed moving money, step by step as it happened: what the agent read, the proposal
waiting on the user's approval below, and each swap of an approved plan as it settles. It plans
nothing ahead, and a step reads as done only once its result or settlement receipt is in. The head
says the financial state and how many transfers settled, excluding reads. A partial or uncertain
ending stays explicit after the model finishes. Unstarted and blocked actions stay still; the step working or waiting carries
`aria-current="step"`. `runProgress(thread, key)` gives what it takes for a run with an approval
and two steps or more.

| Prop | Type | Description |
| --- | --- | --- |
| `progress` | `RunProgressView` | The run's steps, from `runProgress`. Its `request`, the run's first message, names a chat card's token by its shortened mint (`withShortMintMentions`). |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, bar?, steps? }` | Classes for its parts. |

Parts: `run-progress-header` (the request, state and count), `run-progress-bar` (decorative),
`run-progress-steps`.

### `RunReceipt`

What a finished run moved, swap by swap, from its settlement receipts: what each spent and what it
delivered, or that it was refunded or never ran. `runReceipt(thread, key)` gives it once the run
ended with two swaps or more settled. It states no fee: the receipts carry none.

| Prop | Type | Description |
| --- | --- | --- |
| `receipt` | `RunReceiptView` | The run's swaps, from `runReceipt`. |
| `className` | `string` | Classes for the card. |
| `classNames` | `{ header?, lines?, footer? }` | Classes for its parts. |

Parts: `run-receipt-header`, `run-receipt-lines`, `run-receipt-footer`.

### `RunFooter`

How a run ended, when that needs saying: "Stopped" for a run the user stopped; for a failure, why
in plain words and the request id to quote. When an action may have started, it says to check the
history before trying again. A run that a budget or spend limit stopped says which one (the
user's day or month, a freeze, or your app's own limit) and when it resets, and never suggests
trying again at once. A completed run draws nothing, unless you pass `feedback`: then a
completed or failed run also carries a thumbs-up and a thumbs-down. One tap sends the feedback,
and a tap on the thumb already chosen deletes it. Tapping the thumbs-down opens a panel of
reasons (Incorrect, Not helpful, Too slow, Unsafe, Something else). A reason is optional:
picking one sends it, and Skip closes the panel.
Once Fin has saved what the user sent (the `value` you pass shows it and `busy` is off):

- the panel closes, and focus moves to the thumbs-down if it was inside the panel;
- "Thanks, your feedback was recorded." shows beside the thumbs for four seconds, then fades.

The thanks never shows for feedback that is not saved:

- a refused reason keeps the panel open with the refusal, so the user can try again;
- Skip after a refused thumbs-down closes the panel with no thanks.

A thumbs-down saved before (after a reload, say) shows pressed, and the panel does not open
again. While a tap is being saved the controls ignore taps but keep the keyboard focus. A run the
user stopped is never offered the thumbs.

| Prop | Type | Description |
| --- | --- | --- |
| `item` | `RunItem` | The `run` item that closes a turn. Its `runId` names the run the feedback is for. |
| `feedback` | `RunFooterFeedback` | Lets the user send feedback on the reply. Without it, no thumbs are drawn. |
| `className` | `string` | Classes for the root. |
| `classNames` | `{ feedback?, reasons?, thanks? }` | Classes for its parts. |

`RunFooterFeedback` is `{ value, busy?, error?, onChange, tooltip? }`:

| Field | Type | Description |
| --- | --- | --- |
| `value` | `RunRating \| null` | The user's feedback on this reply now, as Fin returned it (the run's `feedback`); `null` while there is none. |
| `busy` | `boolean` | Feedback is being saved: holds the thumbs and the reasons until it lands. |
| `error` | `string \| null` | Fin's refusal of the last feedback, in words, shown beside the thumbs. |
| `onChange` | `(feedback) => void` | The user sent, changed or deleted their feedback. Send `{ rating: "up" }` or `{ rating: "down", reason? }` with `runs.sendFeedback`; `null` deletes it, with `runs.deleteFeedback`. |
| `tooltip` | `ControlTooltip` | Wraps each icon-only control (the thumbs, the reasons' Skip) in your own tooltip. Without it they draw as they always have. |

To draw a failed run your own way, `failedRunText(item)` returns the words `RunFooter` says for
it: why the reply stopped and what to do next, in the same plain sentences. Show `item.reference`
beside them when it is there.

Model connection, timeout, rate-limit and availability failures receive bounded
server-side recovery before a failed ending is published. `model_invalid_output`
means terminal structured output still failed its schema after bounded repair.
Earlier actions may have completed regardless of which stage failed. A reply retry
should generate an answer from retained results with `profile.tools: []` in
`runs.start`, rather than repeat the original action request with tools enabled.
For financial recovery, use the existing eligible-action review and fresh approval.
Assistant `agent.entry` events may carry `interrupted: true`; the reducer preserves
that flag even if a later attempt completes the run. Mark such a draft as interrupted while nothing
follows it. `transcriptEntries` leaves it out once later words of its turn exist, so it never
reaches the final answer's Copy action.

A `ControlTooltip` is `(label, control) => ReactNode`: it is given a control's name (`Good reply`,
`Bad reply`, `Skip`, the same as its accessible name) and the control, and returns the control
inside your tooltip. Render `control` as your tooltip's trigger, passing its props and ref through,
and don't add a second accessible name: the control already has one.

A `RunRating` is `{ rating, reason? }`: `rating` is `up` or `down`, and `reason` (one of `wrong`,
`unhelpful`, `slow`, `unsafe` or `other`) only goes with `down`. A run's `feedback` from the SDK, and
the body you send, both fit it.

Parts: `run-footer-feedback` (the thumbs), `run-footer-reasons` (the panel of reasons after a
thumbs-down), `run-footer-thanks` (the thanks once feedback is saved: a live region, empty
otherwise).

## Tokens and chains

### `TokenIcon`

A token's disc: its icon, or the symbol's initials, with its network's badge when you name one.
Decoration only: it never identifies the asset.

| Prop | Type | Description |
| --- | --- | --- |
| `symbol` | `string` | The symbol; its first three characters are the fallback. |
| `iconUrl` | `string \| null` | A URL or `data:` URI, as `TokenInfo.icon` gives it. `null` draws the initials. |
| `size` | `16 \| 20 \| 28 \| 36 \| 40` | 40 an asset row, 36 compact, 28 inline, 20 a table row, 16 within text. |
| `network` | `string \| null` | The token's chain, `assetChain(tokenId)`, badged on the disc. |
| `ringClassName` | `string` | The badge ring's colour, matching the surface below. |
| `className` | `string` | Classes for the root. |
| `data-fin-part` | `string` | The part name for its root; `AssetIcon` passes `asset-icon`. |

It carries `data-fin-ui="token-icon"`, and its badge `data-fin-ui="network-badge"`.

### `AssetIcon`

A held asset's icon from the token list, with its chain's badge unless `compact`.

| Prop | Type | Description |
| --- | --- | --- |
| `asset` | `PortfolioHolding` | A holding, as Fin's wallet read or a provider names it. |
| `compact` | `boolean` | A 36px disc without the badge; otherwise 40px with it. |
| `className` | `string` | Classes for the root. |

## Configuration

### `FinUIProvider`

How your app links, where cards link and what tokens look like, for every block inside it. It
carries no data.

| Prop | Type | Description |
| --- | --- | --- |
| `link` | `LinkComponent` | Your router's link component. Defaults to a plain anchor. |
| `routes` | `Partial<FinRoutes>` | `automation(id)`, `orders()` and `assets()`, `contacts()` for your own contacts page, `asset(asset)` for a token's page and `transaction(network, id)` for your explorer's page for one transaction. Unset routes keep near.com's paths. |
| `tokens` | `TokenResolver` | What each token looks like. Defaults to `DEFAULT_TOKENS`. |
| `children` | `ReactNode` | The part of your app that draws Fin's blocks. |

A `LinkComponent` takes `LinkProps`: `href`, `className`, `children` and an anchor's other
attributes, as Next.js's `Link` does. `DEFAULT_ROUTES` holds near.com's paths:
`/agent/automations/<id>`, `/agent/orders` and `/agent/assets`. It has no `contacts()`: the
contacts are your app's, so the contacts card links only where you name your page.

It has no `asset()` either. Name it, and every token Fin draws in a conversation links to your
page for it: a card's token (a holding, a swap's two sides, a receipt, a price, a comparison) and
a ticker in a reply. It receives an `AssetRef`, `{ symbol, tokenId }`, with `tokenId` set where
the card knows which token it is, and returns your page, or `undefined` for a token you have none
for, which then draws as plain text. A Solana token's `tokenId` is `solana:<mint>`. The link keeps the token's look, with no colour of its own,
and underlines on hover and keyboard focus; its accessible name says the token, then
"open its page". Its part is `asset-link`. The user's own messages are yours to draw, so nothing
in them links. Unset, the blocks draw exactly as before.

`transaction(network, id)` is your explorer's page for one transaction, which a Solana receipt
links each of its transactions to (`network` is `solana`, `id` the signature). A block never
hard-codes an explorer, so there is no default: unset, the receipt shows each signature shortened
with a button that copies it whole.

```tsx title="fin-chat.tsx"
import { FinUIProvider } from "@nearai/financial-agents-react";
import type { ReactNode } from "react";

/** The tickers your app has a market page for. */
const MARKETS = new Set(["NEAR", "BTC", "ETH", "USDC"]);

export function FinChat({ children }: { children: ReactNode }) {
  return (
    <FinUIProvider
      link={Link}
      routes={{ asset: ({ symbol }) => (MARKETS.has(symbol) ? `/markets/${symbol}` : undefined) }}
    >
      {children}
    </FinUIProvider>
  );
}
```

### `useFinUI()`

The nearest provider's `FinUIConfig`, `{ tokens, link, routes }`, with defaults where there is no
provider. Use it so your own markup links the way Fin's blocks do.

### `configureFinUI(configuration)`

Sets the tokens and routes the view models read outside React, such as on a server.
`FinUIProvider` calls it for you; `tokens()` and `routes()` return what is set.

### `DEFAULT_TOKENS`, `RENDERED_CARDS`

`DEFAULT_TOKENS` is near.com's token list as a `TokenResolver`; see
[Tokens and chains](/tokens-and-chains). `RENDERED_CARDS` names the result cards, for
`context.renders`.

## Types

| Kind | Types |
| --- | --- |
| Props | `ActivityGroupProps`, `ApprovalCardProps`, `AssetIconProps`, `AutomationCardProps`, `ComparisonCardProps`, `ContactsCardProps`, `ContractTermsProps`, `FinEntryProps`, `FinUIProviderProps`, `HoldingsCardProps`, `MemecoinsCardProps`, `MessageMarkdownProps`, `NextStepsProps`, `OrdersCardProps`, `PendingApprovalChipProps`, `PerpsFiringCardProps`, `PredictionMarketCardProps`, `PredictionPreviewCardProps`, `PredictionsCardProps`, `PriceCardProps`, `QuestionCardProps`, `RunFooterProps`, `RunProgressProps`, `RunReceiptProps`, `SettlementReceiptProps`, `SolanaHoldingsCardProps`, `SolanaReceiptProps`, `SolanaTokenCardProps`, `TokenCandidatesCardProps`, `TokenIconProps`, `ToolCallCardProps`, `VaultsCardProps`, `WalletCardProps` |
| Part names | `ApprovalCardPart`, `AutomationCardPart`, `ComparisonCardPart`, `ContactsCardPart`, `HoldingsCardPart`, `MemecoinsCardPart`, `MessageMarkdownPart`, `OrdersCardPart`, `PerpsFiringCardPart`, `PredictionMarketCardPart`, `PredictionPreviewCardPart`, `PredictionsCardPart`, `PriceCardPart`, `QuestionCardPart`, `RunFooterPart`, `RunProgressPart`, `RunReceiptPart`, `SettlementReceiptPart`, `SolanaHoldingsCardPart`, `SolanaReceiptPart`, `SolanaTokenCardPart`, `TokenCandidatesCardPart`, `ToolCallCardPart`, `VaultsCardPart`, `WalletCardPart`, and `PartClassNames<Part>` for a `classNames` prop |
| Variants and loaders | `QuestionCardVariant`, `OptInResultCard`, `PriceRange`, `PriceHistoryLoader`, `SolanaTokenLoader` |
| Handlers and data | `ApprovalHandlers`, `QuestionHandlers`, `FeedbackHandlers`, `RunFooterFeedback`, `RunRating`, `ControlTooltip`, `RuleConflict`, `AgentHolding`, `PendingApproval`, `RunItem`, `ToolItem` |
| Grids | `GridBandProps`, `GridCardProps`, `GridBandPart`, `GridCardPart`, `GridHandlers`, `GridAction` |
| Configuration | `FinUIConfig`, `FinRoutes`, `AssetRef`, `LinkComponent`, `LinkProps`, `TokenInfo`, `TokenResolver` |

The data the props take (`ThreadState`, `TranscriptEntry`, `ApprovalView`, `ExecutionView`,
`ActivityStep`, `ReplyContext`, `AutomationReceipt`, `WalletReading`, `LimitOrderView`,
`ContactsLookup`, `PriceHistory`, `MarketComparison`, `PricePoint`, `EarnVaults`, `PredictionSearch`, `PredictionMarketDetail`, `PredictionPreview`, `SolanaTokenSearch`, `SolanaTokenList`, `SolanaTokenDetail`, `SolanaAccountRead`, `RunProgressView`, `RunReceiptView`, `SolanaReceiptView`, `PortfolioHolding`, `PricedHolding`, `TermRow`, `GridBandCell`) comes from [`@nearai/financial-agents-react/model`](/react-model); Fin's
resources (`Approval`, `Automation`, `Grid`, `Question`, `EventPayload`) from
[`@nearai/financial-agents-sdk`](/sdk-reference#types).
