> ## Documentation Index
> Fetch the complete documentation index at: https://vowena.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Add the Vowena SDK to your project.
```bash npm theme={null}
npm install @vowena/sdk
```
```bash yarn theme={null}
yarn add @vowena/sdk
```
```bash pnpm theme={null}
pnpm add @vowena/sdk
```
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.
Initialize the `VowenaClient` with your network configuration.
```typescript theme={null}
import { VowenaClient, NETWORKS } from "@vowena/sdk";
const client = new VowenaClient({
contractId: NETWORKS.mainnet.contractId,
rpcUrl: NETWORKS.mainnet.rpcUrl,
networkPassphrase: NETWORKS.mainnet.networkPassphrase,
});
```
```typescript theme={null}
import { VowenaClient, NETWORKS } from "@vowena/sdk";
const client = new VowenaClient({
contractId: NETWORKS.testnet.contractId,
rpcUrl: NETWORKS.testnet.rpcUrl,
networkPassphrase: NETWORKS.testnet.networkPassphrase,
});
```
```typescript theme={null}
import { VowenaClient } from "@vowena/sdk";
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.
Define a subscription plan. This is an on-chain transaction that stores the plan parameters permanently.
```typescript theme={null}
import { toStroops, NETWORKS } from "@vowena/sdk";
// 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.
`toStroops("9.99")` converts a human-readable amount to the 7-decimal-place integer format used by Stellar tokens. It returns a `BigInt`:
```typescript theme={null}
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.
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.
```typescript theme={null}
// 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.
Once a billing period has elapsed, **anyone** can trigger the charge. The contract validates all conditions on-chain.
```typescript theme={null}
// 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](/dashboard/keeper-setup) includes a built-in keeper service, or you can use third-party keeper networks.
Either the subscriber **or** the merchant can cancel a subscription at any time.
```typescript theme={null}
// 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:
```typescript theme={null}
import { VowenaClient, NETWORKS, toStroops } from "@vowena/sdk";
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
Understand plans, subscriptions, allowances, and the billing lifecycle in depth.
Visual walkthrough of the full protocol flow - from plan creation to cancellation.
Complete SDK documentation with all methods, types, and configuration options.
Set up an automated keeper bot to charge subscriptions on schedule.