Mudrex-API-Copilot/README.md at main · DecentralizedJM/Mudrex-API-Copilot

███╗   ███╗██╗   ██╗██████╗ ██████╗ ███████╗██╗  ██╗
████╗ ████║██║   ██║██╔══██╗██╔══██╗██╔════╝╚██╗██╔╝
██╔████╔██║██║   ██║██║  ██║██████╔╝█████╗   ╚███╔╝ 
██║╚██╔╝██║██║   ██║██║  ██║██╔══██╗██╔══╝   ██╔██╗ 
██║ ╚═╝ ██║╚██████╔╝██████╔╝██║  ██║███████╗██╔╝ ██╗
╚═╝     ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
 █████╗ ██████╗ ██╗ ██████╗ ██████╗ ██████╗ ██╗██╗      ██████╗ ████████╗
██╔══██╗██╔══██╗██║██╔════╝██╔═══██╗██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝
███████║██████╔╝██║██║     ██║   ██║██████╔╝██║██║     ██║   ██║   ██║   
██╔══██║██╔═══╝ ██║██║     ██║   ██║██╔═══╝ ██║██║     ██║   ██║   ██║   
██║  ██║██║     ██║╚██████╗╚██████╔╝██║     ██║███████╗╚██████╔╝   ██║   
╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝

An API Copilot for the Mudrex Futures API community. Helps developers with code examples, API integration, error debugging, and onboarding.

Reactive mode: The bot responds only when explicitly engaged (@mentioned, replied to, or quote+mention). It does not auto-respond to keywords.

Recent updates
Features
Architecture
Quick start
Project structure
Bot commands
When the bot responds
MCP integration
RAG pipeline
Bot persona
Environment variables
Community resources
Development & deployment
License & author

Recent updates

Area	Change
Railway	SIGTERM handler so the bot stops polling immediately on deploy; `drop_pending_updates` on start; 25s startup delay; single-replica recommended.
API check	“Is API down?” → two-step reply: “Let me check.” → typing → live ping result + test snippet + “share error code if you need help.”
Greetings	“How are you” and similar get a short reply only (no code/scripts).
Confidentiality	Questions about how the copilot works or building a similar bot → redirect to @DecentralizedJM.
Mudrex loyalist	“Which platform?” / “Is Mudrex reliable?” → praise Mudrex + “I’m here to help.”
Coming soon	Klines, Webhooks, TradingView, subbroker, INR Futures, WebSockets → “on the roadmap / product prioritized” style replies.
Hallucination	Legacy docs removed; strict endpoint validation; template responses for missing features.

Features

Category	Description
Code-first	Working Python/JS snippets for “how to” questions; no scripts for greetings.
Error debugging	Analyzes logs, error codes, and suggests fixes.
RAG pipeline	Query planning, vector search, relevancy validation, rerank, Gemini generation.
Hallucination prevention	Only Mudrex docs; validated context; template replies for known missing features.
Live API check	“Is API down?” triggers a real HTTP ping and returns status + test snippet.
MCP	Live market data via Mudrex MCP (500+ futures pairs).
Caching	Redis for query/response and semantic cache to reduce Gemini calls.
Context	Conversation context and semantic memory for follow-ups.

Architecture

High-level system

flowchart TB
    subgraph External["External"]
        TG[Telegram]
        MUDREX[Mudrex Futures API]
    end

    subgraph App["Mudrex API Copilot"]
        Bot[Telegram Bot\nReactive only]
        Health[Health Server :8080]
        RAG[RAG Pipeline]
        MCP[MCP Client]
    end

    subgraph Storage["Storage & AI"]
        VS[Vector Store\nQdrant / Pickle]
        Redis[(Redis\nCache)]
        Gemini[Gemini\nGeneration]
    end

    TG --> Bot
    Bot --> RAG
    RAG --> VS
    RAG --> Redis
    RAG --> Gemini
    RAG --> MCP
    MCP --> MUDREX
    Bot --> Health

Request flow (message → response)

flowchart LR
    subgraph In["Incoming"]
        M[User @mentions bot]
    end

    subgraph Bot["Bot layer"]
        M --> Rate[Rate limit]
        Rate --> Greet{Greeting?}
        Greet -->|Yes| Short[Short reply\nno RAG]
        Greet -->|No| Conn{API down?}
        Conn -->|Yes| Ping[Let me check\n→ Ping API\n→ Result + snippet]
        Conn -->|No| RAG[Pipeline.query]
    end

    subgraph Pipeline["Pipeline short-circuits"]
        RAG --> OffTopic{Off-topic?}
        OffTopic -->|Yes| Short2[Short reply]
        OffTopic -->|No| BotArch{Bot architecture?}
        BotArch -->|Yes| Redirect[Redirect @DecentralizedJM]
        BotArch -->|No| Loyal{Platform choice?}
        Loyal -->|Yes| Praise[Mudrex loyalist reply]
        Loyal -->|No| Cache{Cache hit?}
        Cache -->|Yes| Cached[Cached answer]
        Cache -->|No| Retrieve[Vector search\n+ Validate + Rerank]
        Retrieve --> Gen[Gemini generate]
    end

    Short --> Out[Response]
    Ping --> Out
    Short2 --> Out
    Redirect --> Out
    Praise --> Out
    Cached --> Out
    Gen --> Out

