# credits

> Enforces per-user credit budgets with middleware that stops model calls, and settles held credits as on-chain claims on a cron. Covers production setup.

The `credits` plugin enforces per-user credit budgets and settles held credits to the chain on a cron. It is on unless `DISABLE_CREDITS=true`, and in production you construct it with a Redis client and the network.

**Source:** [`packages/oracle-runtime/src/plugins/credits/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/credits/)

| Attribute | Value |
| --- | --- |
| Feature key | `credits` |
| Visibility | `silent` |
| Stability | `stable` |
| Category | `core` |
| Default state | On unless `DISABLE_CREDITS=true` |
| Depends on | None |

## Summary

Owns the full credit lifecycle:

- **Enforcement.** Per-request middleware that aborts model calls when the user is out of credits (`createCreditsMiddleware` + `TokenLimiter`).
- **Settlement.** Background cron that converts held credits into on-chain claims, shipped via `ClaimProcessingModule`.

Silent (no agent-visible tools). When loaded, this plugin also activates the runtime's Tier-0 `SubscriptionMiddleware`, which gates the HTTP request before the graph even runs.

## Environment variables

| Var | Required | Description |
| --- | --- | --- |
| `SUBSCRIPTION_URL` | no | Subscription API URL. |
| `SUBSCRIPTION_ORACLE_MCP_URL` | no | Subscription Agentic Oracles MCP server URL. |
| `DISABLE_CREDITS` | no | Set to `'true'` to skip the plugin entirely. |
| `NETWORK` | no | Read but not owned (declared by the core base env schema). Required by the cron module. |

## What it contributes

- **Tools:** none.
- **Sub-agents:** none.
- **Middleware:** `createCreditsMiddleware` (aborts the agent run when the user is out of credits).
- **Nest modules** (when Redis is configured at construct time):
  - `ClaimProcessingModule`: cron that settles held credits on chain.
  - `FileProcessingSinkModule`: `FILE_PROCESSING_CREDIT_SINK` so pre-flight file-processing LLM usage bills the per-user budget.
  - `SubscriptionSinkModule`: `SUBSCRIPTION_CREDIT_SINK` so the subscription middleware mirrors per-DID subscription payload + balance into Redis on every authenticated request.
- **HTTP routes:** none directly.
- **Shared state:** none.

## Production constructor

The bundled singleton is for inspect / test only. Production needs a Redis client and the network:

```ts
import { createOracleApp, CreditsPlugin } from '@ixo/oracle-runtime';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

const app = await createOracleApp({
  config,
  plugins: [new CreditsPlugin({ redis, network: 'devnet' })],
});
```

Without a Redis client the middleware loads in pass-through mode and the cron modules are skipped.

## Opt out / opt in

```ts
const app = await createOracleApp({
  config,
  features: { credits: false }, // never load
});

// Or via env: DISABLE_CREDITS=true
```

## Where to read next

<CardGroup cols={2}>
  <Card title="Add a middleware" icon="layer-group" href="/build-an-oracle/develop/plugin-recipes/add-a-middleware">
    The pattern `createCreditsMiddleware` uses.
  </Card>
  <Card title="Identity and auth" icon="id-card" href="/build-an-oracle/develop/identity-and-auth">
    How subscription payloads reach the request.
  </Card>
</CardGroup>
