Guides

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>
QueryWhat it is
surfaceThe page asking: home (the default), orders, automations, swap, earn, or one asset's page as asset: and its assetId from Get balances. Home gets every kind of move; a page gets the moves that belong on it.
timeZoneThe 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.
countryThe 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.
perpsAllowedtrue 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

FieldWhat it is
idThe suggestion's id. The same move in a later read keeps it.
titleThe move, verb first, with its exact terms, written by Fin: "Move your NEAR buy to $4.80".
reasonWhy, in one sentence. Fin filled in every figure from the account.
reviewThe terms the move's review draws, keyed by kind.
surfacesThe pages it belongs on.
expiresAtWhen 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.kindHow the user makes it
swapGet a swap quote for the chosen amount, then Swap tokens.
limit_orderPrepare an order with the chosen option's order, then Place an order.
order_moveCancel the order, then prepare and place the chosen option's order, in the order below.
order_cancelCancel the order.
automation_pause, automation_resumePause or Resume the automation.
automation_endDelete the automation.
depositYour deposit flow, for the chosen amount: Create a deposit.
withdrawGet a withdrawal quote, then Withdraw funds, to the user's own wallet: the one your app has connected. Fin names no destination.
recurring_buy, price_rule, summary, automation_change, perps_fundStart a run asking the agent for it with the chosen terms, as the user's own message; the user approves it in chat.
askStart a run 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 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. 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. 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 shows it ended and Get 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 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.

Fin documentation Built from the API contract · v1

Search all documentation