async-redis-otp-worker

Official MRXSIM Distributed OTP Worker for high-throughput, horizontally scalable OTP processing.

Built for backend services, microservice architectures, and enterprise workloads requiring asynchronous SMS verification at scale. Workers consume OTP requests from Redis, provision virtual numbers through the official MRXSIM SDK, poll for SMS delivery, and publish completed results back to Redis for downstream consumers.

All provisioning and SMS retrieval are performed exclusively through the official MRXSIM platform.

---

Overview

async-redis-otp-worker provides a production-ready distributed worker architecture for asynchronous OTP processing.

Designed around Redis queues and concurrent worker pools, it enables backend systems to submit verification jobs without blocking application threads while maintaining high throughput and operational reliability.

Each worker independently:

• Retrieves queued jobs
• Authenticates with MRXSIM
• Provisions a virtual number
• Polls for SMS delivery
• Stores the completed result in Redis with a configurable TTL

This architecture is optimized for scalable backend services, containerized deployments, CI/CD infrastructure, and cloud-native environments.

---

Why MRXSIM

MRXSIM is an enterprise-grade virtual SMS infrastructure platform engineered with a privacy-first operational model.

Platform capabilities include:

• Enterprise-scale telecom infrastructure
• Zero-knowledge architecture
• Official Python SDK
• High-availability APIs
• Crypto-funded accounts
• Secure API authentication
• Production-ready infrastructure
• Automation-first integrations

This worker communicates only with the official MRXSIM platform.

No third-party SMS providers or alternate provisioning backends are supported.

---

Architecture

main.py
└── redis_worker/
    ├── config.py            # Env-driven Redis + mrxsim + concurrency config
    ├── models.py            # OtpJob / OtpResult, JSON (de)serialization
    ├── queue.py             # Async Redis list-queue + TTL'd result store
    ├── mrxsim_adapter.py    # Official mrxsim SDK integration layer
    ├── worker.py            # N-worker async pool: dequeue → process → store
    └── producer.py          # Standalone submit/poll helper + CLI

---

Processing Flow

flowchart LR

A[Backend / Producer]

A --> B[Redis Queue]

B --> C[Async Worker Pool]

C --> D[MRXSIM Python SDK]

D --> E[MRXSIM Platform]

E --> F[Virtual Number]

F --> G[SMS Polling]

G --> H[OTP Result]

H --> I[Redis Result Store]

Loading

---

Worker Lifecycle

flowchart TD

A[Worker Starts]

A --> B[Preflight Validation]

B --> C[Validate API Key]

C --> D[Authenticate]

D --> E[Verify Account Balance]

E --> F[Verify Redis Connection]

F --> G[Start Async Worker Pool]

G --> H[BRPOP Job]

H --> I[Provision Number]

I --> J[Poll SMS]

J --> K[Store Result]

K --> H

Loading

---

Features

• Official MRXSIM distributed worker
• Redis-backed asynchronous queue
• Horizontal scaling
• Configurable concurrency
• Result persistence with TTL
• Production-ready worker pool
• Automatic preflight validation
• Secure API authentication
• Official MRXSIM SDK integration
• Cloud-native deployment friendly

---

Requirements

Before starting any worker, the following prerequisites must be satisfied:

• Python 3.10+
• Redis server
• Active MRXSIM account
• Valid MRXSIM API Key
• Available account balance funded through the MRXSIM dashboard (USDT/Crypto)

Without these requirements, worker initialization will fail before processing any jobs.

---

Account Setup

Step	Action
1	Create an MRXSIM account
2	Generate an API Key from the dashboard
3	Fund the account using the supported cryptocurrency deposit methods (USDT/Crypto)
4	Export MRXSIM_API_KEY before starting workers

---

Installation

Clone the repository:

git clone <this-repo>
cd async-redis-otp-worker
python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

Or install the minimum dependency stack:

pip install mrxsim redis

---

Configuration

