Fluxa

Cross-border payment infrastructure for emerging markets.

Fluxa is a programmable payments API built on the Stellar network. It gives fintech products and developers the primitives to move value across borders — wallet management, internal transfers, FX conversion via Stellar path payments, and settlement — behind a clean REST API.

Status: Active development — testnet only.

What it does

✅ Wallets — create Stellar accounts with AES-256-GCM encrypted secrets; never expose raw keys
✅ Transfers — async payment submission with queue-backed retry and status polling
✅ FX / Conversion — quote and execute cross-asset swaps via Stellar DEX path payments
✅ Settlement — background worker submits transactions to Stellar, handles retries, confirms on-chain
✅ Ledger indexer — streams Horizon events to keep local state in sync
✅ Multi-tenant — API key + JWT auth; individual developers and business organizations each get scoped access
✅ Webhooks — signed delivery of payment events to developer endpoints
🔜 Sandbox mode — sk_test_ keys route to Stellar testnet for safe integration testing
✅ Recurring payouts — scheduled transfers with daily/weekly/monthly cadence
✅ Fiat rails — deposit/withdrawal via Flutterwave integration
✅ Organization management — invite members, role-based access control (owner/admin/dev/viewer)

Architecture

Client Applications
        │  Authorization: Bearer sk_live_... or sk_test_...
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Fluxa REST API                             │
│  Chi router │ JWT + API key auth │ Rate limiting │ Tenant scope │
└─────────────────────────────────────────────────────────────────┘
        │
        ├── Wallet Service       ──► postgres: wallets, balances
        ├── Transfer Service     ──► postgres: transactions
        ├── FX Service           ──► Stellar DEX + rate cache (Redis)
        ├── Fee Service          ──► postgres: fees, fee_collections
        └── Webhook Dispatcher   ──► postgres: webhook_endpoints, deliveries
                │
                ▼  (Asynq job queue)
        ┌────────────────────────────────────────┐
        │           Background Worker             │
        │  Settlement Engine │ Ledger Indexer     │
        │  Reconciliation    │ Scheduler          │
        └────────────────────────────────────────┘
                │
                ▼
        Stellar Network (Horizon API + Soroban RPC)
        testnet: horizon-testnet.stellar.org
        mainnet: horizon.stellar.org

Two processes

Binary	Role
`cmd/api`	HTTP server — handles all REST requests, enqueues async work
`cmd/worker`	Asynq worker — settles transfers, runs ledger indexer, processes webhooks

Transfers are asynchronous. POST /v1/transfers returns 202 Accepted with a pending transaction immediately. Poll GET /v1/transfers/:id or receive a transfer.settled webhook for the final status.

Project Structure

fluxa/
├── cmd/
│   ├── api/main.go           # HTTP server entry point
│   └── worker/main.go        # Background worker entry point
├── internal/
│   ├── config/               # Viper env config
│   ├── domain/               # Core types: Wallet, Transaction, Conversion, errors
│   ├── crypto/               # AES-256-GCM encrypt/decrypt (stdlib only)
│   ├── assets/               # Asset registry: USDC/EURC issuers per network
│   ├── stellar/              # Horizon client, keypair generation, signer interface
│   ├── postgres/             # pgx/v5 repository implementations
│   ├── queue/                # Asynq client + task type definitions
│   ├── wallet/               # Wallet service + HTTP handler
│   ├── transfer/             # Transfer service + HTTP handler
│   ├── batch/                # Batch transfers + CSV export, reuses transfer settlement
│   ├── schedule/             # Recurring payouts + Asynq periodic task
│   ├── fx/                   # FX service + rate providers + HTTP handler
│   ├── fees/                 # Fee calculation and collection
│   ├── settlement/           # Settlement engine + Asynq task handler
│   ├── indexer/              # Ledger indexer + Asynq periodic task
│   ├── webhook/              # Webhook dispatcher + delivery worker
│   ├── reconcile/            # DB vs on-chain reconciliation
│   ├── apikey/               # API key generation, hashing, verification
│   ├── auth/                 # User registration, login, JWT
│   ├── org/                  # Organization members, roles
│   ├── fiat/                 # Fiat rail abstraction + provider adapters
│   ├── alerting/             # Alerting client for platform notifications
│   ├── tenant/               # Tenant context helpers
│   ├── server/               # Chi router setup, middleware
│   └── api/                  # Shared request validation + response helpers
└── db/
    └── migrations/           # golang-migrate SQL files (numbered up/down pairs)

Getting Started

Prerequisites

Go 1.22+
PostgreSQL 15+
Redis 7+

The repository root is a Go backend workspace. It does not require root-level Node.js, TypeScript, Prisma, or BullMQ tooling to build or run the API and worker.

1. Clone and install

git clone https://github.com/Savitura/Fluxa
cd Fluxa
go mod tidy

2. Configure environment

cp .env.example .env

Variable	Description
`PORT`	HTTP listen port (default: `3000`)
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string
`STELLAR_NETWORK`	`testnet` or `mainnet`
`STELLAR_HORIZON_URL`	Horizon endpoint
`STELLAR_USDC_ISSUER`	USDC issuer public key
`MASTER_ENCRYPTION_KEY`	64 hex chars (32 bytes) — encrypts stored wallet secrets
`PLATFORM_FEE_WALLET_PUBLIC_KEY`	Stellar address where platform fees are collected
`TREASURY_SECRET_KEY`	Stellar key that funds new accounts (testnet: leave empty, use Friendbot)

