BILLING LAYER · VOL V

Subscriptions

Recurring payments enforced at the blockchain consensus layer — no payment processor, no webhook infrastructure, no failed-charge handling. The protocol collects, or the subscription lapses.

AUTOMATED BILLINGFLEXIBLE FREQUENCYCONSENSUS-ENFORCEDAI-AGENT PERMITTED
100%
On-chain billing — no external payment processor
∞
Configurable billing frequency in blocks
1
Transaction type: SUBSCRIBE — covers full lifecycle
0
Webhooks, callbacks, or off-chain logic required
ARCHITECTURE

How protocol subscriptions work

Subscriptions in Shamwari are stored as first-class account entities. The protocol processes billing automatically at the configured block height interval.

01
Service Creation
SERVICE_PROVIDER creates a subscription service with configurable billing frequency (in blocks), price, accepted asset types, and account type restrictions. Persisted on-chain as a service entity.
Subscriber Opt-In
Subscriber submits SUBSCRIBE transaction specifying the service ID. Subscription entity created on-chain with expirationHeight = current height + billing period. First payment taken immediately.
Automatic Renewal
At expirationHeight, AFTER_BLOCK_APPLY checks all expiring subscriptions. If funds available, payment is collected and expirationHeight extended. If not, subscription lapses automatically. Zero manual intervention.
KEY FEATURES

Subscription capabilities

Block-Height Billing

Billing frequency configured in blocks — daily (~7200 blocks), weekly, monthly, or any custom interval. Exact and deterministic — no timezone issues, no ambiguous billing dates.

Any Asset Type

Services can accept payment in chain coin, ShamwariPay currency, or Totem digital assets. The same subscription infrastructure supports any monetary instrument the protocol supports.

Account Type Restrictions

Services can restrict subscriptions to specific account types — BUSINESS, DEVELOPER, or PERSONAL only. Enforced at consensus — the protocol rejects subscriptions from non-permitted account types.

AI Agent Compatible

AccountType.AI agents can subscribe to services within their configured permission matrix. Subscription payments are included in the rolling spend window calculation for limit enforcement.

Automatic Lapse

If funds are unavailable at renewal, the subscription lapses immediately. No retry logic, no dunning management, no failed payment handler. Protocol state reflects economic reality instantly.

Instant Cancellation

CANCEL_SUBSCRIPTION is a consensus transaction — effective at the next block. No notice period ambiguity. Subscription entity deleted from state immediately.

BUILD SUBSCRIPTION PRODUCTS

No payment processor. Just the protocol.

Create subscription services that bill automatically — SaaS, media, data feeds, or any recurring revenue model.

Get StartedShamwariPay