ixo-ussd is an open-source project that brings verifiable Web3 impact tools to any mobile phone — even without internet access 📱⚡.
Run it vanilla. Fork it. Build your own USSD-powered impact solutions.
Built as part of the IXO World ecosystem, it enables communities anywhere to interact with the global impact economy through simple, reliable USSD menus. Whether you’re connecting rural stewards, enabling on-chain verifications, or piloting local reward systems, ixo-ussd gives you the infrastructure to make it happen — securely, inclusively, and at scale.
The IXO USSD gateway makes it possible for anyone to access blockchain-powered tools on any GSM mobile phone — no smartphone or data plan required.
It’s built to be adaptable: fork this repo, start with the vanilla setup, and quickly customise it to your community, use cases, or technology stack.
- ✅ Offline-ready — works on any GSM mobile phone via USSD
- ⚡ Fast & lightweight — optimised for low-latency menu navigation
- 🔐 Secure — robust PIN handling, session management, and private data vaults
- 🔗 Integrates with IXO blockchain and Web3 identity tools
- 🐳 Integration test pipeline — record and replay USSD flows against ephemeral databases
Fork this project and adapt it for your own USSD use cases.
# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/ixo-ussd.git
cd ixo-ussd
pnpm install
# Configure environment
cp env.example .env
# Edit .env with your PostgreSQL details# Run migrations and start server
pnpm build && node dist/src/migrations/run-migrations.js
pnpm dev# Run unit tests
pnpm test
# Run integration flow tests (requires Docker)
pnpm test:integrationNeed detailed setup help? → Getting Started Guide
Ready to customize? → Architecture Guide
Need Web3 integration help? → Web3 Integration Guide
- Getting Started Guide - Setup, environment config, and first steps
- API Reference - USSD endpoints, request/response formats, and integration examples
- Architecture Patterns - State machine design patterns and best practices
- State Machine Development - Development workflow and testing patterns
- Demo Files Guide - Interactive development and testing tools
- Testing Guide - Unit tests, integration flow tests, and recording new flows
We ❤️ contributions! See our Contributing Guide and our Code of Conduct.
Quick steps:
- Fork & clone this repo
- Install dependencies:
npm install - Run tests:
npm test - Open a pull request 🎉
# Unit tests (mocked services)
pnpm test
# Integration flow tests (ephemeral Postgres via Docker)
pnpm test:integration- Unit tests — 126 tests with mocked database, IXO, and Matrix services
- Integration flow tests — 88 tests that replay recorded USSD sessions against a live server with an ephemeral database
See Testing Guide for full details on running, recording, and adding new flow tests.
We use Semantic Versioning and release via GitHub Actions. See CHANGELOG.md for history.
See our open issues for planned features and known issues. Vote on what’s next by adding 👍 reactions.
Apache 2.0 © 2025 IXO World
Thanks to all contributors and the open-source community 💚
A special thank you to the Grassroots Economics team for setting us down this path with their now-archived repo named cic-ussd 🌱