Subscriptions

The SubscriptionsSDK manages on-chain recurring payment services. Service creators define payment terms, and subscribers authorize recurring payments that can be triggered by anyone.

Concepts

Services

A service defines recurring payment terms:

• Payment asset and amount — what the subscriber pays per period
• Period duration — how often payments occur
• Service metadata — name, description, color, highlight messages

Subscriptions

When a user subscribes to a service, an on-chain record tracks:

• Payment history and streak count
• Next payment timestamp
• Subscription status

Triggers

Anyone can trigger a due payment. The trigger earns a percentage of the payment as an incentive, keeping the system running without centralized cron jobs.

Initialization

import { SubscriptionsSDK } from '@akta/sdk/subscriptions'

const subscriptions = new SubscriptionsSDK({ algorand })

Creating a Service

const serviceId = await subscriptions.newService({
  title: 'Premium Access',
  description: 'Monthly premium subscription',
  amount: 5_000_000n,           // 5 ALGO per interval
  interval: 2_592_000n,         // 30 days in seconds
  highlightColor: '#9439e6',
  highlightMessage: HighlightMessage.New,
  bannerImage: bannerBytes,     // 36-byte image reference
})

With optional parameters:

const serviceId = await subscriptions.newService({
  sender: myAddress,
  signer: mySigner,
  title: 'Premium Access',
  description: 'Monthly premium subscription',
  amount: 5_000_000n,
  interval: 2_592_000n,
  highlightColor: '#9439e6',
  highlightMessage: HighlightMessage.New,
  bannerImage: bannerBytes,
  asset: aktaAssetId,           // Pay with AKTA instead of ALGO
  passes: 3n,                   // 3 shareable pass slots
  gateId: gateAppId,            // Gate subscriber access
})

Subscribing to a Service

const subscriptionId = await subscriptions.subscribe({
  amount: 5_000_000n,
  interval: 2_592_000n,
  recipient: serviceOwnerAddr,
})

With optional parameters:

const subscriptionId = await subscriptions.subscribe({
  sender: myAddress,
  signer: mySigner,
  amount: 5_000_000n,
  interval: 2_592_000n,
  recipient: serviceOwnerAddr,
  asset: aktaAssetId,
  serviceId: serviceId,
  initialDepositAmount: 10_000_000n, // Prepay extra
})

Utilities

The SDK includes helpers for subscription service configuration:

import {
  ServicesKey,
  ServiceStatus,
  HighlightMessage,
  bytesToHexColor,
  hexColorToBytes,
} from '@akta/sdk/subscriptions'

// Convert hex colors for on-chain storage
const bytes = hexColorToBytes('#9439e6')
const hex = bytesToHexColor(bytes) // '#9439e6'

Service Types

interface Service {
  // Service configuration
}

interface NewServiceArgs {
  // Arguments for creating a new service
}

interface SubscribeArgs {
  // Arguments for subscribing to a service
}

interface SubscriptionInfoWithDetails {
  // Full subscription info with service details
}

Subscription operations are typically executed through the wallet plugin system. See Wallet Plugins for details.