@buildnimbus/sdk

v0.1.0

Published

a month ago

Token-gated access for any React app. Wallet ownership → verification → access.

0High
0Medium
0Low

nicksands

solana token-gating web3 access-control nimbus

@buildnimbus/sdk

Token-gated access for any React app.

Wallet ownership → token verification → access → participation

All verification is server-side via the Nimbus API. The SDK never makes blockchain calls and never trusts client-reported balances.

Install

From npm (coming soon):

npm install @buildnimbus/sdk

Local development (SDK not yet published):

npm install C:\Users\Curtis\dev\nimbus-sdk

Import from @buildnimbus/sdk — the same name whether you installed from npm or a local path.

Zero runtime dependencies. React >=18 peer dependency only.

Windows PowerShell: if npm or npx fails because .ps1 shims are blocked by execution policy, use npm.cmd and npx.cmd instead.

Quickstart

import { NimbusProvider, NimbusGate, useNimbusAccess } from "@buildnimbus/sdk";

// 1. Wrap your app
<NimbusProvider
  apiUrl="https://nimbus-seven-alpha.vercel.app"
  config={{
    communities: {
      bonk: { mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", chain: "solana" },
    },
    tiers: {
      whale:  { community: "bonk", minimum: 1000000 },
      holder: { community: "bonk", minimum: 1 },
    },
  }}
>
  {children}
</NimbusProvider>

// 2. Gate any component
<NimbusGate tier="whale">
  <WhaleOnlyContent />
</NimbusGate>

// 3. Gate a word
<NimbusGate tier="holder">PROMO50</NimbusGate>

// 4. Hook for custom UI
const { hasAccess, balance, tier, isLoading, error } = useNimbusAccess({ community: "bonk" });

Next.js App Router setup

Step 1 — Config file

// app/nimbus.config.ts
import { defineConfig } from "@buildnimbus/sdk";
import type { NimbusConfig, NimbusChain, NimbusProviderProps } from "@buildnimbus/sdk";

export default defineConfig({
  communities: {
    myToken: { mint: "YOUR_TOKEN_MINT_HERE", chain: "solana" },
  },
  tiers: {
    basic:   { community: "myToken", minimum: 100 },
    premium: { community: "myToken", minimum: 500 },
  },
});

Step 2 — Provider wrapper

// app/providers.tsx
"use client";
import { NimbusProvider } from "@buildnimbus/sdk";
import nimbusConfig from "./nimbus.config";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <NimbusProvider
      apiUrl="https://nimbus-seven-alpha.vercel.app"
      config={nimbusConfig}
    >
      {children}
    </NimbusProvider>
  );
}

Step 3 — Root layout

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Step 4 — Gate a page

<NimbusGate> carries its own "use client" and can be imported directly into a Server Component. Pages that call hooks directly must be Client Components:

// app/picks/page.tsx — Server Component, no hooks
import { NimbusGate } from "@buildnimbus/sdk";

export default function PicksPage() {
  return (
    <div>
      <p>Free content for everyone.</p>
      <NimbusGate tier="basic">
        <p>Basic tier — visible to holders of 100+.</p>
      </NimbusGate>
      <NimbusGate tier="premium">
        <p>Premium — visible to holders of 500+.</p>
      </NimbusGate>
    </div>
  );
}

// app/dashboard/page.tsx — Client Component, uses a hook directly
"use client";
import { useNimbusAccess } from "@buildnimbus/sdk";

export default function Dashboard() {
  const { hasAccess, balance, tier } = useNimbusAccess({ community: "myToken" });
  return <pre>{JSON.stringify({ hasAccess, balance, tier }, null, 2)}</pre>;
}

Gate styles

Three visual modes for the locked state. Omitting style defaults to "block".

// Block — content removed from the DOM entirely (default, most secure)
<NimbusGate tier="holder" style="block">
  <SecretSection />
</NimbusGate>

// Fade — content faded, but present in the DOM
<NimbusGate tier="holder" style="fade">PROMO50</NimbusGate>

// Blur — content blurred, but present in the DOM
<NimbusGate tier="holder" style="blur">
  <PreviewContent />
</NimbusGate>

