credits

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

Source: 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:

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

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

// Or via env: DISABLE_CREDITS=true

Where to read next

Add a middleware

The pattern createCreditsMiddleware uses.

Identity and auth

How subscription payloads reach the request.