Knowledge Base

When you submit a signal via /track or the Track page, AgoraIQ's parser extracts structured data from your raw text. The parser is deliberately flexible — it handles dozens of common signal formats used across Telegram and Discord providers.

What the parser extracts:

• Symbol — Recognized formats: BTCUSDT, BTC/USD, BTC-USDT, XBTUSD. All normalized to XXXUSDT.
• Direction — LONG, BUY → LONG. SHORT, SELL → SHORT.
• Entry price — Extracted from "Entry:", "Buy zone:", "Enter at:", etc. Supports K notation (65k = 65000).
• Stop loss — Extracted from "SL:", "Stop Loss:", "Stop:".
• Targets — Extracted from "TP1:", "TP2:", "Target 1:", etc. Up to 5 levels.
• Leverage — Pattern: "10X", "5x", etc.

Parse status values:

Only parsed and partial signals are accepted. not_signal returns a 422 error.

Every signal in AgoraIQ follows a defined lifecycle with full audit trail:

State transitions:

• OPEN → TP1/TP2/TP3 — Price hits a take-profit level. The resolver marks which TP was hit and calculates realized PnL as a decimal ratio (0.032 = 3.2%).
• OPEN → SL — Price hits stop loss. Loss recorded.
• OPEN → EXPIRED — Signal exceeds max age (default 7 days) without resolution.
• OPEN → CANCELLED — User manually cancelled.

Audit events logged:

Every state change is recorded in the signal_events table with: old status, new status, price at time of event, PnL at event, timestamp, and metadata (who/why). This provides a complete, immutable lifecycle audit for each signal.

Signals can enter AgoraIQ from four sources:

Regardless of source, every signal passes through Signal.normalize(), which applies consistent field names, validates ranges, converts confidence scores to 0–100, and stores the result in the signals_v2 table.

Symbol normalization examples:

• BTC/USD, BTC-USDT, BTCUSD, XBTUSD → BTCUSDT
• ETH → ETHUSDT
• Already XXXUSDT → unchanged

The AgoraIQ market scanner runs as a PM2 process, executing every 5 minutes. It monitors the top crypto perpetual futures pairs on Binance and Kraken.

Data points collected per scan cycle:

• 24h volume and volume change percentage
• Open interest and OI direction (rising/falling)
• Funding rate (positive = longs paying shorts, negative = shorts paying longs)
• Price change percentage (1h, 4h, 24h)

Scoring: Each pair receives a breakout score (0–100) based on a weighted combination of volume spike magnitude, OI trend, funding rate extreme, and price momentum. Pairs scoring above threshold generate scanner signals.

Categories available:

• /top — Highest breakout scores
• /momentum — Strongest price momentum
• /volume — Largest volume spikes
• /oi — Biggest open interest changes
• /funding — Most extreme funding rates

Scanner results are cached in the scanner_cache table with TTL, ensuring fast lookups even under load.

The breakout score is a composite metric from 0 to 100 that represents how likely a pair is to experience a significant price move. Higher is stronger.

Score ranges:

The score does not indicate direction (long or short). Direction is determined separately based on OI trend and price action. A high score with rising OI suggests long; high score with falling OI and negative funding suggests short.

AgoraIQ uses an entitlement model separate from raw billing status. Your plan access is derived from your subscription state, not just the latest database row.

Subscription states and what they mean for access:

This means if you cancel your Pro plan mid-month, you continue to have full Pro access until the end of that billing cycle. If a payment fails, you get a 3-day grace period to update your card before losing access.

Plan gating is enforced server-side. Even if you access a Pro endpoint from a Free account, the API returns limited data — the frontend does not make access decisions.

AgoraIQ uses Stripe Checkout for all payment processing. This means:

• Card data never touches AgoraIQ servers. You enter your card on Stripe's hosted checkout page.
• PCI compliance is handled entirely by Stripe (PCI DSS Level 1).
• 256-bit TLS encryption on all payment communication.
• Webhook verification — Every Stripe event is cryptographically signed and verified before processing. Duplicate events are rejected via idempotency checks.

AgoraIQ stores only: your Stripe customer ID (for managing your subscription) and subscription ID (for tracking status). No card numbers, CVVs, or sensitive payment data is ever stored in our database.

Linking your Telegram account to AgoraIQ uses a secure, one-time code flow:

1. You type /connect in the bot.
2. The bot generates a unique link with a one-time code.
3. You open the link in your browser (must be logged into AgoraIQ).
4. The web page claims the code, binding your Telegram user ID to your AgoraIQ account.

Security details:

• Codes expire after 5 minutes.
• Codes are single-use — claiming it a second time fails.
• Your AgoraIQ JWT token is encrypted at rest in the bot's local store using Fernet (AES-128-CBC + HMAC-SHA256).
• No passwords are ever exchanged via Telegram.

Use /disconnect to unlink at any time. This removes your encrypted token from the bot's store.

When a new signal is generated or a tracked signal resolves, AgoraIQ's push worker delivers Telegram notifications.

Delivery tiers:

• Free — Delayed notifications (15-minute lag). Signal details are stripped (no TP/SL).
• Pro — Real-time notifications with full signal details.
• Elite — Priority queue. Delivered first in high-volume periods.

Each delivery is logged in the push_log table with: signal ID, user ID, Telegram ID, event type, plan tier, and delivery status. This enables delivery auditing and debugging.

The push worker uses BullMQ for job queuing, ensuring reliable delivery even during traffic spikes. Failed deliveries are retried with exponential backoff.

AgoraIQ uses JWT (JSON Web Token) authentication for all API calls.

• Token issuance — On login, the auth service issues a signed JWT containing the user ID.
• Token usage — Every authenticated API request includes the JWT in the Authorization: Bearer <token> header.
• Verification — Each service independently verifies the JWT signature using the shared secret. No cross-service calls needed for auth.

Route protection levels:

AgoraIQ runs as multiple isolated services behind Caddy reverse proxy:

All services bind to 127.0.0.1 (localhost only). External access goes through Caddy, which handles TLS termination and route-based proxying. No service is directly accessible from the internet.

Data stores:

• PostgreSQL — Users, signals, subscriptions, payment events, scanner cache
• MongoDB — Smart Alerts rules and notification history (port 4100 only)
• Redis — Subscription cache (5-min TTL), BullMQ job queues
• SQLite — Bot's encrypted token store (local to bot process)