5-minute setup

Quickstart Guide

Get BillAI integrated into your ChatGPT app in just 5 minutes. This guide walks you through the complete setup process.

Prerequisites

Node.js 18 or higher
A ChatGPT/MCP app you want to monetize
5 minutes of your time

Create a BillAI account

Create your first app

After signing in, go to the Apps page and click Create App.

Give your app a name (e.g., "My ChatGPT Assistant") and optionally add a description. You'll receive an API key — copy and save it securely.

Save your API key

Your API key is only shown once. Store it in a secure location like environment variables.

Create a pricing plan

Go to your app's detail page and navigate to the Plans tab. Create at least one plan with the features you want to gate.

For example, create a "Pro" plan at $9.99/month with these features:

premium_export (boolean)
api_calls (number: 1000)
ai_summaries (boolean)

Install the SDK

Install the BillAI SDK in your project:

Terminal

npm install @billai/sdk
# or
yarn add @billai/sdk
# or
pnpm add @billai/sdk

Set up environment variables

Add your API key and App ID to your environment:

.env

BILLAI_API_KEY=sk_live_your_api_key_here
BILLAI_APP_ID=app_your_app_id_here

You can find your App ID on the app detail page in the dashboard.

Initialize the SDK

Create an AccessControl instance in your app:

lib/access.ts

import { AccessControl } from '@billai/sdk';

export const access = new AccessControl({
  apiKey: process.env.BILLAI_API_KEY!,
  appId: process.env.BILLAI_APP_ID!,
});

Check access before features

Use the check() method to gate features:

Example usage

import { access } from './lib/access';

async function handlePremiumExport(userId: string) {
  // Check if user has access to the feature
  const result = await access.check(userId, 'premium_export');
  
  if (!result.granted) {
    // User doesn't have access - show upgrade prompt
    return {
      error: 'upgrade_required',
      message: 'Premium export requires a Pro plan',
      upgradeUrl: result.upgradeUrl,
    };
  }
  
  // User has access - proceed with the feature
  return performExport();
}

// For usage-based features, increment the counter
async function handleAPICall(userId: string) {
  const result = await access.check(userId, 'api_calls', {
    increment: 1, // Count this API call
  });
  
  if (!result.granted) {
    return {
      error: 'limit_exceeded',
      message: `API limit reached (${result.usage}/${result.limit})`,
      upgradeUrl: result.upgradeUrl,
    };
  }
  
  return processAPICall();
}

You're done!

Your app is now integrated with BillAI. Users who don't have access will be prompted to upgrade, and paying users will seamlessly access premium features.

Common Use Cases

MCP Server Tools

Gate specific tools in your MCP server based on user's plan.

// Before executing a tool
const toolAccess = await access.check(userId, 'advanced_tools');
if (!toolAccess.granted) {
  return { error: 'Upgrade required', upgradeUrl: toolAccess.upgradeUrl };
}

API Rate Limiting

Limit API calls per month with automatic tracking.

// Check and increment usage
const result = await access.check(userId, 'api_calls', { increment: 1 });
console.log(`Usage: ${result.usage}/${result.limit}`);

Feature Flags

Use BillAI as a simple feature flag system tied to plans.

// Check multiple features
const [exports, summaries] = await Promise.all([
  access.check(userId, 'premium_export'),
  access.check(userId, 'ai_summaries'),
]);

const features = {
  canExport: exports.granted,
  canSummarize: summaries.granted,
};

What's next?

Explore the full SDK Reference Learn about feature types See a complete example app