Getting Started · Web Script Tag

Shadow DOM Web SDK (/v1/creditkit.js)

Drop a single script tag into any HTML page, Vue/Svelte/Astro app, Rails/Django template, or Webflow site. It mounts an isolated Shadow DOM balance pill and exposes window.CreditKit.

Key Capabilities

  • Sandbox & Live Keys: Pass pk_test_... while building locally for instant sandbox checkouts, then swap to pk_live_... once Stripe is connected.
  • Server-Authoritative or Client UI Gating: Pass window.CreditKit.getToken() as x-creditkit-token to your backend route and call window.CreditKit.openTopUp() on HTTP 402—or use data-creditkit-gate / window.CreditKit.gate() for static prototypes.
  • Spoof-Proof User Binding & Sign-Out: Pass data-user-id + data-identity-signature (computed on your backend via HMAC-SHA256(CREDITKIT_SECRET_KEY, userId.toLowerCase())), or call window.CreditKit.identify({ userId, identitySignature }) after login and window.CreditKit.logout() on sign-out. (Free starter credits and live checkouts require a signed-in user so balances sync safely across devices; Test Mode pk_test_... lets you prototype locally before wiring credits.signUser(user.id).)

1. Add the Script Tag & Attribute Gate

index.html
<!-- Render on your server for signed-in users (compute signature with HMAC-SHA256(sk_..., userId.toLowerCase())) -->
<script
  async
  src="https://creditkit.dev/v1/creditkit.js"
  data-project-key="pk_test_..."
  data-user-id="usr_clerk_9921"
  data-identity-signature="8f92a4c1..."
  data-auto-gate="[data-creditkit-gate]"
></script>

<!-- Optional: Zero-Code HTML Attribute Gating (must match a key in Pricing & Gates, e.g. run_action) -->
<button data-creditkit-gate data-creditkit-placement="run_action">
  Run Action (-10 credits)
</button>

2. Calling a Server-Gated Endpoint & Handling Sign-Out

app.js
// Link session wallet after login using a server-issued HMAC signature:
await window.CreditKit.identify({
  userId: "usr_clerk_9921",
  identitySignature: serverIssuedHmac, // HMAC-SHA256(CREDITKIT_SECRET_KEY, userId.toLowerCase())
});

// Forward visitor token to your backend hold & open paywall on HTTP 402:
async function onRunAction() {
  const res = await fetch("/api/generate", {
    method: "POST",
    headers: { "x-creditkit-token": window.CreditKit.getToken() || "" },
  });
  if (res.status === 402) {
    window.CreditKit.openTopUp("run_action");
    return;
  }
  if (!res.ok) return;
  await window.CreditKit.refresh();
}

// Or gate a client action directly with 2-phase crash-proof hold / auto-paywall:
async function onClientGate() {
  const gate = await window.CreditKit.gate("run_action", async ({ holdId, remaining }) => {
    return { ok: true, holdId, remaining };
  });
  if (!gate?.allowed) return; // Paywall modal opened automatically on 402
}

// Clear local session token when your user signs out:
async function onSignOut() {
  await window.CreditKit.logout();
}

// Listen to live wallet lifecycle events anywhere in your app:
window.addEventListener("creditkit:synced", (e) => console.log("Synced:", e.detail));
window.addEventListener("creditkit:purchased", (e) => console.log("Purchased:", e.detail));

3. UI Placement & Custom Navbar Triggers

By default, CreditKit pins a floating balance pill to the bottom-right or bottom-left corner of your app. To display credits inside your own top navbar, set Balance pill placement to Custom (Navbar) in Widget Studio and drop in an inline mount:

navbar.html
<!-- Option A (Zero-JS): Auto-render the themed CreditKit pill inside your navbar -->
<header class="my-navbar">
  <a href="/">Acme AI</a>
  <div data-creditkit-pill></div>
</header>

<!-- Option B (Custom button styling): Open the Wallet Drawer from any element -->
<button type="button" data-creditkit-wallet>Billing & Credits</button>

<script>
  // Option C (Programmatic JS API):
  window.CreditKit.openTopUp('run_action');
  window.CreditKit.toggleWalletDrawer(document.getElementById('my-wallet-btn'));
</script>