SECURITY — fade and blur are teaser UX, not protection. Both modes render the real content into the DOM for every visitor. A non-holder can read a fade/blur-gated string straight out of page source. Never use fade or blur on truly secret data — fetch secrets from a server route that re-verifies access before returning the payload.

Custom fallback for any style:

<NimbusGate tier="holder" fallback={<UpgradePrompt />}>
  premium content
</NimbusGate>

Direct mint check (no config needed):

<NimbusGate mint="TOKEN_ADDRESS" minimum={1000}>
  <p>Holder-only content</p>
</NimbusGate>

Tiers

useNimbusTier returns the single highest tier the wallet satisfies, or "none". Because it returns immediately on first render, show a loading state to avoid flashing the fallback branch at a valid holder:

import { NimbusTier, useNimbusTier } from "@buildnimbus/sdk";

// Hook — useful for conditional logic
const tier = useNimbusTier({ community: "bonk" });
// Returns: "whale" | "holder" | "none"
// Note: returns "none" on the initial render before the API responds.
// Use isLoading from useNimbusAccess if you need to distinguish loading from no-access.

// Component — renders exactly one branch
<NimbusTier community="bonk">
  <NimbusTier.Match tier="whale">Whale content</NimbusTier.Match>
  <NimbusTier.Match tier="holder">Holder content</NimbusTier.Match>
  <NimbusTier.None>Not a holder yet — join to unlock.</NimbusTier.None>
</NimbusTier>

Resolution selects the highest satisfied tier — a wallet with 1,000,000 balance satisfies both holder and whale and renders the whale branch.

.Match and .None must be direct children of <NimbusTier> — they read access state from the parent context and will throw if used outside it. Do not wrap them in intermediate elements. Exactly one branch renders at a time; all others return null.

Wallets

The SDK bundles no wallet library. Three paths:

Path 1 — Your app already manages wallets (wagmi, Solana Wallet Adapter, Privy) — pass the address down:

// wagmi
const { address } = useAccount();
<NimbusProvider apiUrl="..." wallet={{ address: address ?? null }}>

// Solana Wallet Adapter
const { publicKey } = useWallet();
<NimbusProvider apiUrl="..." wallet={{ address: publicKey?.toBase58() ?? null }}>

// Privy
const { user } = usePrivy();
<NimbusProvider apiUrl="..." wallet={{ address: user?.wallet?.address ?? null }}>

Path 2 — No wallet setup — the SDK detects injected providers (window.solana, window.ethereum) automatically.

Path 3 — Local testing with a dev wallet override:

// Use an env var, never a hardcoded address. Remove before shipping to production.
const devWallet =
  process.env.NODE_ENV === "development"
    ? (process.env.NEXT_PUBLIC_NIMBUS_TEST_WALLET ?? null)
    : null;

// Spread the wallet prop — never pass wallet={{ address: null }}.
// Passing a null address is treated as an active override and permanently
// locks everyone out. Omit the prop entirely when no override exists.
<NimbusProvider
  apiUrl="..."
  config={nimbusConfig}
  {...(devWallet ? { wallet: { address: devWallet } } : {})}
>

Add NEXT_PUBLIC_NIMBUS_TEST_WALLET=YOUR_HOLDER_WALLET to .env.local.

This pattern only applies under next dev. Running next build + next start disables the override intentionally — production requires a real connected wallet.

useNimbusWallet() exposes the current wallet state:

import { useNimbusWallet } from "@buildnimbus/sdk";

const { address, connected, chain } = useNimbusWallet();
// address:   string | null       — base58 / hex address, or null when disconnected
// connected: boolean             — note: `connected`, NOT `isConnected`
// chain:     NimbusChain | null  — active chain, or null when disconnected
//
// This is the complete return interface.
// Import WalletState for the full type: import type { WalletState } from "@buildnimbus/sdk";

When a wallet is connected or a wallet override is active, NimbusButton displays the truncated active address instead of the connect label.

The SDK currently verifies against mainnet only. Use the dev wallet override pattern for local testing. Devnet and testnet support is on the roadmap.

Wall and Button

<NimbusWall /> is a ready-made locked-state card. It takes no children — it self-renders its message and a truncated wallet address. In the disconnected state it also shows a "No wallet detected" banner. Use it as a gate fallback:

