StellarPay

Stellar-MBC

A three-month open-source builder journey on Stellar. Focused on real, core contributions—no low-effort PRs. $2,000 rewarded every month to validated builders.

Fast, Cheap & Borderless Payrolls for the World

Built on Stellar Blockchain — powering global remittance, Early Wage Access (EWA), and modern payroll systems.

Live Demo • Getting Started • Documentation • Contributing

---

About

StellarPay is a next-generation remittance and payroll platform built on the Stellar blockchain. We leverage Soroban smart contracts to provide:

• Remittance Payments — Cross-border money transfers with near-zero fees
• Early Wage Access (EWA) — Get paid as you earn, no more waiting for payday
• On/Off-Ramp Payroll — Modern global payroll infrastructure for remote teams

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          StellarPay                                 │
├─────────────────┬─────────────────────┬─────────────────────────────┤
│     Client      │     Go Backend      │     Smart Contracts         │
│   (React/Vite)  │    (Horizon SDK)    │   (Rust/Soroban)            │
├─────────────────┼─────────────────────┼─────────────────────────────┤
│ • Freighter     │ • XLM Transfers     │ • EarlyWage Contract        │
│   Wallet        │ • Transaction       │ • Token Contract            │
│ • Soroban SDK   │   Signing           │ • Vault Management          │
│ • TailwindCSS   │ • CORS Support      │ • Employee Registry         │
└─────────────────┴─────────────────────┴─────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    │  Stellar Testnet  │
                    │   (Soroban RPC)   │
                    └───────────────────┘

---

⚙️ Tech Stack

Layer	Technology
Frontend	React 19, Vite, TailwindCSS 4, Stellar SDK
Backend	Go, Stellar Horizon SDK
Smart Contracts	Rust, Soroban SDK
Wallet	Freighter Browser Extension
Network	Stellar Testnet

---

Getting Started

Prerequisites

• Node.js v18+ and npm
• Go v1.21+
• Rust and Cargo (for contract development)
• Freighter Wallet browser extension (Install)

1️⃣ Clone the Repository

git clone https://github.com/your-username/Stellar-Pay.git
cd Stellar-Pay

2️⃣ Start the Go Backend

cd Go-Sdk
go mod download
go run main.go

The API will be running at http://localhost:8080

Available Endpoints:

Method	Endpoint	Description
POST	/api/send	Send XLM to a recipient
GET	/api/health	Health check

3️⃣ Start the React Client

cd client
npm install
npm run dev

The app will be running at http://localhost:5173

4️⃣ Connect Your Wallet

1. Install Freighter Wallet
2. Create/import a testnet account
3. Fund your account using Stellar Friendbot
4. Connect wallet in the StellarPay app

---

Project Structure

Stellar-Pay/
├── client/                    # React Frontend
│   ├── src/
│   │   ├── components/        # UI Components
│   │   │   ├── HomePage.jsx
│   │   │   ├── WithdrawForm.jsx
│   │   │   ├── PayCycleProgress.jsx
│   │   │   ├── TransactionHistory.jsx
│   │   │   └── SendMoneyModal.jsx
│   │   ├── hooks/             # Custom React Hooks
│   │   │   └── useWallet.js   # Freighter integration
│   │   ├── services/          # API & Blockchain Services
│   │   │   ├── apiService.js  # Go backend client
│   │   │   └── sorobanService.js  # Smart contract interactions
│   │   └── App.jsx
│   └── package.json
│
├── Go-Sdk/                    # Go Backend
│   ├── main.go                # API server & Stellar transactions
│   ├── go.mod
│   └── go.sum
│
├── early-wager-contract/      # Soroban Smart Contracts
│   └── contracts/
│       ├── early-wage/        # Main EWA contract
│       │   └── src/lib.rs
│       └── token/             # Token contract
│           └── src/
└── README.md

---

Smart Contract Functions

Early Wage Contract

Function	Description
register_employee(wallet, salary)	Register new employee
deposit_to_vault(from, amount, token)	Deposit funds to company vault
request_advance(emp_id, amount, token)	Request salary advance (1.25% fee)
get_remaining_salary(emp_id)	Check available salary balance
release_remaining_salary(emp_id, token, salary)	Release remaining salary
vault_balance(token)	Get vault balance

---

Why StellarPay?

Market Opportunity

Segment	Market Size	Problem	Our Solution
Remittance	$860B+ (2023)	6-8% fees, 1-5 day transfers	Near-zero fees, ~5 sec transfers
EWA	$200B+ by 2030	70%+ live paycheck-to-paycheck	Real-time earned wage access
Global Payroll	$40B+ (2024)	Complex cross-border payments	Crypto on/off-ramps

Stellar Advantage

Feature	Traditional	StellarPay
Transfer Fees	6–8%	~$0.00001
Transfer Time	1–5 days	~5 seconds
Bank Required	Yes	No
Global Access	Limited	Borderless

---

Contributing

We love contributions! StellarPay is open source and we welcome developers of all skill levels.

How to Contribute

1. Fork the repository

   git clone https://github.com/your-username/Stellar-Pay.git

2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes

   • Follow existing code style
   • Add tests if applicable
   • Update documentation

4. Commit your changes

   git commit -m "feat: add amazing feature"

   We follow Conventional Commits:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation
   • style: Formatting
   • refactor: Code restructuring
   • test: Adding tests
   • chore: Maintenance

5. Push and create a Pull Request

   git push origin feature/amazing-feature

Reporting Issues

Found a bug? Please open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Screenshots if applicable

💡 Feature Requests

Have an idea? We'd love to hear it! Open a feature request and describe:

• The problem you're trying to solve
• Your proposed solution
• Any alternatives you've considered

📋 Good First Issues

New to the project? Look for issues labeled:

• good first issue — Great for newcomers
• help wanted — We need your help!
• documentation — Help improve our docs

---

🛠️ Development

Running Tests

# Client tests
cd client
npm test

# Contract tests
cd early-wager-contract
cargo test

Building for Production

# Build client
cd client
npm run build

# Build contracts
cd early-wager-contract/contracts/early-wage
make build

Environment Variables

Create a .env file in the client directory:

VITE_RPC_URL=https://soroban-testnet.stellar.org
VITE_NETWORK=TESTNET
VITE_CONTRACT_TOKEN=your_token_contract_address
VITE_CONTRACT_WAGE=your_wage_contract_address

---

Screenshots

Dashboard	Withdraw

---

🗺️ Roadmap

• Core EWA smart contract
• React frontend with Freighter integration
• Go backend for XLM transfers
• Mobile app (React Native)
• Multi-currency support
• Employer dashboard
• Live FX rate optimization
• Mainnet deployment

---

📢 Live Demo

🔗 Coming soon...

---

🙏 Acknowledgments

• Stellar Development Foundation
• Soroban Smart Contracts
• Freighter Wallet

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with 💜 by the StellarPay Team

⭐ Star this repo if you find it useful!

Report Bug · Request Feature

## FAQ

How do I configure environment variables?

Create a .env file and add all required configuration values before running the project.

What should I do if wallet connection fails?

Verify wallet permissions, network settings, and browser compatibility.

How can I test remittance transactions safely?

Use the Stellar testnet before deploying or testing with real funds.

Troubleshooting

Application does not start

• Run dependency installation again
• Check environment variables
• Verify Node.js version

Wallet connection issues

• Refresh the browser
• Reconnect the wallet
• Check network configuration

Smart contract errors

• Verify contract deployment
• Check transaction logs
• Confirm correct network selection

Improvements

• Added FAQ section for developers
• Added troubleshooting guide
• Improved onboarding documentation
• Added common wallet and setup solutions