RAG pipeline stages

flowchart TB
    Q[User question] --> Plan[Query planner]
    Plan --> Canned{Canned?}
    Canned -->|Greeting / off-topic / bot-arch / loyalist| Reply1[Short reply]
    Canned -->|Connectivity| Ping[Live API ping]
    Canned -->|No| Cache{Redis / semantic cache?}
    Cache -->|Hit| Reply2[Cached reply]
    Cache -->|Miss| VS[Vector search\nembeddings]
    VS --> Validate[Relevancy validation]
    Validate --> Rerank[LLM rerank]
    Rerank --> Context[Build context]
    Context --> Gemini[Gemini generate]
    Gemini --> Reply3[Final answer]
    Ping --> Reply4[Status + snippet]

Component diagram

flowchart TB
    subgraph Entry["Entry"]
        main[main.py]
    end

    subgraph Bot["Bot"]
        main --> telegram_bot[telegram_bot.py]
        main --> health[health.py]
    end

    subgraph RAG["RAG"]
        pipeline[pipeline.py]
        query_planner[query_planner.py]
        vector_store[vector_store.py]
        gemini_client[gemini_client.py]
        document_loader[document_loader.py]
        cache[cache.py]
        semantic_cache[semantic_cache.py]
        context_manager[context_manager.py]
        semantic_memory[semantic_memory.py]
        fact_store[fact_store.py]
    end

    subgraph MCP["MCP"]
        client[mcp/client.py]
        tools[mcp/tools.py]
    end

    subgraph Tasks["Tasks"]
        scheduler[scheduler.py]
        changelog_watcher[changelog_watcher.py]
        futures_listing_watcher[futures_listing_watcher.py]
    end

    telegram_bot --> pipeline
    pipeline --> query_planner
    pipeline --> vector_store
    pipeline --> gemini_client
    pipeline --> cache
    pipeline --> semantic_cache
    pipeline --> context_manager
    main --> client
    telegram_bot --> client
    main --> scheduler

Quick start

1. Clone & install

git clone https://github.com/DecentralizedJM/Mudrex-API-Copilot.git
cd Mudrex-API-Copilot

python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

pip install -r requirements.txt

2. Configure

cp .env.example .env

Required:

Variable	Description
`TELEGRAM_BOT_TOKEN`	Telegram bot token
`GEMINI_API_KEY`	Google Gemini API key

Optional:

Variable	Description
`MUDREX_API_SECRET`	Mudrex API secret (live data, MCP)
`REDIS_URL`	Redis URL (caching)
`ADMIN_USER_IDS`	Comma-separated admin Telegram IDs
`QDRANT_URL` / `QDRANT_API_KEY`	Qdrant Cloud (production vector store)

3. Run

python3 main.py

Project structure

├── main.py                    # Entry point; health server; RAG + MCP + bot init
├── railway.json               # Railway deploy (overlap=0, draining=30)
├── Dockerfile
├── requirements.txt
├── .env.example
│
├── src/
│   ├── bot/
│   │   └── telegram_bot.py    # Reactive handlers; rate limit; connectivity 2-step
│   ├── config/
│   │   └── settings.py       # Config and validation
│   ├── health.py              # Health server (Railway)
│   ├── rag/
│   │   ├── pipeline.py      # Query orchestration; short-circuits; RAG stages
│   │   ├── query_planner.py  # Greeting / code / error / mudrex classification
│   │   ├── vector_store.py   # Embeddings; Qdrant or pickle
│   │   ├── gemini_client.py  # Gemini generate; missing-feature templates
│   │   ├── document_loader.py
│   │   ├── cache.py          # Redis query/response cache
│   │   ├── semantic_cache.py # Similar-query cache
│   │   ├── context_manager.py
│   │   ├── semantic_memory.py
│   │   └── fact_store.py
│   ├── mcp/
│   │   ├── client.py         # MCP connection and tools
│   │   └── tools.py
│   └── tasks/
│       ├── scheduler.py      # Daily changelog scrape + ingest
│       ├── changelog_watcher.py
│       └── futures_listing_watcher.py
│
├── docs/                      # RAG source (Markdown)
├── scripts/
│   ├── ingest_docs.py        # Ingest docs into vector store
│   ├── scrape_docs.py        # Scrape API docs
│   └── scrape_api_docs.py
│
└── tests/

