Skip to main content
The IXO USSD gateway is an open-source tool that makes IXO Protocol services accessible from any GSM phone — no smartphone, app, or data plan required. This page explains its architecture and role in the IXO ecosystem. For setup instructions, see the developer guide.

​
Role in the IXO ecosystem

USSD (Unstructured Supplementary Service Data) is a real-time text session protocol built into every GSM network. A user dials a short code such as *1234#, navigates menus via number keys, and receives responses — all within a live network session. The IXO USSD gateway sits between a telecom network and IXO services. It receives USSD sessions from a telecom gateway, processes user input through configurable state machine flows, and calls IXO Protocol and IXO Matrix services to create identities, issue credentials, and record verifiable impact data.
  1. A user dials the USSD service code on any GSM phone.
  2. The telecom gateway (such as Africa’s Talking) forwards the session to the IXO USSD gateway as an HTTP POST request.
  3. The gateway processes the input through an XState v5 state machine and returns a CON (continue) or END (close) response.
  4. The user navigates menus until the session completes or times out.
  5. Completed actions — account creation, credential issuance, impact reporting — are recorded on the IXO Protocol and stored in an IXO Matrix data vault.
The gateway integrates with:
  • IXO Protocol — creates Decentralized Identifiers (DIDs) and blockchain wallets for new users, and writes verifiable claims on behalf of the user
  • IXO Matrix — stores encrypted user data and private keys in a Matrix-based data vault
  • PostgreSQL — maintains session state across USSD interactions for each user
The gateway is designed to be forked and adapted. The core framework — state machines, session management, database layer, and IXO service integrations — is reusable across any impact use case. Operators fork the repository, define their own USSD flows as state machines, and deploy against their own telecom gateway and IXO network.

​
Concept model

State machines

Each USSD flow is an XState v5 state machine. Parent machines orchestrate flows; child machines handle specific screens and business logic.

Session management

PostgreSQL stores active session state. Each USSD session maps to a state machine instance keyed by session ID and phone number.

Telecom gateway bridge

Any telecom gateway that sends HTTP POST requests with session ID, service code, phone number, and text input is compatible. Africa’s Talking is the reference integration.

IXO identity and credentials

On account creation, the gateway generates a DID and blockchain wallet for the user, and stores encrypted credentials in an IXO Matrix data vault.

​
Typical use cases

Offline user onboarding

Register community members on IXO without a smartphone — collect name, set a PIN, create a DID and wallet.

Impact activity reporting

Let field workers or household members report verified activities (such as clean cooking sessions) via USSD, triggering credential issuance on-chain.

Digital voucher management

Issue and redeem digital vouchers for goods or services through USSD menus, with on-chain settlement.

Low-connectivity data collection

Collect structured data from areas with no mobile data coverage using only voice-quality GSM connectivity.

​
Reference implementation

Emerging Household Energy (Supamoto) uses the IXO USSD gateway as the offline access channel for rural household members in Zambia. The Supamoto deployment is maintained as an open-source fork at emerging-eco/ixo-ussd-supamoto. See USSD access channel for details.

​
Go here next

Deploy the IXO USSD gateway

Fork, configure, and run the gateway for your use case.

USSD gateway API

Endpoint reference for the USSD session API.

Use IXO via USSD

End-user guide for accessing IXO services on a basic phone.

Source repository

Fork the open-source IXO USSD gateway on GitHub.