IXO USSD gateway

What the IXO USSD gateway is: an open-source service that lets people use IXO from any GSM phone, how a session works, and what it records on IXO.

The IXO USSD gateway is an open-source service that lets people use IXO from any GSM phone, with no smartphone, app or data plan. A person dials a short code such as *1234#, moves through menus with the number keys, and the gateway creates their identity, issues credentials or records their reports on IXO.

Read this page to understand how the gateway fits between a mobile network and IXO. To deploy it, use Deploy the IXO USSD gateway.

How a session works

USSD (Unstructured Supplementary Service Data) is a real-time text session built into every GSM network. The gateway sits between a telecom gateway and IXO.

The person dials

A person dials the service code on a GSM phone.

The telecom gateway forwards the session

The telecom gateway (such as Africa's Talking) sends the session to the IXO USSD gateway as an HTTP POST request.

The gateway answers

The gateway runs the input through an XState v5 state machine and returns a CON (continue) or END (close) response.

The session ends

The person moves through menus until the session completes or times out.

The result is recorded

Completed actions, such as creating an account, issuing a credential or reporting an activity, are recorded on the IXO Protocol and stored in an IXO Matrix data vault.

What it connects to

PartWhat the gateway does with it
IXO ProtocolCreates a Decentralized Identifier (DID) and a blockchain wallet for each new user, and writes claims on the user's behalf
IXO MatrixStores the user's encrypted data and private keys in a Matrix-based data vault
PostgreSQLKeeps session state between USSD interactions. Each session maps to a state machine instance keyed by session ID and phone number
Telecom gatewayAny gateway that sends HTTP POST requests with session ID, service code, phone number and text input. Africa's Talking is the reference integration

Each USSD flow is an XState v5 state machine. Parent machines run flows, and child machines handle single screens and their logic.

What people use it for

  • Registering without a smartphone. Collect a name, set a PIN, and create a DID and wallet.
  • Reporting activities. Field workers or household members report activities, such as clean cooking sessions, which can lead to a credential being issued.
  • Digital vouchers. Issue and redeem vouchers for goods or services through USSD menus.
  • Collecting data with no mobile data coverage. Only a GSM connection is needed.

Forking it

The gateway is built to be forked. The state machines, session management, database layer and IXO integrations are reusable. An operator forks the repository, defines their own USSD flows as state machines, and deploys against their own telecom gateway and IXO network.

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

What works today makes no statement about which networks USSD access is live on.

Where to go next