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
| Task | Call |
|---|
| Create the client | createFinClient({ baseUrl, apiKey }) |
| Create a user, once | fin.users.create({ userId, name }) |
| Sign in after your own login | fin.users.createSession(userId, { controller }) |
| Sign in with the user's wallet | fin.users.sessionChallenge(userId, { controller, origin }), then fin.users.createSession(userId, { challengeId, signature }) |
| Sign in and create the wallet with one signature | fin.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 created | fin.users.createSession(userId, { controller, createWallet: true }), then user.wallets.create({}) when createsWallet |
| Act as the user | fin.user({ userId, token }) |
| Check a session | fin.users.me({ token }) |
| Sign out | fin.users.revokeSession({ userId, sessionId, token }) |
Conversations and runs
| Task | Call |
|---|
| Find the conversation | user.conversations.main() |
| Send a message | user.runs.start({ conversationId, text, context }, { idempotencyKey }) |
| Follow it live | for await (const event of user.events.stream(conversationId, { signal })) |
| Read its history | paginate((cursor) => user.events.list(conversationId, cursor ? { cursor } : {})) |
| Stop a run | user.runs.cancel(runId) |
| Send feedback on a reply | user.runs.sendFeedback(runId, { rating: "down", reason: "wrong" }) once the run has ended; delete it with user.runs.deleteFeedback(runId) |
Approvals and questions
| Task | Call |
|---|
| Check a message before the user signs | isAuthorizationFor(await fin.users.me({ token }), audience, toSign) |
| Approve | user.approvals.approve(approvalId, { authorization }) |
| Deny | user.approvals.deny(approvalId, {}) |
| Answer a question | user.questions.answer(questionId, { kind: "answers", answers }, { idempotencyKey }) |
Agent wallet and automations
| Task | Call |
|---|
| Create the wallet | user.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 balances | user.wallets.balances() |
| Read everything it owns | user.portfolio.get() |
| Chart its value | user.portfolio.history({ range: "1W" }) |
| Price a deposit | user.wallets.quoteDeposit({ rail, network, assetId, amountRaw, maxValueLossBps }) |
| Fund it | user.wallets.createDeposit({ terms }, { idempotencyKey }) |
| Withdraw | user.wallets.quoteWithdrawal(request), then user.wallets.withdraw({ terms, authorization }, { idempotencyKey: quote.requestKey }) |
| Swap | user.wallets.quoteSwap(request), then user.wallets.swap({ terms, authorization }, { idempotencyKey: quote.requestKey }) |
| Place a limit order | user.wallets.prepareOrder(request), then user.wallets.placeOrder({ terms, authorization }, { idempotencyKey: prepared.requestKey }) |
| Pause or resume an automation | user.automations.pause(id), user.automations.resume(id) |
| Handle a refusal | if (error instanceof FinApiError) error.reason |
React components
The quickstart puts these together; the components and view models references list everything.
Set up
| Task | Use |
|---|
| Load the styles | import "@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
| Task | Use |
|---|
| Fold the events | useReducer(threadReducer, initialThread), then dispatch(event) |
| List what to draw | transcriptEntries(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 time | wrap the transcript in <ApprovalExpansionProvider> |
| Offer the suggested replies | <NextSteps steps={splitReplyNextSteps(text).nextSteps} onPick={send} /> |
| Let the cards carry the facts | send RENDERED_CARDS as context.renders |
| Show cards as the agent finds what it needs | add show (or placement) to context.renders, draw threadTurns(thread) |
| Report the user's country | send context.country from your server's edge geolocation with every message; see Tokenized stocks for country and purchase restrictions |
Style and test
| Task | Use |
|---|
| Retheme | --fin-* variables on :root |
| Restyle one block | className, and classNames for its parts |
| Restyle every button | CSS on [data-fin-ui="button"][data-fin-variant="primary"] |
| Draw your own approval | approvalContent(approval) |
| Show a token | <TokenIcon symbol iconUrl network={assetChain(tokenId)} />, or <AssetIcon asset={holding} /> |
| Draw states in stories and tests | foldFixture("approvalPending"), oneShotApproval(contract) from /fixtures |