Installation & Setup

Install the Vowena TypeScript SDK from npm, configure your VowenaClient for Stellar mainnet or testnet, and explore all available exports and type definitions.

Install the SDK

npm

npm install @vowena/sdk

The SDK requires Node.js 18+ and has a peer dependency on @stellar/stellar-sdk ^15.0.1. If your project doesn’t already include it, install it alongside:

npm install @vowena/sdk @stellar/stellar-sdk

---

Create a Client

The VowenaClient is the main entry point for all contract interactions. It builds transactions locally - you sign and submit them with your own wallet or keypair.

import { VowenaClient, NETWORKS } from "@vowena/sdk";

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

---

Network Configuration

The SDK ships with pre-configured network constants via the NETWORKS object.

Testnet

import { VowenaClient, NETWORKS } from "@vowena/sdk";

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

Property	Value
rpcUrl	https://soroban-testnet.stellar.org
networkPassphrase	Test SDF Network ; September 2015
contractId	Pre-deployed testnet contract
usdcAddress	Testnet USDC token contract

Mainnet

// Mainnet deployment is coming after testnet pilots.
import { VowenaClient, NETWORKS } from "@vowena/sdk";

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

Property	Value
rpcUrl	https://soroban.stellar.org
networkPassphrase	Public Global Stellar Network ; September 2015
contractId	Mainnet contract (coming soon)
usdcAddress	CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI

Custom RPC

import { VowenaClient } from "@vowena/sdk";

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

Use a custom configuration when you want to connect to a private RPC provider or a locally deployed contract.

---

Exports

Classes & Functions

import {
  VowenaClient, // Main client for all contract interactions
  toStroops, // Convert human-readable amount to stroops (bigint)
  fromStroops, // Convert stroops (bigint) to human-readable string
  getEvents, // Fetch contract events from Soroban RPC
  VowenaEventPoller, // Continuous event polling class
  NETWORKS, // Pre-configured network constants
  USDC_DECIMALS, // 7
  SECONDS_PER_DAY, // 86400
  SECONDS_PER_MONTH, // 2592000
  SECONDS_PER_YEAR, // 31536000
} from "@vowena/sdk";

Types

import type {
  Project, // On-chain project data
  Plan, // On-chain plan data
  Subscription, // On-chain subscription data
  SubscriptionStatus, // "Active" | "Paused" | "Cancelled" | "Expired"
  CreateProjectParams, // Parameters for buildCreateProject()
  CreatePlanParams, // Parameters for buildCreatePlan()
  VowenaClientOptions, // Constructor options for VowenaClient
  TransactionResult, // Result from submitTransaction()
  VowenaEvent, // Parsed contract event
  EventPollerOptions, // Constructor options for VowenaEventPoller
} from "@vowena/sdk";

---

Requirements

Dependency	Version
Node.js	20+
@stellar/stellar-sdk	^15.0.1

The SDK is a lightweight wrapper that builds Soroban transactions. It does not hold private keys or sign transactions - that is handled by your wallet integration (e.g., Freighter, Albedo, or a raw Keypair).

---

Next Steps

Client Reference

Full API reference for every VowenaClient method.

Quickstart

Build a complete subscription lifecycle in 5 minutes.