# Suggestions

Fin reads each user's whole account in the background and suggests the moves worth making on
it: an order to move, renew or cancel, an automation to pause, resume, change or end, and money to
swap, protect with a sell line, put on a schedule, deposit or withdraw. Each suggestion carries the
exact terms of its review, which Fin computed from the account. Suggestions are available to every
user.

The model decides what is worth suggesting, and often that is nothing. Fin checks every move it
proposes before anyone sees it: the order, automation or holding is the user's own and in a state
that allows the move, the amount fits what they hold, a schedule stays covered for four weeks, and
a price sits on the right side of the market. Fin writes the title and fills in every figure of the
reason from the account itself. A suggestion moves no money: the user makes each move through the
routes that make it, where money still needs their approval.

## Read a page's suggestions

```http
GET /v1/users/{userId}/suggestions?surface=orders&timeZone=Europe%2FLondon&country=GB&perpsAllowed=false
X-Api-Key: fin_…
Authorization: Bearer <session token>
```

| Query | What it is |
| --- | --- |
| `surface` | The page asking: `home` (the default), `orders`, `automations`, `swap`, `earn`, or one asset's page as `asset:` and its `assetId` from [Get balances](/api-reference/wallets/balances). Home gets every kind of move; a page gets the moves that belong on it. |
| `timeZone` | The user's IANA time zone. Dates and run times read in it; without it they read in UTC and no suggestion starts a new schedule. |
| `country` | The country the user is reading from, as your server resolved it. A move on a tokenized stock shows only where stocks are available; without a country, none shows. |
| `perpsAllowed` | `true` when your app lets this user fund perpetuals where they are now; without it, no perps move shows. |

Send all three with every read. They apply to that read only, and Fin never stores them.

A read answers at once and never waits on the model:

- `ready`: show `suggestions`, at most three, best first. With none, `calm.watching` counts the
  orders and automations Fin keeps an eye on, for a quiet line such as "Nothing needs you". When
  `updating` is `true`, something changed and Fin is reading the account again; what it shows
  still holds.
- `thinking`: Fin is reading an account it has nothing saved for yet. Read again in a few seconds.
- `failed`: Fin could not read the account. When `retryable` is `false`, the user's AI budget
  (`budget_exhausted`) or the hourly limit (`rate_limited`) stopped it, and trying again now
  changes nothing: say so and offer no Try again. When it is `true` (`model_unavailable`,
  `model_timeout` or `invalid_output`), a later read tries again. An answer Fin could not read
  is tried once more at once, so `invalid_output` means neither answer could be used; the page
  reads `thinking` while the second try runs.

While a visible page shows `thinking`, or `updating` is `true`, read again every few seconds.

## When Fin reads the account again

Fin keeps one set of suggestions per account and reads the account again when something a
suggestion depends on changes: a holding's amount, an order or automation placed, filled, edited,
paused or cancelled, a deposit under way, the user's deposit limit or one of their features.
Prices alone never start a read. Each suggestion holds while the prices it uses stay within 5% of
where they were; one that leaves that band is hidden and starts a read. A set lasts 24 hours, and
Fin keeps the suggestions of anyone who read theirs in the last day current in the background, so
most visits find them ready.

## Budget and limits

Reading suggestions costs nothing. Each time Fin reads an account again, its one model call
reserves a few cents from the user's AI budget before it is made, like a chat message, and settles
what it cost; it counts toward your account's spend caps too. Fin reads an account at most once a
minute, and its reads count toward the user's 30 an hour and 200 a day. When the budget or those limits stop a read, the page keeps the suggestions
that still hold; with none left, it answers `failed` with `retryable: false`. These limits never
answer `429` here.

## Show a suggestion

| Field | What it is |
| --- | --- |
| `id` | The suggestion's id. The same move in a later read keeps it. |
| `title` | The move, verb first, with its exact terms, written by Fin: "Move your NEAR buy to $4.80". |
| `reason` | Why, in one sentence. Fin filled in every figure from the account. |
| `review` | The terms the move's review draws, keyed by `kind`. |
| `surfaces` | The pages it belongs on. |
| `expiresAt` | When it is no longer served. |