Generate a master key:

openssl rand -hex 32

3. Run migrations

make migrate

4. Start the API and worker

# Terminal 1
make run-api

# Terminal 2
make run-worker

API Reference

All endpoints are prefixed /v1. Auth: Authorization: Bearer <api_key_or_jwt>. Errors:

{ "error": { "code": "WALLET_NOT_FOUND", "message": "wallet not found" } }

Authentication

POST /v1/auth/register     Create account (individual or organization)
POST /v1/auth/login        Login — returns JWT
POST /v1/auth/refresh      Refresh access token
POST /v1/keys              Create API key  →  sk_live_... or sk_test_...
GET  /v1/keys              List keys (prefix only, never raw)
DELETE /v1/keys/:id        Revoke key

Wallets

POST /v1/wallets           Create wallet — returns public key only
GET  /v1/wallets/:id/balances   Live balances from Horizon (all assets)
POST /v1/wallets/:id/trustlines  Add Stellar trustline for a new asset

Transfers

POST /v1/transfers         Initiate transfer (202 Accepted — async)
GET  /v1/transfers/:id     Poll status
GET  /v1/transfers         List (filter by wallet, status, date)
POST /v1/transfers/batch   Up to 100 transfers in one call
GET  /v1/transfers/batch/:batchId          Batch status with per-transfer breakdown
GET  /v1/transfers/batch/:batchId/export   CSV download of batch results

Status flow: pending → confirmed | failed

Batch status is derived live from its linked transactions: pending → processing → partial | completed | failed.

Scheduled Payouts

POST   /v1/schedules       Create a recurring transfer (daily | weekly | monthly)
GET    /v1/schedules       List schedules
PATCH  /v1/schedules/:id   Pause, resume, or update amount/frequency/end_date
DELETE /v1/schedules/:id   Cancel a schedule

A background worker checks for due schedules every minute and enqueues a normal transfer for each one — a paused schedule is skipped until resumed.

FX

POST /v1/fx/quote          Get a 30-second exchange rate quote
POST /v1/fx/convert        Execute a currency swap
GET  /v1/fx/rates          Live rates for a currency pair

Webhooks

POST   /v1/webhooks        Register endpoint + event subscriptions
GET    /v1/webhooks        List endpoints
DELETE /v1/webhooks/:id    Remove endpoint
GET    /v1/webhooks/:id/deliveries  Delivery log

Event types: transfer.initiated · transfer.settled · transfer.failed · wallet.funded · conversion.completed

Fees

GET /v1/fees               Your fee schedule (transfer/conversion fee rates)

Organization

POST /v1/org/members/invite     Invite member to organization
GET  /v1/org/members            List organization members
PATCH  /v1/org/members/{userId}   Update member role
DELETE /v1/org/members/{userId}   Remove member
POST /v1/org/invites/accept     Accept organization invite (public)

Fiat Rails

POST /v1/wallets/{id}/deposit/fiat   Initiate fiat deposit
POST /v1/wallets/{id}/withdraw/fiat  Initiate fiat withdrawal
POST /v1/webhooks/fiat/{provider}   Fiat provider webhook receiver

Health

GET /health                Health check

Security

Key storage: Stellar secrets are encrypted with AES-256-GCM before storage. The 32-byte master key lives only in env — never in the database or logs.
No key exposure: Secret keys are never returned by any API endpoint.
Signer abstraction: stellar.Signer in internal/stellar/signer.go isolates all signing. Swap EnvSigner for HSM or AWS KMS without touching the settlement engine.
Decimal arithmetic: All monetary values use shopspring/decimal — no floating-point.
API key hashing: Raw keys are SHA-256 hashed before storage; the plaintext is shown exactly once on creation.

Development

make test          # go test ./... -race
make test-cover    # with HTML coverage report
make lint          # golangci-lint
make build         # outputs bin/api + bin/worker
make tidy          # go mod tidy

Fund a testnet wallet:

curl "https://friendbot.stellar.org?addr=<PUBLIC_KEY>"

Part of Savitura

CrowdPay — crowdfunding platform built on top of Fluxa payment rails
SaviTools — developer tools: API playground, transaction inspector, wallet sandbox

Contributing

See CONTRIBUTING.md.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps/web		apps/web
cmd		cmd
contracts/soroban/contract_wallet		contracts/soroban/contract_wallet
db/migrations		db/migrations
docs		docs
internal		internal
sdk		sdk
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
package-lock.json		package-lock.json

Navigation Menu

Repository files navigation

Fluxa

What it does

Architecture

Project Structure

Getting Started

Prerequisites

1. Clone and install

2. Configure environment

3. Run migrations

4. Start the API and worker

API Reference

Authentication

Wallets

Transfers

Scheduled Payouts

FX

Webhooks

Fees

Organization

Fiat Rails

Health

Security

Development

Part of Savitura

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Fluxa

What it does

Architecture

Project Structure

Getting Started

Prerequisites

1. Clone and install

2. Configure environment

3. Run migrations

4. Start the API and worker

API Reference

Authentication

Wallets

Transfers

Scheduled Payouts

FX

Webhooks

Fees

Organization

Fiat Rails

Health

Security

Development

Part of Savitura

Contributing

License

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages