# Nimbus SDK reference

> Add a private balance to a web app on Solana with @umbra/nimbus-solana-web: proofs in a worker, the balance kept on the device, and every flow from deposit to Private Send.

Every page is also served as Markdown at its URL with `.md` appended. The full text of every page is at https://sdk.nimbusprivacy.xyz/llms-full.txt.

## Overview

- [Nimbus SDK](https://sdk.nimbusprivacy.xyz/index.md): Add private balances and payments to your Solana app.
- [Quickstart](https://sdk.nimbusprivacy.xyz/getting-started/quickstart.md): Go from an empty Vite or Next.js app to Alice depositing, paying Bob privately, and Bob withdrawing.
- [Install and set up](https://sdk.nimbusprivacy.xyz/getting-started/setup.md): Install the package, serve its files, turn on cross-origin isolation and pass the gateway token.
- [Use it with React](https://sdk.nimbusprivacy.xyz/getting-started/react.md): Load the SDK once in the browser, follow the user's wallets, keep the session in context, and sync in the background.
- [Private balances](https://sdk.nimbusprivacy.xyz/explainers/private-balance.md): A private balance is a set of notes, each like a small token account that only its owner can read.
- [The private account](https://sdk.nimbusprivacy.xyz/explainers/private-account.md): One wallet signature opens your user's private account on this device, and the same wallet opens the same account anywhere.
- [What's public and what's private](https://sdk.nimbusprivacy.xyz/explainers/visibility.md): The edges of the pool are public, and the path between them is private. Here is what each payment shows.
- [How a payment works](https://sdk.nimbusprivacy.xyz/explainers/payments.md): Every payment is prepared, approved, proved, sent and settled. Here is what each step does and what can stop it.
- [Fees](https://sdk.nimbusprivacy.xyz/explainers/fees.md): A payment can carry three fees, the protocol fee, Solana's network fee and the relayer's tip. Here is who pays each.
- [Keeping the device in sync](https://sdk.nimbusprivacy.xyz/explainers/sync.md): Why the device's copy of the private balance needs syncing, what a sync does, and when to run one.
- [Tabs and reserved funds](https://sdk.nimbusprivacy.xyz/explainers/reserved-funds.md): Why a running payment reserves the notes it spends, what keeps them reserved, and what frees them.
- [The function template](https://sdk.nimbusprivacy.xyz/api-design/function-template.md): Every function takes one of three objects first, then its arguments, then its options. Learn the shape once and every page reads the same.
- [Results and errors](https://sdk.nimbusprivacy.xyz/api-design/results-and-errors.md): A call can end badly in three ways. Learn which to expect where, and turn every error into a message your user understands.
- [Progress](https://sdk.nimbusprivacy.xyz/api-design/progress.md): Every payment reports its stages through onProgress. Here is every stage, which payments report it, and a message to show.
- [Register a user](https://sdk.nimbusprivacy.xyz/registration.md): Register your user once, on Solana, so they can deposit and receive private payments.
- [Deposit](https://sdk.nimbusprivacy.xyz/deposit.md): Move tokens from your user's wallet into a private balance, theirs or another user's.
- [Pending and stranded deposits](https://sdk.nimbusprivacy.xyz/deposit/pending.md): Finish a deposit Solana had not settled, keep it across a page reload, and return funds an older wallet left behind.
- [Private Send](https://sdk.nimbusprivacy.xyz/transfer.md): Pay another user from the private balance, so the tokens arrive in theirs and the chain shows neither name nor amount.
- [Withdraw](https://sdk.nimbusprivacy.xyz/withdraw.md): Move tokens out of the private balance to any Solana address, the user's own or anyone else's.
- [Load the SDK](https://sdk.nimbusprivacy.xyz/helpers/load.md): Load the SDK for mainnet, replace any of its endpoints, and handle what it checks before it returns.
- [Wallets](https://sdk.nimbusprivacy.xyz/helpers/wallets.md): List the wallets that can sign on the cluster, connect one, handle wallets that sign only version 0, or bring a signer of your own.
- [Sessions](https://sdk.nimbusprivacy.xyz/helpers/sessions.md): Open the user's private account on this device, choose where its unlock signature is kept, switch wallets, and close it.
- [Balances](https://sdk.nimbusprivacy.xyz/helpers/balances.md): Read the private balance from the device, show one row per token with its name and logo, and refresh it after a sync.
- [History](https://sdk.nimbusprivacy.xyz/helpers/history.md): Read the user's past payments a page at a time, tell deposits, withdrawals and Private Sends apart, and know what history cannot show.
- [Sync](https://sdk.nimbusprivacy.xyz/helpers/sync.md): Bring the device up to date with Solana, bound and stop a sync, and keep it running in the background.
- [Reserved funds](https://sdk.nimbusprivacy.xyz/helpers/reserved-funds.md): List the payments holding part of the private balance, and give the user a button that releases the stopped ones.
- [Tokens](https://sdk.nimbusprivacy.xyz/helpers/tokens.md): The tokens a cluster lists, their decimals, formatting amounts for display, names and logos, and naming the token in a history item.
- [Errors](https://sdk.nimbusprivacy.xyz/helpers/errors.md): The two errors the SDK throws, the guards that recognise them, and a catch block that tells them apart.
- [Prover worker and CLI](https://sdk.nimbusprivacy.xyz/helpers/prover-worker.md): Copy the SDK's browser files into your app with the copy-assets command, or bundle the prover yourself and start your own worker.
- [API reference](https://sdk.nimbusprivacy.xyz/reference.md): Every function and type the SDK exports, each documented once, generated from its TSDoc.
- [Load](https://sdk.nimbusprivacy.xyz/reference/load.md): The function that loads the SDK for a cluster, before anything else runs.
- [Wallets](https://sdk.nimbusprivacy.xyz/reference/wallets.md): The three functions that find the user's wallets and connect one.
- [Sessions](https://sdk.nimbusprivacy.xyz/reference/sessions.md): The functions that open and close a user's private account, and the stores that keep its unlock signature.
- [Registration](https://sdk.nimbusprivacy.xyz/reference/registration.md): The three functions that check and complete a user's one-time registration.
- [Deposit](https://sdk.nimbusprivacy.xyz/reference/deposit.md): The four functions a deposit uses, from creating its context to refunding what an older wallet left behind.
- [Transfer](https://sdk.nimbusprivacy.xyz/reference/transfer.md): The two functions a Private Send uses, its context and the payment itself.
- [Withdraw](https://sdk.nimbusprivacy.xyz/reference/withdraw.md): The two functions a withdrawal uses, its context and the withdrawal itself.
- [Balances, history and sync](https://sdk.nimbusprivacy.xyz/reference/reads.md): The three functions that bring the device up to date and read the private balance and past payments from it.
- [Reserved funds](https://sdk.nimbusprivacy.xyz/reference/reserved-funds.md): The two functions that list what stopped payments hold and give it back.
- [Tokens](https://sdk.nimbusprivacy.xyz/reference/tokens.md): The function that names the token of a history item.
- [Errors](https://sdk.nimbusprivacy.xyz/reference/errors.md): The error class the SDK throws, and the two guards that recognise its errors.
- [Prover worker and CLI](https://sdk.nimbusprivacy.xyz/reference/prover-worker.md): The function a prover worker of your own answers with, and the copy-assets command that copies the SDK's browser files.
- [Types](https://sdk.nimbusprivacy.xyz/reference/types.md): Every type the SDK exports, in alphabetical order, generated from its TSDoc.
- [Production checklist](https://sdk.nimbusprivacy.xyz/production/checklist.md): What to check before real users arrive, and how to check each one.
- [Endpoints](https://sdk.nimbusprivacy.xyz/production/endpoints.md): The mainnet endpoints the SDK uses, your own RPC, and services you run yourself.
- [Browser support](https://sdk.nimbusprivacy.xyz/production/browser-support.md): Which browser the SDK is tested in, and what each browser feature it uses is for.
- [Troubleshooting](https://sdk.nimbusprivacy.xyz/production/troubleshooting.md): The problems an app meets most often, what causes each one, and how to fix it.
- [The example app](https://sdk.nimbusprivacy.xyz/resources/example-app.md): A small Next.js app on mainnet that registers, deposits, pays privately and withdraws, and how to run it.
- [Don't confuse](https://sdk.nimbusprivacy.xyz/resources/dont-confuse.md): Six pairs of things that sound alike and behave differently.
- [Glossary](https://sdk.nimbusprivacy.xyz/resources/glossary.md): Every term these docs and the SDK use, in one or two plain sentences.
- [Changelog](https://sdk.nimbusprivacy.xyz/resources/changelog.md): Every change to the SDK since its last version, generated from the repository's changesets.
- [Use these docs with AI tools](https://sdk.nimbusprivacy.xyz/resources/ai-tools.md): Give an AI assistant these docs as Markdown, one page or the whole site.