Quickstart

One API key. Every major model. Built-in billing. Get your first response back in under five minutes — and your first user paying for their own usage in under thirty.

01 Create your developer account

Register with an email and password. New accounts get a small free balance to play with — enough for a few thousand low-cost completions before you ever reach for a credit card.

The session_token below (sess_…) is your developer session — used to mint API keys and manage OAuth apps. It is not the same as an end-user OAuth token (quota_token_…) that your users will get later if you adopt Sign in with Quota or Connect Quota Wallet. See Tokens and actors for the full credential map.

curl -X POST https://api.usequota.ai/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-secure-password"}'

Response:

{
  "user": { "id": "usr_5f3a...", "email": "you@example.com", "balance": 1000000 },
  "session_token": "sess_5d8c7e1f3a..."
}

Balance is denominated in credits. 1,000,000 credits = $1.00. We track to six decimal places so you never lose a fraction of a cent on a streamed response.

Pick your path

Three integration shapes, three walkthroughs. Pick the one that matches your app and the rest of this page reflows to match. Stuck on which? The docs landing has a three-question picker.

02 Get an API key

Use your session token to mint an API key. The full key value is shown once, at creation — Quota stores only a hash, so if you lose it you'll need to mint a new one.

curl -X POST https://api.usequota.ai/developers/keys \
  -H "Authorization: Bearer sess_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My first key"}'

03 Set up environment variables

Drop your key into .env. The exact set you need depends on which billing mode you're using.

# You pay for all AI usage in this app.
QUOTA_API_KEY=sk-quota-...

04 Install the SDK

Quota is OpenAI-compatible — most apps need nothing more than the official OpenAI SDK pointed at our base URL. For Next.js apps, the dedicated SDK adds React hooks, route handlers, and components like <QuotaSignInButton />.

npm install openai
# Optional: Quota's Next.js SDK
npm install @usequota/nextjs

05 Make your first request

Point the OpenAI SDK at https://api.usequota.ai/v1 and call chat.completions.create like you always have. Every response back includes a quota block with credits used and remaining balance.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QUOTA_API_KEY,
  baseURL: "https://api.usequota.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello from Quota" }],
});

console.log(response.choices[0].message.content);
console.log(response.quota); // { credits_used, balance_after, ... }

06 Check your balance

Every response carries a quota object. You can also hit the balance endpoint directly — useful for showing a top-up prompt or a meter in your own UI.

curl https://api.usequota.ai/v1/balance \
  -H "Authorization: Bearer $QUOTA_API_KEY"

07 Drop in the SDK components

The Next.js SDK ships React components and hooks that handle the whole identity, balance, and top-up surface so you don't have to build it. Each demo below is live — toggle the auth chip in the corner to see how they react to signed-out and signed-in state.

<QuotaSignInButton />

Drop-in OAuth-style sign-in. Renders a Quota-branded button that opens the consent flow and resolves to a session.

import { QuotaSignInButton } from "@usequota/nextjs";

export default function Header() {
  return <QuotaSignInButton variant="filled" />;
}

useQuota()

Reactive client hook. Returns user (with user.balance, which may be null if the signed-in user hasn't linked a Quota wallet yet), isLoading, login, and logout — re-renders when usage updates.

{
  "user": null,
  "isLoading": false
}

"use client";
import { useQuota } from "@usequota/nextjs";

export function AccountWidget() {
  const { user, isLoading, logout } = useQuota();

  if (isLoading) return null;
  if (!user) return <p>Sign in to see your balance.</p>;

  // user.balance is `number | null` — `null` means the user is signed in
  // but hasn't linked a Quota credits wallet to this app yet.
  return (
    <div>
      <p>Hi, {user.email}</p>
      {user.balance === null ? (
        <p>No wallet linked — connect one to start spending.</p>
      ) : (
        <p>Balance: <strong>$${(user.balance / 1_000_000).toFixed(2)}</strong></p>
      )}
      <button onClick={() => logout()}>sign out</button>
    </div>
  );
}

<QuotaBalance />

A balance pill you can drop in any header. Animates after each billable request.

import { QuotaBalance } from "@usequota/nextjs";

<QuotaBalance format="dollars" />

More components

The SDK ships three more pre-built components for the wallet, menu, and top-up surfaces. See the SDK reference for the full prop tables.

<QuotaConnectButton />

Wallet-linking pattern — pair Quota credits with your existing auth. Use this when your app has its own user table and you just want a spendable balance attached.

import { QuotaConnectButton } from "@usequota/nextjs";

export function ConnectWallet() {
  return <QuotaConnectButton variant="primary" />;
}

<QuotaUserMenu />

Avatar + balance + sign-out, headless. Drop it in the corner of any signed-in header.

import { QuotaUserMenu } from "@usequota/nextjs";

export function HeaderRight() {
  return <QuotaUserMenu />;
}

<QuotaBuyCredits />

One-click top-up. Drop it in with no props and it opens an inline picker listing every credit package; pass packageId or amount to skip the picker and go straight to Stripe Checkout in a new window. The balance refreshes automatically when the user comes back.

import { QuotaBuyCredits } from "@usequota/nextjs";

export function TopUp() {
  return <QuotaBuyCredits variant="primary" amount={5000000} />;
}

08 Common errors

The error envelope is OpenAI-shaped: error.code, error.message, plus an optional error.param. Three you'll see most:

What's next

Stuck? Drop into #help on Discord — usually answered in under an hour. Brand new? Walk through the 30-line example.