DeFi Payment Streaming on Stellar
Programmable, real-time payment streams and recurring subscriptions.
FlowFi allows users to create continuous payment streams and recurring subscriptions using stablecoins on the Stellar network. By leveraging Soroban smart contracts, FlowFi enables autonomous accurate-to-the-second distribution of funds.
- Real-time Streaming: Pay by the second for services or salaries.
- Recurring Subscriptions: Automate monthly or weekly payments.
- Soroban Powered: Secure and efficient execution on Stellar's smart contract platform.
flowfi/
├── backend/ # Express.js + TypeScript backend
├── contracts/ # Soroban smart contracts
│ ├── stream_contract/ # Core streaming logic
├── frontend/ # Next.js + Tailwind CSS frontend
├── docs/ # Documentation
│ └── ARCHITECTURE.md # Architecture overview
FlowFi consists of three main components that work together:
- Soroban Smart Contracts: Handle on-chain payment stream logic
- Backend API: Indexes on-chain events, provides REST API, and streams real-time updates via SSE
- Frontend: User interface for creating and managing payment streams
For a detailed explanation of how these components interact, where event indexing happens, and the overall system architecture, see the Architecture Documentation.
- Node.js & npm
- Rust & Cargo
- Stellar CLI (optional but recommended)
- Docker & Docker Compose (for containerized setup)
The fastest way to run the full stack locally:
docker compose up --buildThis starts:
- Postgres database on port
5432 - Backend API on port
3001
To run in detached mode:
docker compose up -d --buildTo stop the services:
docker compose downTo reset the database:
docker compose down -vcd backend
npm install
npm run devcd frontend
npm install
npm run devcd contracts
cargo build --target wasm32-unknown-unknown --releaseThe FlowFi backend API uses URL-based versioning. All endpoints are prefixed with a version (e.g., /v1/streams).
- API Versioning Guide: backend/docs/API_VERSIONING.md
- Deprecation Policy: backend/docs/DEPRECATION_POLICY.md
- Sandbox Mode: backend/docs/SANDBOX_MODE.md - Test without affecting production data
- Interactive API Docs: Available at
http://localhost:3001/api-docswhen backend is running - Raw OpenAPI JSON: Available at
http://localhost:3001/api-docs.jsonwhen backend is running
FlowFi supports sandbox mode for safe testing. Enable it by:
- Setting
SANDBOX_MODE_ENABLED=truein your.envfile - Adding
X-Sandbox-Mode: trueheader or?sandbox=truequery parameter to requests
Sandbox mode uses a separate database and clearly labels all responses. See Sandbox Mode Documentation for details.
Pre-built collections for exploring all endpoints without any manual setup.
| File | Client |
|---|---|
docs/api/flowfi.postman_collection.json |
Postman |
docs/api/flowfi.hoppscotch_collection.json |
Hoppscotch |
Environment files (import alongside the collection):
| File | Target |
|---|---|
docs/api/local.postman_environment.json |
Postman — local |
docs/api/test.postman_environment.json |
Postman — test |
docs/api/local.hoppscotch_environment.json |
Hoppscotch — local |
docs/api/test.hoppscotch_environment.json |
Hoppscotch — test |
Postman
- Import → select
flowfi.postman_collection.json. - Import → select the matching
*.postman_environment.json. - Pick the environment from the top-right dropdown and send requests.
Hoppscotch
- Collections → Import / Export → Import from JSON → select
flowfi.hoppscotch_collection.json. - Environments → Import → select the matching
*.hoppscotch_environment.json. - Activate the environment and send requests.
GET /events/subscribe streams text/event-stream data and keeps the connection open. Postman buffers the response — use Send and Download to capture it, or test interactively with:
curl -N --no-buffer 'http://localhost:3001/events/subscribe?all=true'Or open backend/test-sse-client.html directly in a browser.
Contributions are welcome! Please see our Contributing Guide for:
- Local development setup instructions
- Code style and commit guidelines
- Pull request process
- Development scripts and CI workflows
For architecture details, see docs/ARCHITECTURE.md.
If you discover a security vulnerability, please see our Security Policy for information on how to report it responsibly.
Have questions? Want to share ideas or projects? Join the conversation!
- ❓ Ask Questions - Get help in GitHub Discussions Q&A
- 💡 Share Ideas - Propose features and discuss improvements
- 🎪 Show and Tell - Share projects and use cases built with FlowFi
- 📖 Discussions Guide - Learn when to use Discussions vs Issues
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT