> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended.

# The function template (/api-design/function-template)

The SDK has no client class. It exports plain functions, and each one takes an object it acts on as
its first argument. There are three such objects, and each lives for a different time.

## Three objects

| Object    | Made by                                                         | Lives for                                          | Holds secrets       |
| --------- | --------------------------------------------------------------- | -------------------------------------------------- | ------------------- |
| The SDK   | `loadNimbusSdk`                                                 | The page. Load it once.                            | No                  |
| A session | `openNimbusSession`                                             | One user on one device, until `closeNimbusSession` | Yes                 |
| A context | `createDepositContext` and the other `create…Context` functions | One payment, or until a pending deposit resolves   | Through its session |

Each object is made from the one before it. The functions that take each one are grouped below.

```mermaid
flowchart LR
sdk(["SDK"]) --> session(["Session"])
session --> context(["Context"])
sdk -.-> wallets["Wallets and tokens: listWallets, followWallets, openWalletConnection, findMintByIdentifier"]
session -.-> reads["The private account: syncNoteStore, readBalances, readHistory, readRegistration, listReservedSpends, releaseReservedNotes"]
context -.-> flows["Payments: register, deposit, transfer, withdraw, resolvePendingDeposit, refundStrandedDeposit"]
```

*The SDK makes a session, and a session makes a context. Each function takes the object it needs.*

Wallet functions need only the SDK. Reading and syncing the private account needs a session. A
payment needs a context, which adds the pool and the services that payment uses.

Create a fresh context right before each payment. It is cheap, and it reads the current pool.

## The call shape

Most functions take three arguments, always in this order:

1. **The object** it acts on: the SDK, a session or a context.
2. **`args`**: what the call is about. These are required.
3. **`options`**: how it behaves. Every option has a default, so you can leave any of them out.

Here is a withdrawal, with each part marked:

```ts
import { withdraw } from "@umbra/nimbus-solana-web";

const result = await withdraw(
  // 1. The object: a withdrawal context, made for this one payment.
  context,
  // 2. args: which token, how much and to whom. All required.
  { mint: usdc, amount: 10_000_000n, recipient: bobsWallet },
  // 3. options: each one changes a default.
  { fees: "added", commitment: "finalized" },
);
```

Where a call needs nothing in `args`, it takes `{}`, and you may leave it out.

A few functions differ. `loadNimbusSdk` takes `{ cluster }` first, since there is no SDK yet. The
`create…Context` functions take a session and options. The sign-in store functions take options
at most, and `closeNimbusSession` takes only a session.

## Names

The verb at the start of a name tells you what the call does:

| Verb                                          | What happens                                                     | Functions                                                                          |
| --------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `load`, `open`, `close`                       | Starts or ends one of the three objects, or a wallet connection. | `loadNimbusSdk`, `openNimbusSession`, `openWalletConnection`, `closeNimbusSession` |
| `create`                                      | Makes a context or a sign-in store. No transaction is sent.      | `createDepositContext`, `createTabSignatureSecretStore` and the rest               |
| `register`, `deposit`, `transfer`, `withdraw` | Runs a payment.                                                  | One function each                                                                  |
| `resolve`, `refund`                           | Settles a deposit that did not finish.                           | `resolvePendingDeposit`, `refundStrandedDeposit`                                   |
| `read`                                        | Returns state and changes nothing.                               | `readBalances`, `readHistory`, `readRegistration`                                  |
| `list`                                        | Returns what is there now.                                       | `listWallets`, `listReservedSpends`                                                |
| `sync`                                        | Brings this device up to date.                                   | `syncNoteStore`                                                                    |
| `release`                                     | Frees funds a payment holds.                                     | `releaseReservedNotes`                                                             |
| `follow`                                      | Calls you back on every change, until you stop it.               | `followWallets`                                                                    |
| `find`                                        | Looks something up in the SDK's own lists.                       | `findMintByIdentifier`                                                             |
| `is`                                          | Tests what was thrown.                                           | `isNimbusSdkError`, `isNimbusSolanaFlowError`                                      |

`readBalances` and `readHistory` read only this device and fetch nothing. `readRegistration` is
the exception: it asks Nimbus's context service, since registration happens on Solana.

## Values

- **Amounts** are `bigint`, in the token's smallest unit. 25 USDC is `25_000_000n`.
- **Addresses** are the `Address` type from `@solana/kit`.
- **Lamports** are always named as such, as in `priorityFeeLamports`.
- **Results** that can end more than one way have a `kind` to `switch` on.

## How a function's entry reads

Each function is documented once, in the [API reference](https://sdk.nimbusprivacy.xyz/reference). Every entry has the same
parts, in this order:

1. **Summary.** One or two sentences on what it does.
2. **Signature.** The function's TypeScript declaration.
3. **Example.** A short call, type-checked against the SDK when the site is built.
4. **Parameters.** Every argument and option, with its type and meaning.
5. **Returns.** What it resolves to, and what each `kind` means.
6. **Throws.** The errors it throws, and why.
7. **Details.** The finer points, collapsed until you open them.

See [readBalances](https://sdk.nimbusprivacy.xyz/reference/reads#readbalances) for a short entry.

- [Results and errors](https://sdk.nimbusprivacy.xyz/api-design/results-and-errors): The three ways a call ends badly.
- [Progress](https://sdk.nimbusprivacy.xyz/api-design/progress): Every stage a payment reports.


Last updated 21 October 2026