Bot commands

Command	Description
`/help`	Help and usage
`/endpoints`	API endpoints with doc links
`/listfutures`	Count of futures pairs
`/tools`	MCP tools list
`/mcp`	MCP setup for Claude Desktop
`/stats`	Bot stats (admin)

Admin: /learn <text>, /set_fact KEY value, /delete_fact KEY

When the bot responds

The bot is reactive only:

@mentioned in a message
Replied to (continuation)
Quote + mention (reply to someone else’s message and tag the bot)

It does not respond to plain keywords without engagement.

MCP integration

Live data via Mudrex MCP. Read-only tools: list_futures, get_future, get_orders, get_positions, get_leverage, get_liquidation_price, get_available_funds, get_fee_history, etc. Write/confirm tools: place_order, cancel_order, close_position, set_leverage, etc.

Claude Desktop config:

{
  "mcpServers": {
    "mcp-futures-trading": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mudrex.com/mcp", "--header", "X-Authentication:${API_SECRET}"],
      "env": {"API_SECRET": "<your-api-secret>"}
    }
  }
}

Docs: https://docs.trade.mudrex.com/docs/mcp

RAG pipeline

Query planner — Canned (greeting, off-topic, bot-arch, loyalist), connectivity, or full RAG.
Short-circuits — Off-topic, bot-architecture, Mudrex loyalist, API-down ping, cache.
Retrieval — Vector search → relevancy validation → rerank.
Generation — Context + Gemini; template responses for missing features (Klines, Webhooks, TradingView, etc.).

Hallucination prevention: Only Mudrex docs in context; relevancy threshold; “coming soon” templates for known missing features.

Bot persona

Does: Code examples (when asked), error debugging, auth/docs links, Mudrex-positive answers for “which platform?”
Doesn’t: Auto-respond to keywords, give trading advice, explain how the copilot is built (→ @DecentralizedJM).
Out of scope: “Couldn’t find that. Docs: https://docs.trade.mudrex.com — @DecentralizedJM can help.”

Environment variables

Variable	Required	Default	Description
`TELEGRAM_BOT_TOKEN`	Yes	-	Telegram bot token
`GEMINI_API_KEY`	Yes	-	Gemini API key
`MUDREX_API_SECRET`	No	-	Mudrex API secret
`GEMINI_MODEL`	No	`gemini-3-flash-preview`	Gemini model
`REDIS_ENABLED`	No	`false`	Enable Redis cache
`REDIS_URL`	No	`redis://localhost:6379`	Redis URL
`QDRANT_URL` / `QDRANT_API_KEY`	No	-	Qdrant Cloud
`ADMIN_USER_IDS`	No	-	Admin Telegram IDs
`ALLOWED_CHAT_IDS`	No	-	Allowed group IDs
`BOT_STARTUP_DELAY`	No	25 (Railway)	Seconds before bot starts (deploy conflict)
`SIMILARITY_THRESHOLD`	No	`0.45`	Vector similarity
`RELEVANCY_THRESHOLD`	No	`0.6`	Doc relevancy min
`RERANK_TOP_K`	No	`5`	Docs after rerank

Community resources

Python SDK: https://github.com/DecentralizedJM/mudrex-api-trading-python-sdk
Trade Ideas Broadcaster: https://github.com/DecentralizedJM/TIA-Service-Broadcaster
API docs: https://docs.trade.mudrex.com
MCP docs: https://docs.trade.mudrex.com/docs/mcp

Development & deployment

Local:

LOG_LEVEL=DEBUG python3 main.py
python3 scripts/scrape_docs.py && python3 scripts/ingest_docs.py

Railway:

Connect GitHub repo.
Set env vars (token, Gemini, optional Redis, Qdrant).
Use one replica to avoid Telegram Conflict.
Optionally set BOT_STARTUP_DELAY=40 if conflicts persist.

See docs/troubleshooting_bot.md for Telegram 409 Conflict.

License & author

License: MIT — see LICENSE.
Author: DecentralizedJM

Built for the Mudrex developer community

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Table of contents

Recent updates

Features

Architecture

High-level system

Request flow (message → response)

RAG pipeline stages

Component diagram

Quick start

1. Clone & install

2. Configure

3. Run

Project structure

Bot commands

When the bot responds

MCP integration

RAG pipeline

Bot persona

Environment variables

Community resources

Development & deployment

License & author

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Table of contents

Recent updates

Features

Architecture

High-level system

Request flow (message → response)

RAG pipeline stages

Component diagram

Quick start

1. Clone & install

2. Configure

3. Run

Project structure

Bot commands

When the bot responds

MCP integration

RAG pipeline

Bot persona

Environment variables

Community resources

Development & deployment

License & author