Every value in `review` is exact. An amount is `{ asset, amountRaw }`, with the asset's `assetId`,
`symbol` and `decimals` and the amount in its smallest unit; dollars are decimal text such as
`"4.80"`; a share is whole basis points; an instant is RFC 3339. The one figure the review lets the
user adjust with − and + is `{ options, suggested }`: every value a step reaches, lowest first, at
most 25, each with what follows from it, opening on `options[suggested]`. Draw the review from
these values and step between options; compute nothing yourself.

## Open its review

When the user opens a suggestion, check it again:

```http
GET /v1/users/{userId}/suggestions/{suggestionId}/review?timeZone=Europe%2FLondon&country=GB
```

It answers the suggestion with fresh terms from the account as it is now. When it answers
`409 suggestion_changed`, the suggestion no longer holds: the account or a price moved, the user
set it aside, or it can't be made where the user is now. Say it changed since Fin suggested it,
and read the page's suggestions again.

## Make the move

| `review.kind` | How the user makes it |
| --- | --- |
| `swap` | [Get a swap quote](/api-reference/wallets/quote-swap) for the chosen amount, then [Swap tokens](/api-reference/wallets/swap). |
| `limit_order` | [Prepare an order](/api-reference/wallets/prepare-order) with the chosen option's `order`, then [Place an order](/api-reference/wallets/place-order). |
| `order_move` | Cancel the order, then prepare and place the chosen option's `order`, in [the order below](#move-or-renew-an-order). |
| `order_cancel` | [Cancel the order](/api-reference/wallets/cancel-order). |
| `automation_pause`, `automation_resume` | [Pause](/api-reference/automations/pause) or [Resume](/api-reference/automations/resume) the automation. |
| `automation_end` | [Delete the automation](/api-reference/automations/delete). |
| `deposit` | Your deposit flow, for the chosen amount: [Create a deposit](/api-reference/wallets/create-deposit). |
| `withdraw` | [Get a withdrawal quote](/api-reference/wallets/quote-withdrawal), then [Withdraw funds](/api-reference/wallets/withdraw), to the user's own wallet: the one your app has connected. Fin names no destination. |
| `recurring_buy`, `price_rule`, `summary`, `automation_change`, `perps_fund` | [Start a run](/api-reference/runs/start) asking the agent for it with the chosen terms, as the user's own message; the user approves it in chat. |
| `ask` | [Start a run](/api-reference/runs/start) with `question` as the user's own message. |

### Move or renew an order

The old order holds the funds the new one needs, and [Prepare an order](/api-reference/wallets/prepare-order)
checks the agent wallet's balance, so prepare the new order only once the old one is cancelled and
its funds are back:

1. Check the suggestion again with [Get a suggestion's review](/api-reference/suggestions/review).
   On `409 suggestion_changed`, say it changed since Fin suggested it.
2. Tell the user that nothing rests between the cancel and the new order, then
   [cancel the order](/api-reference/wallets/cancel-order). On `409 order_not_cancelable`, read
   the order: if it expired, the cancel is done, so go on; if it filled, stop and say so.
3. Wait until [Get an order](/api-reference/wallets/get-order) shows it ended and
   [Get balances](/api-reference/wallets/balances) shows its funds back, reading every few
   seconds. If it partly filled, less comes back: prepare with what came back, or check the
   suggestion again.
4. Prepare the chosen option's `order`.
5. Check the prepared terms against the option the user chose: the amount, the limit price, the
   least they receive and the expiry.
6. Have the user's wallet sign the authorization.
7. [Place the order](/api-reference/wallets/place-order) with its request key. On
   `409 order_changed` because the funds are not back yet, send the same request again once they
   are, while its signature holds; after that, prepare and sign again.

At the order's own price (`current.limitPriceUsd`) this renews it, with a fresh expiry.

## Not now

```http
POST /v1/users/{userId}/suggestions/{suggestionId}/dismiss
```

It answers `204`. Fin stops suggesting that kind of move on that order, automation or asset until
it changes or seven days pass, and later reads leave it out. Sending it again changes nothing.

With `@nearai/financial-agents-sdk`, these are `suggestions.list`, `suggestions.review` and
`suggestions.dismiss`; see [the recipe](/sdk-recipes#show-suggestions-on-a-page).
