# 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](/sdk-recipes) explain each task; the [reference](/sdk-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](/react-quickstart) puts these together; the [components](/react-components)
and [view models](/react-model) 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](/concepts#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` |
