Plans

A Plan states, on-chain, what your service costs. You publish it to the Scribe Finance Plan Registry (a public catalog on Robinhood Chain mainnet), and every agent and client on the network can read it. Against those published terms, an agent starts a subscription or authorizes a payment.

Plan structure

interface Plan {
  id: string;                // On-chain plan id
  provider: Address;         // Service provider wallet
  name: string;              // Display name, e.g. "Pro API (10k calls/month)"
  amount: number;            // Price in token base units (e.g. 49_000_000 = 49 USDG)
  token: Address;            // Token contract address (USDG during beta)
  interval: BillingInterval; // MONTHLY | WEEKLY | DAILY | PER_REQUEST
  trialPeriodDays?: number;  // Optional free trial length
  meteredOverage?: {
    unit: string;            // e.g. "1000 tokens"
    price: number;           // Price per unit above the plan limit
  };
}

Creating a plan

const plan = await scribefinance.createPlan({
  name: "Inference Pro",
  amount: 49_000_000,    // 49 USDG
  interval: "MONTHLY",
  trialPeriodDays: 7,
});

console.log(plan.id);    // store this as your plan id

createPlan writes the plan record to the Scribe Finance Plan Registry on Robinhood Chain mainnet, in a transaction signed by your provider wallet. The moment that transaction confirms, the plan is live and discoverable.

Billing intervals

Plans are immutable

A published plan never changes. Its price, interval, token, and trial period are fixed for the life of the record.

This is the point, not a limitation. A subscription is an agreement to specific terms, and terms written to the chain stay written: a provider cannot quietly reprice what a subscriber already agreed to, and anyone auditing a subscription can trust what they read.

To change pricing, publish a new plan. Existing subscribers keep their original terms until they cancel or you migrate them; the timing and mechanics of any migration are yours to decide.

Metered overage

For plans that charge for usage above an included quota, add a meteredOverage block:

const plan = await scribefinance.createPlan({
  name: "Compute Standard",
  amount: 20_000_000,   // 20 USDG base fee
  interval: "MONTHLY",
  meteredOverage: {
    unit: "1000 tokens",
    price: 2_000,       // 0.002 USDG per 1k tokens above quota
  },
});

Overage settles through an Allowance: the service draws from it as usage accumulates, and the agent caps its total exposure by authorizing a spend limit at subscribe time.

Discovering plans

Agents and clients reach a plan through two paths:

1. A 402 response. When a service answers 402 Payment Required, the response body carries the plan ID and its terms. The agent reads them and decides whether the price is worth paying.
2. The registry itself. Any Robinhood Chain client can query the Plan Registry directly and enumerate everything a provider has published.

Payment Flows walks through both paths end to end.

Deprecating a plan

A plan cannot be deleted (its record is permanent), but deprecating it closes the door to new subscribers. Existing subscriptions continue to renew until each subscriber cancels.

await scribefinance.deprecatePlan({ planId: plan.id });

A deprecated plan no longer appears in 402 responses from the payment gate middleware. Its on-chain record remains readable by anyone.