Quickstart

Go from zero to a working on-chain subscription in 5 minutes. Install the Vowena SDK, create a billing plan, subscribe a wallet, charge, and cancel.

Get a complete subscription lifecycle running on Stellar in under 5 minutes.

This guide uses the Vowena TypeScript SDK. You’ll need Node.js 18+ and a Stellar account with USDC.

1. Install the SDK

   Add the Vowena SDK to your project.

   npm

   npm install vowena
   

   The SDK is a lightweight wrapper around the Vowena Soroban contract. It builds transactions locally - you sign and submit them with your own wallet or keypair.

2. Create a Client

   Initialize the VowenaClient with your network configuration.

   Mainnet

   import { VowenaClient, NETWORKS } from "vowena";
   
   const client = new VowenaClient({
     contractId: NETWORKS.mainnet.contractId,
     rpcUrl: NETWORKS.mainnet.rpcUrl,
     networkPassphrase: NETWORKS.mainnet.networkPassphrase,
   });
   

   Testnet

   import { VowenaClient, NETWORKS } from "vowena";
   
   const client = new VowenaClient({
     contractId: NETWORKS.testnet.contractId,
     rpcUrl: NETWORKS.testnet.rpcUrl,
     networkPassphrase: NETWORKS.testnet.networkPassphrase,
   });
   

   Custom RPC

   import { VowenaClient } from "vowena";
   
   const client = new VowenaClient({
     contractId: "CABC...XYZ",
     rpcUrl: "https://your-rpc.example.com",
     networkPassphrase: "Test SDF Network ; September 2015",
   });
   

   NETWORKS.mainnet provides pre-configured values for contractId, rpcUrl, networkPassphrase, and usdcAddress so you don’t need to look them up.

3. Create a Plan (Merchant)

   Define a subscription plan. This is an on-chain transaction that stores the plan parameters permanently.

   import { toStroops, NETWORKS } from "vowena";
   
   // Build the create_plan transaction
   const tx = await client.buildCreatePlan({
     merchant: "GMERCHANT...ADDR",        // Merchant's Stellar address
     token: NETWORKS.mainnet.usdcAddress,  // USDC token contract
     amount: toStroops("9.99"),            // 9.99 USDC per period → 99900000n
     period: 2_592_000,                    // 30 days in seconds
     priceCeiling: toStroops("14.99"),     // Max price before re-auth needed
     trialPeriods: 1,                      // 1 free billing period
     maxPeriods: 0,                        // 0 = unlimited
     gracePeriod: 259_200,                 // 3 days grace on failed charges
   });
   
   // Sign with your wallet and submit
   const signedXdr = await signTransaction(tx); // Your wallet integration
   const result = await client.submitTransaction(signedXdr);
   console.log("Plan created! ID:", result.planId);
   

   Plans are immutable once created. If you need to change pricing, create a new plan and use the migration flow to move existing subscribers.

   What does toStroops do?

   toStroops("9.99") converts a human-readable amount to the 7-decimal-place integer format used by Stellar tokens. It returns a BigInt:

   toStroops("9.99")   // → 99900000n
   toStroops("1.00")   // → 10000000n
   toStroops("0.50")   // → 5000000n
   

   USDC on Stellar uses 7 decimal places (stroops), matching the native XLM precision.

4. Subscribe (Subscriber)

   A subscriber authorizes the plan. This single transaction calls subscribe() on the Vowena contract and sets the SEP-41 token allowance - one signature covers both.

   // Build the subscribe transaction
   const tx = await client.buildSubscribe(
     "GSUBSCRIBER...ADDR",  // Subscriber's Stellar address
     planId                  // Plan ID from step 3
   );
   
   // Subscriber signs and submits
   const signedXdr = await signTransaction(tx);
   const result = await client.submitTransaction(signedXdr);
   console.log("Subscribed! Subscription ID:", result.subscriptionId);
   

   The subscriber’s wallet will display exactly what is being approved: the token (USDC), the spending ceiling (price_ceiling from the plan), and the contract authorized to pull funds. Full transparency - no hidden permissions.

5. Charge (Keeper / Anyone)

   Once a billing period has elapsed, anyone can trigger the charge. The contract validates all conditions on-chain.

   // Build the charge transaction
   const tx = await client.buildCharge(
     "GCALLER...ADDR",  // Address of whoever is calling (can be anyone)
     subscriptionId      // Subscription ID from step 4
   );
   
   // Sign and submit
   const signedXdr = await signTransaction(tx);
   const result = await client.submitTransaction(signedXdr);
   console.log("Charged! Period:", result.periodNumber);
   

   The contract checks:

   • Is the subscription active?
   • Has enough time passed since the last charge?
   • Is the trial period over?
   • Does the subscriber have sufficient balance and allowance?
   • Has the max period limit been reached?

   If all checks pass, USDC is transferred from the subscriber directly to the merchant via transfer_from().

   You don’t need to run your own keeper. The Vowena Dashboard includes a built-in keeper service, or you can use third-party keeper networks.

6. Cancel

   Either the subscriber or the merchant can cancel a subscription at any time.

   // Build the cancel transaction
   const tx = await client.buildCancel(
     "GSUBSCRIBER...ADDR",  // Subscriber or merchant address
     subscriptionId          // Subscription ID
   );
   
   // Sign and submit
   const signedXdr = await signTransaction(tx);
   const result = await client.submitTransaction(signedXdr);
   console.log("Cancelled! Subscription:", subscriptionId);
   

   Cancellation is immediate and on-chain. No approval from the merchant is needed. The subscriber can also cancel directly through any Stellar wallet or block explorer that supports Soroban contract invocations - the Vowena frontend is not required.

---

Full Example

Here’s the complete flow in a single script:

import { VowenaClient, NETWORKS, toStroops } from "vowena";

const client = new VowenaClient({
  contractId: NETWORKS.mainnet.contractId,
  rpcUrl: NETWORKS.mainnet.rpcUrl,
  networkPassphrase: NETWORKS.mainnet.networkPassphrase,
});

// 1. Merchant creates a plan
const createTx = await client.buildCreatePlan({
  merchant: "GMERCHANT...ADDR",
  token: NETWORKS.mainnet.usdcAddress,
  amount: toStroops("9.99"),
  period: 2_592_000,
  priceCeiling: toStroops("14.99"),
  trialPeriods: 1,
  maxPeriods: 12,
  gracePeriod: 259_200,
});
const planResult = await client.submitTransaction(await sign(createTx));

// 2. Subscriber subscribes
const subTx = await client.buildSubscribe("GSUB...ADDR", planResult.planId);
const subResult = await client.submitTransaction(await sign(subTx));

// 3. After billing period elapses, anyone charges
const chargeTx = await client.buildCharge("GKEEPER...ADDR", subResult.subscriptionId);
await client.submitTransaction(await sign(chargeTx));

// 4. Subscriber cancels when they want
const cancelTx = await client.buildCancel("GSUB...ADDR", subResult.subscriptionId);
await client.submitTransaction(await sign(cancelTx));

---

Next Steps

Core Concepts

Understand plans, subscriptions, allowances, and the billing lifecycle in depth.

How It Works

Visual walkthrough of the full protocol flow - from plan creation to cancellation.

SDK Reference

Complete SDK documentation with all methods, types, and configuration options.

Run a Keeper

Set up an automated keeper bot to charge subscriptions on schedule.