The example app
A complete Next.js wallet on mainnet, in its own public repository, that registers, deposits, pays privately and withdraws, and how to run it.
The Nimbus integration examples repository holds complete apps built on the SDK. Each one installs the SDK from npm. You can copy one folder out of the repository and run it on its own.
Its first example is nextjs-wallet,
a private wallet built with Next.js. It runs on mainnet with real funds. It covers what every app
needs: connect, register, deposit, Private Send, withdraw, balances, history and recovery.
Each file is short and maps onto a page of these docs. Read them side by side.
Run it
Get what it needs
- Node.js 20.9 or later.
- A Solana wallet extension that supports the Wallet Standard. It needs a little SOL for network fees, and the token you want to deposit.
- A mainnet gateway token. To get one, email dev@umbraprivacy.com or reach out to any Umbra team member.
- A Solana RPC endpoint from a provider. The public
api.mainnet-beta.solana.comrefuses most requests from browsers.
Clone it and set the environment
git clone https://github.com/umbra-defi/nimbus-integration-examples.git
cd nimbus-integration-examples/examples/nextjs-wallet
cp .env.example .env.localFill in the two settings in .env.local:
| Variable | What it does |
|---|---|
NEXT_PUBLIC_NIMBUS_RPC | Your RPC endpoint, used in place of the preset's public one. |
NEXT_PUBLIC_NIMBUS_GATEWAY_TOKEN | The gateway token every session sends. Without it, accounts open and read, and every payment fails unauthorized. |
Next.js writes both into the page, so every visitor can read the token. Restart the app after you change them.
Install and start
npm install
npm run devnpm install also runs nimbus-solana-web copy-assets public/nimbus, which copies the SDK's files.
next.config.mjs sends the two cross-origin isolation headers with every route. The app is then at
http://localhost:3000.
npm run build and npm start give a production build. npm run typecheck checks the types.
npm run tokens rewrites the token list, as the table below explains.
Where each feature lives
Every path is under examples/nextjs-wallet.
| Feature | Files | Docs |
|---|---|---|
| Loading the SDK once, in the browser | components/app-provider.tsx, lib/nimbus/load.ts | Use it with React |
| Listing wallets and connecting one | components/connect-card.tsx | Wallets |
| Opening a session, and where its sign-in is kept | lib/nimbus/session.ts, components/connect-card.tsx | Sessions |
| Registering before the first deposit | components/account-gate.tsx, components/register-card.tsx, lib/nimbus/register.ts | Registration |
| Deposit, withdraw and Private Send on one card | components/action-card.tsx, components/flow-form.tsx | Deposit, Withdraw, Transfer |
| Each payment, in one small function | lib/nimbus/deposit.ts, lib/nimbus/withdraw.ts, lib/nimbus/private-send.ts | SDK, sessions and contexts |
| One description of a withdrawal or Private Send result | lib/nimbus/spend.ts | Results and errors |
| A message for each progress stage | lib/progress.ts, components/keep-tab-open.tsx | Show progress |
| Syncing, and balances grouped per token | components/use-account.ts, lib/nimbus/account.ts | Balances, Sync |
| Reserved funds with a Release button | components/balances-panel.tsx, lib/nimbus/account.ts | Reserved funds |
| History, ten entries a page | components/activity-list.tsx, lib/nimbus/history.ts, lib/activity.ts | History |
| A pending deposit, and a refund of a stuck one | components/recovery-card.tsx, lib/nimbus/recovery.ts | If the deposit is still pending |
| Token names and logos | lib/token-list.json, lib/tokens.ts, scripts/fetch-tokens.ts | Tokens |
The token logos are saved in the app, because a cross-origin isolated page shows images from another
site only when that site allows it. npm run tokens fetches the names and logos again. Pass a mint
address to add a token: npm run tokens -- <mint>.
What it leaves out
The example keeps to the basics. It runs only on mainnet, and it does not sync in the background. Use it with React shows how to add that.
Next
Last updated