The IXO USSD gateway gives any GSM phone access to IXO services, with no smartphone or data plan. This guide takes you from a fork of the open-source gateway to a USSD server on your machine that accepts real or simulated sessions and writes results to the IXO Protocol. Build against a test network, never against mainnet.
The gateway is meant to be forked. You define your own USSD flows as XState v5 state machines. The session management, the database layer and the IXO service integrations are already built. For how the gateway is designed, see IXO USSD gateway architecture.
Before you start
- Node.js 20 or later
- pnpm (
npm install -g pnpm) - PostgreSQL 14 or later
- A telecom gateway account (such as Africa's Talking) for live USSD testing
- Docker, only for the integration tests
Fork and clone the repository
Fork ixoworld/ixo-ussd on GitHub, then clone your fork and install dependencies.
git clone https://github.com/YOUR_USERNAME/ixo-ussd.git
cd ixo-ussd
pnpm installConfigure environment variables
Copy the example environment file and edit it with your values.
cp env.example .envRequired variables
DATABASE_URL
- Description: PostgreSQL connection string
- Example:
postgres://user:pass@localhost:5432/ixo-ussd-dev
PIN_ENCRYPTION_KEY
- Description: 32-character key for PIN encryption
- Example: generate with
openssl rand -hex 16
LOG_LEVEL
- Description: Logging verbosity
- Example:
debug,info,warn,error
Optional variables
NODE_ENV
- Default:
development - Description: Environment mode
PORT
- Default:
3000 - Description: Server port
ZM_SERVICE_CODES
- Default:
*1234# - Description: USSD service codes, comma-separated
IXO_API_URL
- Default:
https://api.ixo.world - Description: IXO API endpoint
IXO_BLOCKCHAIN_URL
- Default:
https://rpc.ixo.world - Description: IXO blockchain RPC
The defaults of IXO_API_URL and IXO_BLOCKCHAIN_URL point at mainnet. While you build, set both
to the testnet rows in Networks and endpoints.
Set up the database and start the server
Create a PostgreSQL database, run migrations, then start the development server.
# Build the project
pnpm build
# Run database migrations
node dist/src/migrations/run-migrations.js
# Start the development server
pnpm devThe server starts at http://localhost:3000 by default.
Connect a telecom gateway
Most telecom USSD gateways send HTTP POST requests with a form-encoded or JSON body. The IXO USSD
gateway expects JSON at POST /api/ussd.
For Africa's Talking, add a callback URL that points to your server, and convert the request format:
// Convert Africa's Talking format and forward to the gateway
app.post('/ussd', async (req, res) => {
const response = await fetch('http://your-server/api/ussd', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
sessionId: req.body.sessionId,
serviceCode: req.body.serviceCode,
phoneNumber: req.body.phoneNumber,
text: req.body.text || ''
})
});
const ussdResponse = await response.text();
res.type('text/plain').send(ussdResponse);
});See the USSD gateway API reference for the full request and response format.
Check the result
Send a test request to confirm that the server accepts sessions.
curl -X POST http://localhost:3000/api/ussd \
-H "Content-Type: application/json" \
-d '{
"sessionId": "test-session-001",
"serviceCode": "*1234#",
"phoneNumber": "+260971234567",
"text": ""
}'A working server returns a CON response with the main menu text.
Check active sessions:
curl http://localhost:3000/api/ussd/sessionsCheck server health:
curl http://localhost:3000/healthWhen something goes wrong
Database connection failed
Confirm that PostgreSQL is running and that the DATABASE_URL in .env matches your setup.
# macOS
brew services start postgresql
# Ubuntu/Debian
sudo systemctl start postgresqlMissing PIN encryption key error
Generate a valid key and add it to .env:
echo "PIN_ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .envIXO account does not exist on chain
A new user account needs a small token balance to cover gas fees before the gateway can write on chain. Update your IXO feegrant configuration to cover gas for new accounts, or send a small amount to the generated address.
Migration failed
Check that the database exists and that the user has write permissions, then run the migrations again:
pnpm build && node dist/src/migrations/run-migrations.jsNext steps
Request and response formats, session endpoints and error codes.
IXO USSD gateway architectureThe state machine design and the integration model.
Architecture patterns guidePatterns for building your own USSD flows.
(opens in a new tab)IXO networks and endpointsThe mainnet and testnet connection details.