> ## Documentation Index
> Fetch the complete documentation index at: https://vowena-dependabot-github-actions-actions-checkout-7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @vowena/sdk
  ```

  ```bash yarn theme={null}
  yarn add @vowena/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @vowena/sdk
  ```

  ```bash bun theme={null}
  bun add @vowena/sdk
  ```
</CodeGroup>

<Info>
  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:

  ```bash theme={null}
  npm install @vowena/sdk @stellar/stellar-sdk
  ```
</Info>

***

## 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.

```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,
});
```

***

## Network Configuration

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

<Tabs>
  <Tab title="Testnet">
    ```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,
    });
    ```

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

  <Tab title="Mainnet">
    ```typescript theme={null}
    // 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` |
  </Tab>

  <Tab title="Custom RPC">
    ```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",
    });
    ```

    Use a custom configuration when you want to connect to a private RPC provider or a locally deployed contract.
  </Tab>
</Tabs>

***

## Exports

### Classes & Functions

```typescript theme={null}
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

```typescript theme={null}
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` |

<Tip>
  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`).
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Client Reference" icon="code" href="/sdk/client">
    Full API reference for every VowenaClient method.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build a complete subscription lifecycle in 5 minutes.
  </Card>
</CardGroup>