> 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.

# Load (/reference/load)

Your app loads the SDK once per page. [Load the SDK](https://sdk.nimbusprivacy.xyz/helpers/load) walks through the options and
what it checks.

## loadNimbusSdk

Call it once when your app starts, before you list wallets or open a session.

```ts
function loadNimbusSdk(
  context: { readonly cluster: NimbusCluster },
  options?: LoadNimbusSdkOptions,
): Promise<NimbusSdk>;
```

Loads the SDK for a cluster: its bundled preset completed by the options, the browser's
functions, the primitives' WebAssembly module and the circuit artifact cache.

Nothing is fetched besides the primitives' module until a session is opened or a flow runs, and
no wallet is asked for anything. The primitives' module is checked twice before the SDK is
returned: its bytes against the SHA-256 this package pins for the file it ships, before it is
instantiated, and the primitives it fills against `@umbra/nimbus-primitives/conformance`'s known
answers. The shipped prover worker's script, and each WebAssembly module and script it loads, are
checked against their pins in the same way before they run; `settings.assetPinning` says
whether this copy of the package carries pins at all, which a packed copy always does. The
preset carries the cluster's programs, mints, lookup table, genesis hash and routing defaults.
Mainnet's also carries every service endpoint and the proving keys, so a mainnet app passes only
`assetsBaseUrl`. No preset hosts the browser files the SDK
runs: this package ships them in its `assets/` directory, the primitives' module, the prover
worker and the two WebAssembly modules it proves with, which the application copies into the
directory it serves statically with `nimbus-solana-web copy-assets <dir>` and names in
`assetsBaseUrl`. Where a preset publishes no endpoint or proving keys, each must come from
`options`. Every gateway service answers 401 without a gateway token, which
`openNimbusSession` takes per session.

The page must be cross-origin isolated, served with `Cross-Origin-Opener-Policy: same-origin`
and `Cross-Origin-Embedder-Policy: require-corp`: the prover's WebAssembly module declares
shared memory, which a browser creates on no other page.

**Parameters**

| Parameter  | Type                                                                                                         | Description                                                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `context`  | ``{ /** The cluster whose bundled preset to load, such as `mainnet`. */ readonly cluster: NimbusCluster; }`` | The cluster to load.                                                                                                                                         |
| `options?` | `LoadNimbusSdkOptions`                                                                                       | Where the assets are served, endpoints, proving keys, route and browser functions; each falls back to the preset, the served assets or the browser's global. |

**Returns**

`Promise<NimbusSdk>`

The loaded SDK.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` naming every endpoint, and the proving
keys, that neither the preset nor the options configure, when `cluster` has no preset, or when
`assetsBaseUrl` does not end with `/` or is not a URL; `"unsupported-browser"` naming every
global the browser lacks (`fetch`, `crypto.getRandomValues`, `crypto.subtle`,
`indexedDB`, `IDBKeyRange`, `navigator.locks`, `navigator.storage`, `WebAssembly`), when the
page is not cross-origin isolated, or when the browser refuses to open the artifact cache;
`"service-unavailable"` when the primitives' module cannot be fetched;
`"dependency-nonconforming"` naming the file and both digests when the primitives' module is
not the one this package pins, or naming the primitive and its check when one fails its known
answer; `"unreadable"` when what that URL serves is not the module.

**Example**

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

// After `nimbus-solana-web copy-assets public/nimbus`, on a page served with
// Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp:
const mainnet = await loadNimbusSdk(
  { cluster: "mainnet" },
  { assetsBaseUrl: "/nimbus/" },
);

// The same preset, with the app's own RPC in place of the preset's:
const ownRpc = await loadNimbusSdk(
  { cluster: "mainnet" },
  { assetsBaseUrl: "/nimbus/", endpoints: { rpc: "https://rpc.example" } },
);
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/load.ts`.


Last updated 21 October 2026