# OpenCredits

> AI credits that work everywhere. One balance, every model, any app.

OpenCredits is an open marketplace for AI credits. Users buy credits that apps use to make AI requests. The API is compatible with both OpenAI and Anthropic SDKs.

## Quick Start

Point your SDK at `https://api.opencredits.ai` and authenticate with a user key (`oc_sk_...`).

## Base URLs

- OpenAI SDK / fetch: `https://api.opencredits.ai/v1`
- Anthropic SDK: `https://api.opencredits.ai` (SDK adds /v1 automatically)
- Claude Code: `ANTHROPIC_BASE_URL=https://api.opencredits.ai`

## Authentication

All AI requests require a user key (starts with `oc_sk_`). Pass it as:
- `Authorization: Bearer oc_sk_...` header
- `X-User-Key: oc_sk_...` header
- `api_key` parameter in OpenAI or Anthropic SDKs

## Endpoints

- `POST /v1/chat/completions` — OpenAI-compatible chat completions (supports streaming)
- `POST /v1/messages` — Anthropic-compatible messages (supports streaming)
- `GET /v1/models` — List all available models (no auth required)
- `POST /v1/credits/pricing` — Credit estimates per model (body: publishable_key, optional: models[], input_tokens, output_tokens). Also available as GET with query params.
- `GET /v1/credits/balance` — Credits your app can spend for this user right now, plus a `status` explaining any shortfall (requires auth)

## Code Examples

### OpenAI SDK (Python)

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opencredits.ai/v1",
    api_key="oc_sk_...",  # user key
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

### OpenAI SDK (Node.js)

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.opencredits.ai/v1',
  apiKey: 'oc_sk_...',  // user key
});

const response = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-4-20250514',
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

### Anthropic SDK (Python)

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.opencredits.ai",  # no /v1
    api_key="oc_sk_...",  # user key
)

message = client.messages.create(
    model="anthropic/claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
```

### Anthropic SDK (Node.js)

```javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.opencredits.ai',  // no /v1
  apiKey: 'oc_sk_...',  // user key
});

const message = await client.messages.create({
  model: 'anthropic/claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

### Claude Code

```shell
export ANTHROPIC_BASE_URL=https://api.opencredits.ai
export ANTHROPIC_API_KEY=oc_sk_...  # user key
claude
```

### Raw fetch (OpenAI format)

```javascript
const response = await fetch('https://api.opencredits.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer oc_sk_...',
  },
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4-20250514',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});
```

## Model Names

Models use provider-prefixed identifiers. Call `GET /v1/models` for the full list. Common models:

- `anthropic/claude-sonnet-4-20250514` — Claude Sonnet 4
- `anthropic/claude-haiku-4-5-20251001` — Claude Haiku 3.5
- `openai/gpt-4o` — GPT-4o
- `openai/gpt-4o-mini` — GPT-4o Mini
- `google/gemini-2.0-flash` — Gemini 2.0 Flash

## Key Concepts

- **User key** (`oc_sk_...`) — authenticates a user's credit balance. Issued on purchase.
- **Publishable key** (`oc_pk_...`) — identifies a partner app. Used in the checkout widget.
- **Credits** — 100 credits = $1 USD. Deducted per request based on token usage.
- **Referral share** — a percentage added to each request that goes to the partner app.
- **onCreditsAdded** — the Checkout SDK callback to handle: `OpenCredits.init({ onCreditsAdded(data) {...} })` fires when a user makes credits available to your app; `data.type` is `'purchase'` or `'permission'`, `data.user_key` is the key to use, `data.balance` is what your app can spend now. (`onPurchaseCompleted` / `onPermissionUpdated` are deprecated: the same two cases as separate callbacks, still firing with a console warning.)
- **Origins** — the checkout completes only on pages whose origin (e.g. `https://yourapp.com`) the partner registered in the dashboard under "Sites that open your checkout"; `localhost` always works. A page elsewhere shows a refusal naming the origin and shares nothing with the host. `GET/PUT /v1/partner/origins` manage the list.
- **Metadata** — pass `metadata: { user_id: '...' }` (flat object, ≤500 chars) to `OpenCredits.init`; it is echoed in every webhook event about that user's keys and purchases.
- **Webhooks** — signed server-to-server events to the partner's backend: `user_key.created` (carries the plaintext key), `user_key.revoked`, `credits.added` (type purchase | permission). Users are named by an `au_…` id minted per app; OpenCredits never sends its account id or the user's email. Header `X-OpenCredits-Signature: t=<unix>,v1=<hex>` where `v1 = HMAC-SHA-256(secret, t + '.' + rawBody)`; verify against the raw body and reject timestamps older than 5 minutes. Configured in the partner dashboard. Guide: https://opencredits.ai/docs#webhooks

## Error Codes

- `401` — Missing or invalid user key
- `402` — Insufficient credits (prompt user to top up)
- `429` — Rate limited
- `500` — Internal server error

## Pricing

$1 = 100 credits. Credits are deducted based on token usage at provider rates.

## Links

- Integration skill (step-by-step): https://opencredits.ai/skill.md
- Developer docs: https://opencredits.ai/docs
- Developer docs (markdown): https://opencredits.ai/docs.md
- Webhooks guide: https://opencredits.ai/docs#webhooks
- Dashboard: https://opencredits.ai/dashboard
- Available models: https://api.opencredits.ai/v1/models