# How Fin works

The pieces of Fin, what each one is for, and how they fit together.

## Users and their agent

You create a **user** with your own `userId`, and every path names them by it. The same
`userId` under another partner is a different user. Each user gets one **agent** and one
**main conversation** when you create them.

A **session** lets your backend act for a signed-in user for up to an hour. It is separate from
the user's wallet signature, which is what money needs; see the
[security model](/authentication#security-model).

## Conversations and runs

A **conversation** is a chat thread between the user and their agent. It keeps every message,
run and approval. The main conversation is where single-chat apps send everything; create more
for separate topics, and delete one the user no longer wants: it leaves their list, its history
stays readable, and it takes no new messages. Deleting the main conversation gives the user a new,
empty one, so read the main conversation again after a delete rather than keeping its id.

A **run** is the agent working on one message. You start it with the user's text and it answers
`202` straight away; the work happens in the background. A run moves through these statuses:

| `status` | Meaning |
| --- | --- |
| `running` | The agent is working. |
| `paused` | Waiting for an approval decision or answers to the agent's questions. |
| `completed` | Finished. `response.text` holds the reply. |
| `failed` | Ended with an error. |
| `aborted` | Cancelled, or a pending approval or questionnaire expired. |

A run keeps its id while it pauses and resumes. Call [Get a run](/api-reference/runs/get) at
any time to catch up; it returns the original message, the status, the reply,
`pendingApprovals` and `pendingQuestions`. `output` holds structured output when you asked for one with
`profile.outputContract`; it is separate from the text reply.

`origin` names the automation that started a run: its `automationId`, the automation run it
carried out (`automationRunId`) and the automation's `name`; it's `null` for a run the user started
with a message. `reads` says what the agent read while it worked, by the tools whose calls
completed: `account` (the user's own balances, holdings, orders or positions) and `prices`
(market prices). It's empty when the agent read neither. Use both to show the agent's activity,
such as an automation run that moved no money.

The agent sees the conversation's history, up to the model's context window.

### Feedback on a reply

The user can send feedback on a run's reply with a thumb. Once the run has ended (`completed`,
`failed` or `aborted`), call [Send run feedback](/api-reference/runs/send-feedback) with
`{ "rating": "up" }`, or `{ "rating": "down" }` with an optional `reason`. A run that is still
working or waiting (`running` or `paused`) answers `409 run_active`; wait for `run.ended`. The
reason is one of a fixed list and never free text:

| `reason` | The reply was |
| --- | --- |
| `wrong` | Incorrect. |
| `unhelpful` | Not what the user asked for. |
| `slow` | Too slow. |
| `unsafe` | Risky or inappropriate. |
| `other` | None of these. |

A reason goes with `down` only; with `up` the request is refused with `400 invalid_input`. A run
has one set of feedback. Sending again replaces it, so the same call changes it and a retry is
safe, and [Delete run feedback](/api-reference/runs/delete-feedback) deletes it. Get a run and
List runs return it as `feedback` (`rating`, `reason`, `createdAt`, `updatedAt`), `null` until
there is any, so a page that reloads can show the thumb the user chose. A run that is not the
user's answers `404`, as for any other run. Feedback changes nothing about the run and needs no
approval or signature. Fin's operators see feedback in totals and by reason, and can open a run
that got a thumbs-down to see what happened, so tell users that a thumbs-down may be reviewed.

### Sending a message while the agent works

A conversation has one run at a time: starting another while a run is `running` or `paused`
answers `409 run_active`. A user who types while the agent works has two choices, and your chat
offers either or both:

- **Queue it.** Keep the message in your app and send it with Start a run once `run.ended`
  arrives. The queue is yours: order it, let the user edit or delete what waits, and send one
  message per run. Pause it after a run ends `aborted` or `failed` rather than sending into the
  same trouble.
- **Steer the run.** Call [Steer a run](/api-reference/runs/steer) with `{ "text": … }` and the
  run's id from `run.started`. The agent reads it at its next step, in the same run: it answers
  `202` with the run, the message listed in `steers` as `pending`, and `run.steered` (with the
  message's `steerId`) lands in the conversation where the agent read it. Send an
  `Idempotency-Key` (a UUID) so a retry sends it once.

While a message waits, the agent finishes what it is doing but starts nothing that would need
the user, and nothing destructive: a call that needs an approval, cancels an order, archives an
automation or asks a question is skipped, so nothing acts and no card opens on top of a message
the agent has not read. If the run is waiting on an approval when the message arrives,
the message declines it: the approval is denied with the reason "The user sent a new message
instead." and nothing it proposed runs. If it is waiting on a question, the question is skipped.
Either way the run carries on with the message. A message never approves anything, however it is
worded.

A run that has ended, or is finishing, answers `409 run_not_active`: send the text with Start a run
instead. If the run ends before the agent reads a message (the user stops it, or it fails), the
message is `dropped` in `steers` and never gets a `run.steered`; put it back in front of the user.
Steering is off unless Fin turns it on for your users: until then the call answers
`403 steering_disabled`, and queueing still works.

### Talking instead of typing

A user who would rather say what they want than type it can record it. Call
[Get voice input](/api-reference/voice/get) first and show a microphone only while `status` is
`available`; `disabled` means voice input is not turned on for the user, and `unavailable` that
the deployment has no speech model. Record at most `maxSeconds` (a minute) and send it in one of
`formats`, the types the deployment's speech model decodes. NEAR AI's Whisper takes `audio/ogg`
with Opus (what Firefox records) and `audio/wav`, not the WebM Chrome, Edge and Safari record or
the MP4 older Safari records, so a page in those browsers converts its recording to WAV first: decode it with
Web Audio and write 16-bit mono PCM, where 16 kHz keeps a minute under 2 MB. Send the bytes to
[Transcribe a recording](/api-reference/voice/transcribe) with that type as `Content-Type`; any
other type is refused with `400` before anything is charged. Each format has its own `maxBytes`, a
minute of it with room to spare: 1.5 MiB of compressed speech, 6 MiB of WAV. Fin waits up to a minute for its speech model, so give the call
75 seconds before giving up; one abandoned sooner is still charged. It answers `{ "text": … }`:
put it where the user writes, at their cursor, for them to read, change and send with Start a run,
or Steer a run while the agent works. Nothing reaches the agent until they send it, so a misheard
word is theirs to fix first. An empty `text` means no speech was heard: say so and let them try
again.

The recording goes to the deployment's own model provider, never the browser vendor's speech
service, and Fin keeps neither the audio nor the text. Each transcription is an AI model call on
the user's budget: `429 budget_exhausted` when it has no room, `429 rate_limited` with
`Retry-After` past the user's hourly or daily transcriptions, `413` over the format's `maxBytes`,
and `503 provider_unavailable` when the speech model did not answer, which is worth one retry of
the same recording. `403 voice_disabled` and `503 voice_unavailable` mean the microphone should not
be shown.

## Approvals

When the agent wants to take an action that needs the user's OK, the run pauses and an
**approval** opens. It lists exactly what the action will do. Show that to the user and send
their decision; the run then resumes on its own. A money action also needs the user's
signature on the approval's `authorization.message`. The agent can propose a withdrawal too:
to the user's main wallet, or to an exact address the user gives. That address must be one the
user sent with this message: in its text, in a typed answer to the agent's question, or among
the `context.contacts` sent with it. An address that appeared only in something the agent read
opens no approval; the agent asks the user instead. Its approval names the full destination,
and once approved it cannot change.

Every approval keeps its `fingerprint`, the SHA-256 digest of exactly the action it decides. An
approved money action also names the sign-in wallet that signed it, in `signedBy`. To show one
chat's approvals, decided or not, list them with `status=all&conversationId=…`.

## Questions

The agent can ask for missing preferences using `ask_user_tool`: one card with one to five
questions, each with two to six options. It asks only for what has no default: a recurring
buy that names no time runs at 9:00 AM in the user's time zone and ends after 30 days, and
its approval card shows both. Show one question at a time; a tap on a single-choice option
can answer it and move on. Allow multiple selections only when `multiple` is true, and offer
custom text instead of the listed choices. Submit the answers together after the last
question, leaving out any the user skipped, or skip the whole card. The same run resumes
afterward.

An option may carry `description`, one line on what it means, and at most one option per
question is `recommended`, with why in its description; show the recommendation, never preselect
it. A choice between ways to buy may carry `picture`, a small drawing to show over it: `schedule`
for a regular buy, `dip` for buying only after a fall, `once` for one buy now. It is a hint only:
an app that draws none shows the same choices as text. A question with
`amount: { min, max, step, unit }` asks for one amount: `min`, `max` and `step` are decimal
strings, `unit` is `usd` or a token symbol, and its options are presets whose values are decimal
strings within the bounds. Offer a slider between `min` and `max` in steps of `step`; answer a
preset with its value, and any other amount as `customText`, a plain decimal in that unit
(`"130"`). An amount question never sets `multiple`.
Questions expire after 24 hours; cancelling the run closes them too.
An answer supplies information, never approval or permission to spend.

## Contacts

Send the user's saved contacts in `context.contacts` when you start a run, so the agent can
resolve "send 5 USDC to Alice" to a saved address. Each contact is `{ id, name, address,
network }`, with `network` in your app's own naming (`eth`, `base`, `near`, `near_intents`).
A message carries at most 200 contacts in 64 KiB; `name` is up to 64 characters, `id` and
`address` up to 128 printable ASCII characters without spaces, and `network` up to 32 lowercase
characters. Unknown fields, repeated ids or anything over a limit refuse the whole request with
`400 invalid_input`, and no run starts.

Contacts belong to that one message. The agent reads them through its `contacts_list` tool;
a later message without them has none, and the agent asks the user for an address instead of
reusing an earlier one. Read them from your own server for every message rather than trusting
what the browser sends. A retry with the same `Idempotency-Key` answers the run the first
attempt started, with that attempt's contacts, even when the list changed in between.
Names and addresses are treated as untrusted data: when several
contacts match, none does, or the contact's network does not fit the asset, the agent asks the
user. A contact authorizes nothing. Any action that pays an address still opens an approval
showing the exact address and network, and the user decides there.

When the user asks who is saved, the lookup's result is the list. Draw it as a card and add
`contacts` to `context.renders`, and the reply leaves the names and addresses to the card
([Render a reply](/streaming#render-a-reply)).

## Perps availability

Send `context.perpsAllowed: true` or `false` when you start a run to report whether your
server's current region policy permits that user to add perpetual-futures exposure. Compute
it on your trusted server; do not accept a browser-selected value. The report belongs to that
message and is saved with its observation time. Omitting it on a new message reports no
current permission and leaves the user's latest saved observation unchanged.

Unlike contacts, this value is part of retry identity. Retry with the same `Idempotency-Key`
and the same value to receive the original run without refreshing its observation time.
Changing the value, adding it or omitting a previously supplied value under the same key
answers `409 request_key_conflict`; start a new run with a new key for a new report.
The latest observation wins by observation time, not by which request finishes last.
This flag never authorizes spending or replaces financial approval. Account reads do not
depend on a region report; withdrawing remains an exit rather than permission to grow exposure.

## Tokenized stocks

Send `context.country` with every message, using the user's country from your server's edge
geolocation, not a browser-supplied value. It is an uppercase two-letter ISO 3166-1 country code,
such as `GB`. Leave it out when geolocation is unavailable; without a country, Fin refuses
tokenized-stock trades.

Ondo's tokenized U.S. stocks and ETFs are offered only for messages reporting a country outside
the United States (`US`) and Canada (`CA`), and purchases also require an operator to enable
`tokenized_stocks` for the user. Selling existing holdings does not require that flag, but still
requires an allowed country. These assets can never be withdrawn or sent to another wallet,
only sold. Enabling the flag does not override the country restriction.

Country belongs to that one message. A retry with the same `Idempotency-Key` answers the run the
first attempt started, with that attempt's country, even if geolocation changed in between.

A swap or limit order the user makes from your own screen takes the same fact for that one
request: send `context.country` with Get a swap quote and again with Swap tokens, or with Prepare
an order and again with Place an order, to trade a tokenized stock. Fin checks it on arrival and
keeps it nowhere. A retry that finds its swap or order needs none.

## Money

The agent has its own **wallet**, which the user creates with one signature.

- A **deposit** funds the wallet from an address the API gives you.
- A **withdrawal** sends funds out, after a quote and the user's signature. The agent can also
  propose one in a run; the user approves and signs it like a trade.
- A **trade** is made by the agent during a run, with the user's approval.
- A **limit order** is a trade that waits at the provider for its price. The agent places one
  with the user's approval, or the user places one from your own screen with their signature.

Each has its own record with a status and receipts. A reply from the agent or a finished run
never proves money moved: read the deposit, withdrawal, trade or order.
[Deposits, withdrawals and trades](/wallet-transfers) covers all of them.

## Automations

An **automation** is a task the agent runs on its own, on a schedule, when a condition becomes
true, or when your system sends an event. The user creates it by asking the agent. Each time it
runs it starts a fresh conversation. It can trade without asking each time only within limits
the user signed for it when it was created. New automations with those trading limits are
restricted to clock or first-entry-swap-pair 1Click triggers,
with a reviewed push-only exit exception. Only `kraken.asset_price` and
`consensus.asset_price` readers with `delivery: "push"` may be referenced exclusively
by `rule.exit.push.readers`; their asset/quote pair must match each exit action's
pinned input/output tokens. They cannot appear in the entry condition at any depth
or in either operand, or in `reader_update` wakes. Entry and unused readers remain
pinned-token 1Click readers; entry conditions/update wakes use the first entry
swap's quoted pair, and webhook/event wakes are refused. Any trading contract's
entry condition may also read another venue the policy worker reads itself, on a
clock; see [cross-venue triggers](automations.md#cross-venue-triggers). Push feeds only decide
when a contract-backed exit gets checked. Fin independently checks the guard
against the signed quote's fee-neutral ratio of per-token USD prices, not net
executable amounts; entry conditions use those same exact USD prices.
Clock-only entries with no price condition use the quote's signed timestamp
instead of its prices. A payout-only schedule uses a dry canonical USDC → wNEAR
reference preview as time evidence; it does not add a trade or change the payout.
There is no tolerance band, and freshness and scheduled wakes use Fin's trusted
clock. An outage cannot authorize a trade and leaves work
eligible for a later check. Automations without a contract retain their source and
event support without permission to spend. See [Automations](/automations).

Fin proves the current condition, not a “becomes true” trigger's prior transition.
That history remains scheduler-side, bounded by independently enforced
once-only/run-count/cooldown and financial limits.

## Suggestions

**Suggestions** are the moves Fin suggests on the user's whole account: an order to move or cancel,
an automation to pause or change, money to swap, protect or put on a schedule. Fin reads the account
in the background whenever it changes, checks every move the model proposes against what the user
holds, fills in every figure itself and computes each move's exact review terms. Pages read them at
once, each getting the moves that belong on it; each read of a changed account spends one small
model call from the user's AI budget. Every user has them. A suggestion moves no money and starts
no run. See [Suggestions](/suggestions).

## Notifications

A **notification** is one thing Fin tells the user while they are away: an approval or a question
waiting for them, an automation's report, money that moved, a problem with an automation, or the
agent's reply in a chat they left. Each has its text ready to show and a read state shared by every
device. Your app shows them in an inbox with the user's session, and your server reads every
user's notifications from one feed with your key to ping their devices. A notification grants
nothing: opening one leads to what it is about. See [Notifications](/notifications).

## Events

Everything that happens in a conversation is saved as an **event**: messages, runs, approvals
and trade updates. Read them as pages or follow them live on a stream; see
[Streaming and events](/streaming). Fin never calls your servers.

## Budgets and limits

Running the agent costs AI usage. Each user has a daily and monthly **budget** for it, and your
partner account has shared limits on requests, runs, streams and spend. These are separate from
the money in the user's wallet. See [Usage and limits](/usage-and-quotas).

A budget or spend limit can stop work at two moments:

- **Before a run starts**, Fin refuses the message with `429 budget_exhausted`: the user's budget
  has nothing left, or an operator froze it.
- **While a run is working**, its next model request can find a limit with no room for it. The
  run ends `failed`, and `failure.code` on its `run.ended` event (and on
  [Get a run](/api-reference/runs/get)) names the limit, so your app can say why instead of
  showing a model error:

| `failure.code` | What has no room | Clears |
| --- | --- | --- |
| `daily_budget_exhausted` | The user's budget for today. | At midnight UTC, or at once when an operator raises it. |
| `monthly_budget_exhausted` | The user's budget for this month. | At the start of next month (UTC), or at once when an operator raises it. |
| `budget_frozen` | An operator froze the user's budget. | At once, when the operator lifts the freeze. |
| `partner_daily_budget_exhausted` | Your partner account's spend limit for today. | At midnight UTC. A raised limit applies from the next UTC day. |
| `partner_monthly_budget_exhausted` | Your partner account's spend limit for this month. | At the start of next month (UTC). A raised limit applies from next month. |

A limit stopped the run; the model did not fail. What the run already did stands, a trade the
user approved included, so read their trades and receipts before they ask again. A request is
refused when what is spent and reserved, plus the most it could cost, would pass the limit, so a
limit can clear a little early when another run's reservation settles. Sending the message
again ends the same way, or is refused with `429 budget_exhausted`, until the limit clears.
