> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ixo.world/llms.txt
> Use this file to discover all available pages before exploring further.

# credits

> Enforces per-user credit budgets and settles held credits to the chain on a cron.

**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    | —                                |

## 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 theme={"system"}
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 theme={"system"}
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>