<NimbusGate tier="holder" fallback={<NimbusWall />}>
  <PremiumContent />
</NimbusGate>

<NimbusButton /> renders a connect button and manages the wallet popup. It takes no children. When connected or overridden, it shows the truncated active address:

<NimbusButton />

Both accept a standard React style object for CSS theming. See Troubleshooting for why style on these components is CSS, not a gate style.

Config

defineConfig provides autocomplete and compile-time shape validation. Change a threshold in the config file and every <NimbusGate tier="..."> on the site updates automatically.

// nimbus.config.ts
import { defineConfig } from "@buildnimbus/sdk";

export default defineConfig({
  communities: {
    bonk: { mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", chain: "solana" },
  },
  tiers: {
    whale:  { community: "bonk", minimum: 1000000 },
    holder: { community: "bonk", minimum: 1 },
  },
});

import nimbusConfig from "../nimbus.config";

<NimbusProvider apiUrl="..." config={nimbusConfig}>

Multiple providers — you can mount more than one NimbusProvider (nested or side-by-side). Each scopes its own context and config. The verification cache is keyed by wallet + mint + minimum, so identical checks across providers dedupe.

Inline config — when passing a config object literal directly (not via defineConfig), narrow chain so TypeScript accepts it:

const inlineConfig = {
  communities: {
    alpha: { mint: "...", chain: "solana" as const },
  },
  tiers: { /* ... */ },
};

<NimbusProvider config={inlineConfig} ... />

Without as const, chain: "solana" widens to string and fails with Type 'string' is not assignable to type 'NimbusChain | undefined'. The alternative is to always use defineConfig, which infers the type correctly.

Behavior notes

Fails closed. Loading, errors, disconnected wallets, and misconfigured gates render the locked state — never the content.
Cached. Results cache for 30s client-side; concurrent identical checks share one request.

clearCache() (named export, synchronous, returns void) evicts the client cache. It does not re-run gates or hooks that are already mounted. The next fresh access check (a new mount or a new query) will miss the cache and re-verify. To force on-screen gates to re-verify immediately, remount the subtree by bumping a React key after calling clearCache().

To display measured re-verify latency, place the hook inside the keyed subtree and time the isLoading true→false transition:

import { useEffect, useRef, useState } from "react";
import { clearCache, useNimbusAccess } from "@buildnimbus/sdk";

function AccessProbe({ onSettled }: { onSettled: (ms: number) => void }) {
  const { isLoading } = useNimbusAccess({ community: "myToken" });
  const start = useRef(performance.now());

  useEffect(() => {
    if (!isLoading) onSettled(Math.round(performance.now() - start.current));
  }, [isLoading, onSettled]);

  return null;
}

export function CacheControls() {
  const [nonce, setNonce] = useState(0);
  const [elapsed, setElapsed] = useState<number | null>(null);

  function refresh() {
    clearCache();
    setNonce((n) => n + 1); // remounts AccessProbe → fresh verify
  }

  return (
    <div>
      <button onClick={refresh}>Clear Cache and Re-verify</button>
      {elapsed !== null && <p>Re-verified in {elapsed}ms</p>}
      <div key={nonce}>
        <AccessProbe onSettled={setElapsed} />
        {/* gate content here */}
      </div>
    </div>
  );
}

Typical cache-miss latency is ~150–200ms.

Client-side gating hides UI, it does not protect data. Anything truly secret must be fetched from a server route that re-verifies access before returning the payload.

Under the hood, each gate or hook issues:

GET {apiUrl}/api/check-access
      ?wallet={address}&mint={mint}&minimum={n}
      &network=mainnet&gate_type=token&gate_mode=token_amount
-> 200 { "hasAccess": boolean, "balance": number }

With only a community query (no tier/minimum), the SDK uses minimum=1. balance and hasAccess come from the API; tier is derived client-side from your config thresholds (the highest tier the balance satisfies, or "none").

Common mistakes

// Bad: checking balances in the browser yourself.
if (walletBalance >= 100) { showContent(); }
// Good: let the SDK verify server-side.
<NimbusGate tier="basic"><Content /></NimbusGate>

// Bad: gating truly secret data by hiding components alone.
{ hasAccess && <SecretContent /> }
// Good: fetch secrets from a server route that re-verifies.

// Bad: hardcoding a wallet override in production.
wallet={{ address: "6J8eyph..." }}
// Good: use the env var pattern — dev only.

// Bad: passing wallet={{ address: null }}.
// This treats null as an active override and locks everyone out.
// Good: omit the wallet prop entirely when no override exists.
{...(devWallet ? { wallet: { address: devWallet } } : {})}

Types

All primary TypeScript types are exported from @buildnimbus/sdk:

import type {
  NimbusConfig,        // full config shape for defineConfig / NimbusProvider
  NimbusChain,         // "solana" | "base" | "ethereum" | "polygon"
  NimbusProviderProps, // props for NimbusProvider
  NimbusGateProps,     // props for NimbusGate
  NimbusWallProps,     // props for NimbusWall
  NimbusButtonProps,   // props for NimbusButton
  NimbusTierProps,     // props for NimbusTier
  TierMatchProps,      // props for NimbusTier.Match
  WalletState,         // return shape of useNimbusWallet
  AccessQuery,         // params accepted by useNimbusAccess
  AccessResult,        // { hasAccess, balance } from the API
  AccessState,         // full return shape of useNimbusAccess
  CommunityConfig,     // shape of a single community in defineConfig
  TierConfig,          // shape of a single tier in defineConfig
} from "@buildnimbus/sdk";

detectChain and EVM_CHAIN_IDS are also exported as runtime values.

EVM_CHAIN_IDS maps chain names to their network IDs:

{ ethereum: 1, base: 8453, polygon: 137 }

Phase status

[x] Phase 1 — NimbusProvider, useNimbusWallet, useNimbusAccess, <NimbusGate style="block">
[x] Phase 2 — useNimbusTier, <NimbusTier> (+ .Match / .None), <NimbusWall>, <NimbusButton>
[x] Phase 3 — fade/blur gate styles (content in DOM by design — teaser UX, not protection)
[x] Phase 4 — config system (defineConfig + import pattern)
[ ] Phase 5 — Pantheon swap
[x] Phase 6 — publish-ready (LICENSE, metadata, prepublish pipeline; awaiting npm publish)

Troubleshooting

"useContext/useState only works in Client Components" in Next.js App Router — fixed in 0.1.0 via build banner. All SDK components carry "use client" in the bundle, so importing <NimbusGate> directly into a Server Component works. Pages that call hooks directly must add "use client" at the top. If you see this error on an older build, rebuild the package.

Gate always locked / hasAccess always false — check in order: (1) is <NimbusProvider apiUrl="..."> wrapping the tree? A missing provider throws; a wrong apiUrl fails closed. (2) Is a wallet connected or passed via the wallet prop? No wallet = locked by design. (3) Open the Network tab — a CORS error means the API host hasn't allowed your origin.

Import errors after updating a locally-linked package — restart your dev server and your editor's TypeScript server. Local-path installs are symlinks; both tools cache aggressively.

Type '"blur"' has no properties in common with type 'Properties...' when styling NimbusWall or NimbusButton — the style prop means two different things in this SDK: on <NimbusGate> it selects the gate style ("block" | "fade" | "blur"); on <NimbusWall> and <NimbusButton> it is the standard React CSS style object for theming. Gate styles only exist on NimbusGate.

Type '""' is not assignable to type 'NimbusChain' — editor autocomplete tends to insert chain="". An empty string is not a chain; pass a real value ("solana", "base", "ethereum", "polygon") or omit the prop and let detection/config decide.

Gates permanently locked in production after testing — you likely left wallet={{ address: devWallet }} in your provider with devWallet evaluating to null. Passing any wallet prop (even null) disables injected-wallet detection. Use the spread pattern so the prop is omitted entirely when null: {...(devWallet ? { wallet: { address: devWallet } } : {})}.

Build

npm install
npm run build      # tsup -> dist/ (ESM + CJS + types)
npm run typecheck

Consumer apps: create-next-app does not add a typecheck script. Add this to your app's package.json scripts:

"typecheck": "tsc --noEmit"

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@buildnimbus/sdk

Install

Quickstart

Next.js App Router setup

Gate styles

Tiers

Wallets

Wall and Button

Config

Behavior notes

Common mistakes

Types

Phase status

Troubleshooting

Build