Packages

Packages quick reference

The calls you use most from both packages, on one page.

Server SDK

fin is the client from createFinClient, and user is fin.user({ userId, token }). Recipes explain each task; the reference lists every method.

Users and sessions

TaskCall
Create the clientcreateFinClient({ baseUrl, apiKey })
Create a user, oncefin.users.create({ userId, name })
Sign in after your own loginfin.users.createSession(userId, { controller })
Sign in with the user's walletfin.users.sessionChallenge(userId, { controller, origin }), then fin.users.createSession(userId, { challengeId, signature })
Sign in and create the wallet with one signaturefin.users.sessionChallenge(userId, { controller, origin, createWallet: true }), fin.users.createSession(…), then user.wallets.create({ signIn: { challengeId, signature } }) when createsWallet
Open the account with a passkey your login just createdfin.users.createSession(userId, { controller, createWallet: true }), then user.wallets.create({}) when createsWallet
Act as the userfin.user({ userId, token })
Check a sessionfin.users.me({ token })
Sign outfin.users.revokeSession({ userId, sessionId, token })

Conversations and runs

TaskCall
Find the conversationuser.conversations.main()
Send a messageuser.runs.start({ conversationId, text, context }, { idempotencyKey })
Follow it livefor await (const event of user.events.stream(conversationId, { signal }))
Read its historypaginate((cursor) => user.events.list(conversationId, cursor ? { cursor } : {}))
Stop a runuser.runs.cancel(runId)
Send feedback on a replyuser.runs.sendFeedback(runId, { rating: "down", reason: "wrong" }) once the run has ended; delete it with user.runs.deleteFeedback(runId)

Approvals and questions

TaskCall
Check a message before the user signsisAuthorizationFor(await fin.users.me({ token }), audience, toSign)
Approveuser.approvals.approve(approvalId, { authorization })
Denyuser.approvals.deny(approvalId, {})
Answer a questionuser.questions.answer(questionId, { kind: "answers", answers }, { idempotencyKey })

Agent wallet and automations

TaskCall
Create the walletuser.wallets.get() for creation, then user.wallets.create({ authorization }), or { signIn } after an account-opening sign-in, or {} from a session that opened the account with a new passkey
Read balancesuser.wallets.balances()
Read everything it ownsuser.portfolio.get()
Chart its valueuser.portfolio.history({ range: "1W" })
Price a deposituser.wallets.quoteDeposit({ rail, network, assetId, amountRaw, maxValueLossBps })
Fund ituser.wallets.createDeposit({ terms }, { idempotencyKey })
Withdrawuser.wallets.quoteWithdrawal(request), then user.wallets.withdraw({ terms, authorization }, { idempotencyKey: quote.requestKey })
Swapuser.wallets.quoteSwap(request), then user.wallets.swap({ terms, authorization }, { idempotencyKey: quote.requestKey })
Place a limit orderuser.wallets.prepareOrder(request), then user.wallets.placeOrder({ terms, authorization }, { idempotencyKey: prepared.requestKey })
Pause or resume an automationuser.automations.pause(id), user.automations.resume(id)
Handle a refusalif (error instanceof FinApiError) error.reason

React components

The quickstart puts these together; the components and view models references list everything.

Set up

TaskUse
Load the stylesimport "@nearai/financial-agents-react/styles.css"
Order the layers in a Tailwind app@layer theme, base, fin, components, utilities; above @import "tailwindcss"
Configure links and routes<FinUIProvider link={Link} routes={{ automation, orders, assets }}>
Use your own token list<FinUIProvider tokens={resolver}>, or wrap DEFAULT_TOKENS

Draw the conversation

TaskUse
Fold the eventsuseReducer(threadReducer, initialThread), then dispatch(event)
List what to drawtranscriptEntries(thread), keyed by entryKey(entry)
Draw the agent's text<MessageMarkdown text={text} context={context} /> with replyContext(thread.items)
Draw live text<MessageMarkdown text={thread.streamingText} streaming />
Draw everything that is Fin's<FinEntry entry={entry} thread={thread} approvals={handlers} />
Keep one approval open at a timewrap the transcript in <ApprovalExpansionProvider>
Offer the suggested replies<NextSteps steps={splitReplyNextSteps(text).nextSteps} onPick={send} />
Let the cards carry the factssend RENDERED_CARDS as context.renders
Show cards as the agent finds what it needsadd show (or placement) to context.renders, draw threadTurns(thread)
Report the user's countrysend context.country from your server's edge geolocation with every message; see Tokenized stocks for country and purchase restrictions

Style and test

TaskUse
Retheme--fin-* variables on :root
Restyle one blockclassName, and classNames for its parts
Restyle every buttonCSS on [data-fin-ui="button"][data-fin-variant="primary"]
Draw your own approvalapprovalContent(approval)
Show a token<TokenIcon symbol iconUrl network={assetChain(tokenId)} />, or <AssetIcon asset={holding} />
Draw states in stories and testsfoldFixture("approvalPending"), oneShotApproval(contract) from /fixtures
Fin documentation Built from the API contract · v1

Search all documentation