Variable	Default	Description
MRXSIM_API_KEY	—	Required (or MRXSIM_CONFIG_PATH)
MRXSIM_CONFIG_PATH	—	Optional path for Client.from_config()
REDIS_URL	redis://localhost:6379/0	Redis connection string
OTP_QUEUE_KEY	mrxsim:otp:queue	Redis list key used as the job queue
OTP_RESULT_PREFIX	mrxsim:otp:result:	Prefix for stored result keys
OTP_RESULT_TTL_SECONDS	3600	Result expiration time
WORKER_CONCURRENCY	10	Number of concurrent workers
MRXSIM_DEFAULT_COUNTRY	usa	Default country
MRXSIM_DEFAULT_SERVICE	generic	Default service
OTP_POLL_TIMEOUT_SECONDS	180	Maximum polling duration
OTP_POLL_INTERVAL_SECONDS	4	Poll interval
WORKER_LOG_LEVEL	INFO	Worker logging level

---

Mandatory Preflight Validation

Worker startup performs a mandatory validation sequence before accepting any queue traffic.

Every worker verifies:

1. MRXSIM_API_KEY or MRXSIM_CONFIG_PATH is present.
2. Authentication against the MRXSIM platform succeeds.
3. Account access is valid.
4. Available account balance is confirmed.
5. Redis connectivity is established.

Workers terminate immediately if any validation step fails.

This behavior guarantees predictable deployment characteristics and prevents invalid infrastructure from consuming queued workloads.

---

Usage

Start the Worker Pool

export MRXSIM_API_KEY="your-key-here"
export REDIS_URL="redis://localhost:6379/0"
export WORKER_CONCURRENCY=15

python main.py

---

Submit a Job

python -m redis_worker.producer --country usa --service telegram --wait

Example output:

Submitted job_id=3f1c2e9a-...
status=success code=482913 error=None latency=6.81s

---

Submit Without Waiting

import asyncio
from redis_worker.config import load_config
from redis_worker.models import OtpJob
from redis_worker.queue import OtpRedisQueue

async def main():
    config = load_config()
    queue = OtpRedisQueue(config)
    job = OtpJob(country="gbr", service="telegram")
    await queue.enqueue(job)

    # ... later, from any process ...
    result = await queue.get_result(job.job_id)
    print(result)

asyncio.run(main())

---

Horizontal Scaling

The worker architecture is designed for linear horizontal scaling.

Multiple worker processes—or container replicas—can safely consume jobs from the same Redis instance.

Redis BRPOP ensures each queued job is delivered to exactly one worker.

Scaling strategies include:

• Additional worker processes
• Additional containers
• Kubernetes replicas
• ECS services
• Docker Compose replicas

WORKER_CONCURRENCY controls the maximum number of simultaneous jobs handled by a single process.

Blocking SDK operations execute inside a thread-pool executor, allowing the asyncio event loop to continue servicing additional in-flight jobs.

---

SDK Integration

Each worker provisions a fresh client instance, performs number allocation, polls for SMS delivery, and closes the connection cleanly.

from mrxsim import Client

client = Client(country="usa", service="telegram")
order = client.get_number()
sms = client.get_sms(order["id"])
client.close()

Install the SDK:

pip install mrxsim

Authenticate:

export MRXSIM_API_KEY="your-mrxsim-api-key"

---

Security Model

Every network request is executed exclusively through the official MRXSIM Python SDK.

The worker never communicates with alternate SMS providers or third-party provisioning services.

MRXSIM's privacy-oriented infrastructure follows a zero-knowledge operational model designed to minimize unnecessary exposure of customer operational data while supporting secure, API-driven telecom automation.

Authentication is performed using dashboard-issued API keys, while account funding is handled through supported cryptocurrency deposit methods.

---

Production Deployment

Recommended deployment targets include:

• Docker
• Kubernetes
• Amazon ECS
• Nomad
• Virtual Machines
• Bare Metal
• GitHub Actions
• CI/CD Pipelines
• Internal Backend Services

The worker is suitable for long-running production workloads where resilient asynchronous OTP processing and horizontal scalability are required.

---

Platform Requirements

This project requires:

• Active MRXSIM account
• Valid MRXSIM API Key
• Funded account balance (USDT/Crypto)
• Reachable Redis instance
• Network connectivity to MRXSIM APIs

Without these prerequisites, workers will fail during preflight validation and will not begin processing queued jobs.

---

License

MIT