Skip to main content

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.

Source: packages/oracle-runtime/src/plugins/credits/
AttributeValue
Visibilitysilent
Stabilitystable
Categorycore
Default stateOn 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

VarRequiredDescription
SUBSCRIPTION_URLnoSubscription API URL.
SUBSCRIPTION_ORACLE_MCP_URLnoSubscription Agentic Oracles MCP server URL.
DISABLE_CREDITSnoSet to 'true' to skip the plugin entirely.
NETWORKnoRead 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

Add a middleware

The pattern createCreditsMiddleware uses.

Identity and auth

How subscription payloads reach the request.