Network API Gateway

Introduction

The PAiCore Network API Gateway (NAG) exposes telecom SS7 signaling networks through a simple HTTP/JSON API. Enterprises, MNOs, and OTT platforms can issue MAP operations against an HLR (authentication challenges, SMS routing lookups, location queries) without needing to operate an SS7 stack, an SCTP transport, or a global title themselves. NAG accepts a JSON request, performs the protocol exchange, and POSTs the result back to a callback URL.

This v1.0.0 release covers the SS7 MAP plane. Diameter support is planned for a future release.

Use Cases

• SIM-swap detection / silent authentication: verify a SIM is still bound to a known IMSI before approving a transaction (MAP_SAI).
• A2P SMS routing: discover which MSC/VLR is currently serving an MSISDN before sending a message (MAP_SRISM).
• Subscriber location for emergency, fraud, or LBS: request coarse cell-level location for a subscriber (MAP_SRILCS).
• Authentication-as-a-service for back-ends that need a real network witness, not a self-reported claim.

Architecture

The HTTP module accepts requests, deduplicates via Redis (60 s TTL), and publishes a Kafka event. The SS7 module consumes that event, executes the MAP operation through the jSS7 stack, and publishes the response back to Kafka. The HTTP module receives the response, claims the transaction atomically, and POSTs the result to the caller's callback_url. A scheduler fires explicit TIMEOUT callbacks if the network does not reply within the configured window. For a product overview, see paicore.tech/network-gw.

Supported MAP Operations

Command	Operation	Required input
MAP_SAI	SendAuthenticationInfo, returns auth vectors (2G/3G/4G) for an IMSI	imsi
MAP_SRISM	SendRoutingInfoForSM, returns the MSC/VLR currently serving an MSISDN	msisdn
MAP_SRILCS	SendRoutingInfoForLCS, returns LCS routing info for an MSISDN or IMSI	msisdn or imsi, plus mlcNumber

Prerequisites

• Docker with the Compose v2 plugin (docker compose)

Docker Images

The following pre-built images are published for each release:

Module	Image
HTTP module	paicbusinessdev/free-basic-nag-http-module:1.0.0-2
SS7 module	paicbusinessdev/free-basic-nag-ss7-module:1.0.0-2

Getting Started

# 1. Clone the repository (for docker-compose.yml and config)
git clone https://github.com/paicoretech/network-api-gateway.git
cd network-api-gateway

# 2. Pull images and start the full stack (Kafka + Redis + http + ss7 modules)
docker compose up -d

# 3. Send a sample MAP_SAI request
curl -X POST http://localhost:8080/signaling \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: replace-me' \
  -d '{
    "transaction_id": "demo-001",
    "protocol": "SS7_MAP",
    "command_type": "MAP_SAI",
    "imsi": "598991234567",
    "callback_url": "http://localhost:9999/callback"
  }'

The HTTP module responds immediately with 202 Accepted. The actual MAP exchange happens asynchronously; the result is delivered as a POST to callback_url. Without a real SCTP peer configured (the default sample points at 127.0.0.1), the callback arrives with a body like:

{
  "transaction_id": "demo-001",
  "status": "FAILED",
  "command_type": "MAP_SAI",
  "protocol": "SS7_MAP",
  "error_diagnostic": "SS7 stack not connected",
  "latency_ms": 0
}

With a real SCTP peer, a successful MAP_SAI returns auth vectors in the authentication_sets field.

Other MAP operations

# MAP_SRISM: routing info for SMS delivery
curl -X POST http://localhost:8080/signaling \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: replace-me' \
  -d '{"protocol":"SS7_MAP","command_type":"MAP_SRISM","msisdn":"598991234567","callback_url":"http://localhost:9999/callback"}'

# MAP_SRILCS: location services routing info
curl -X POST http://localhost:8080/signaling \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: replace-me' \
  -d '{"protocol":"SS7_MAP","command_type":"MAP_SRILCS","msisdn":"598991234567","mlc_number":"598990000001","callback_url":"http://localhost:9999/callback"}'

Configuration

The most common environment variables (see .env.example and docs/DEPLOYMENT.md for the full reference):

Variable	Default	Purpose
KAFKA_BOOTSTRAP_SERVERS	kafka:9092	Kafka broker address
REDIS_HOST	redis	Redis host for transaction state
API_KEY	replace-me	API key (validation gate not enforced in v1.0.0)
CALLBACK_TOKEN	replace-me	Token sent in the SGW-Callback-Token header on outbound callbacks
APP_TRANSACTION_TTL_SECONDS	60	How long transactions live in Redis
APP_CALLBACK_MAX_RETRIES	3	Retry attempts for failed callback POSTs
SERVER_PORT (HTTP)	8080	HTTP module listen port
SERVER_PORT (SS7)	8888	SS7 module listen port (actuator/health)

SS7 protocol-layer configuration lives in nag-ss7-module/config/ss7/*.xml. Point SCTP.xml at your real peer's address before connecting to a live telco network.

Building from Source

mvn -B clean install                           # build & install all three modules

The SS7 stack dependencies are built from the following PAiCore open-source projects:

• jSS7 v9.0.0-331: https://github.com/paicoretech/jSS7/releases/tag/v9.0.0-331
• SCTP 2.0.2-17: https://github.com/paicoretech/sctp/releases/tag/2.0.2-17

See docs/DEPLOYMENT.md for instructions on building Docker images locally from source.

Commercial Support

This open-source release reflects PAiCore Technology' commitment to community engagement. For enterprise-grade deployments, real SS7 interconnect provisioning, telco licensing guidance, or consulting on integration with your CRM/fraud/IAM stack, contact us:

🌐 https://paicore.tech

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines on filing issues, the PR process, code style, and testing requirements.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See the LICENSE file for the full text.