Deploy the IXO USSD gateway

Fork, configure and run the open-source IXO USSD gateway on a test network, connect a telecom gateway, and check that it accepts USSD sessions.

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 install

Configure environment variables

Copy the example environment file and edit it with your values.

cp env.example .env

Required 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

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 dev

The 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/sessions

Check server health:

curl http://localhost:3000/health

When 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 postgresql

Missing PIN encryption key error

Generate a valid key and add it to .env:

echo "PIN_ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env

IXO 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.js

Next steps