Configure automated billing for your Vowena subscriptions. Use the built-in dashboard keeper or run a standalone keeper bot for full control.
A keeper is any process that calls charge() on due subscriptions. The Vowena protocol is permissionless - anyone can trigger a charge, and the contract validates all conditions on-chain. You just need something to make the call on schedule.There are two options: the built-in dashboard keeper (zero setup) or a standalone bot you run yourself.
Dashboard Keeper (Built-in)
Standalone Keeper Bot
The Vowena Dashboard includes an integrated keeper service that handles billing automatically. No infrastructure to manage.
Don’t want to wait for the next scheduled run? Click the Charge All Due button to trigger an immediate billing run for all your due subscriptions.
The dashboard keeper requires the dashboard backend to be running (Postgres database, cron endpoint). If you’re self-hosting the dashboard, make sure the cron service is configured and operational.
The built-in keeper is the easiest option for most merchants. It runs as part of the dashboard infrastructure and requires no additional setup. For high-volume merchants or those who want full control over the billing schedule, consider the standalone bot.
Run your own keeper bot for full control over billing execution, scheduling, and monitoring.
1
Clone the Repository
The keeper bot is included in the Vowena SDK repository.
The Vowena contract address on your target network
CABC...XYZ
KEEPER_SECRET
Secret key of the wallet that will sign charge transactions
SABC...XYZ
RPC_URL
Soroban RPC endpoint
https://soroban-testnet.stellar.org
NETWORK_PASSPHRASE
Stellar network passphrase
Test SDF Network ; September 2015
INTERVAL_MS
How often the keeper checks for due subscriptions (in milliseconds)
60000 (every minute)
The KEEPER_SECRET is a Stellar secret key that signs charge transactions. Treat it like a private key - never commit it to version control, never share it, and never expose it in client-side code. Use environment variables or a secrets manager.
Query the contract (or a local index) for subscriptions that are past their next_billing_time
Build a charge() transaction for each
Sign with KEEPER_SECRET and submit
Log the result (success, failure, or skipped)
Wait INTERVAL_MS and repeat
4
Production Hardening
For a production deployment, consider the following:
Use the event indexer - Instead of querying the contract for all subscriptions each cycle, run the SDK’s event indexer to maintain a local database of subscriptions and their billing state. This is far more efficient at scale.
Process manager - Run the keeper with pm2, systemd, or inside a Docker container to ensure it restarts on failure.
Monitoring - Set up alerts for failed charges, keeper downtime, or unexpected errors. The keeper logs structured JSON output for easy integration with monitoring tools.
Multiple keepers - It’s safe to run multiple keeper instances. If two keepers try to charge the same subscription simultaneously, the contract will reject the duplicate - only the first transaction succeeds. No double-charging is possible.
The keeper wallet pays Stellar transaction fees for each charge - approximately $0.00001 per transaction. The keeper does not receive the subscription payment. Payments flow directly from the subscriber’s wallet to the merchant’s wallet via the smart contract. The keeper simply triggers the transfer.
Best for most merchants. Zero setup, managed infrastructure, built-in monitoring. Works out of the box at dashboard.vowena.xyz.
Standalone Bot
Best for high-volume merchants, self-hosted setups, or anyone who wants full control over billing timing and infrastructure.
You can use both. Enable the dashboard keeper as your primary billing mechanism and run a standalone bot as a backup. Since double-charging is impossible at the contract level, redundant keepers are perfectly safe.
Nothing is lost. Subscriptions remain active on-chain. When the keeper comes back online, it picks up all overdue subscriptions and charges them. Subscribers in their grace period won’t be paused until the grace window expires - giving you time to restore the keeper.
Can someone else run a keeper for my subscriptions?
Yes. The charge() function is permissionless - anyone can call it. Third-party keeper networks, your subscribers, or even the subscribers’ own automation can trigger charges. The contract validates everything regardless of who submits the transaction.
How much does it cost to run a keeper?
Each charge transaction costs approximately 0.00001inStellarnetworkfees.For1,000subscriptionsbilledmonthly,that′sroughly0.01 per month in transaction fees. The keeper wallet needs a small XLM balance to cover fees - 10 XLM is enough for hundreds of thousands of transactions.
Does the keeper need USDC?
No. The keeper only signs and submits charge() transactions. The USDC transfer happens from the subscriber’s wallet to the merchant’s wallet. The keeper wallet only needs XLM for transaction fees.
