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 topk_live_...once Stripe is connected. - Server-Authoritative or Client UI Gating: Pass
window.CreditKit.getToken()asx-creditkit-tokento your backend route and callwindow.CreditKit.openTopUp()on HTTP402—or usedata-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 viaHMAC-SHA256(CREDITKIT_SECRET_KEY, userId.toLowerCase())), or callwindow.CreditKit.identify({ userId, identitySignature })after login andwindow.CreditKit.logout()on sign-out. (Free starter credits and live checkouts require a signed-in user so balances sync safely across devices; Test Modepk_test_...lets you prototype locally before wiringcredits.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>