# Signal — Bidbes Real-Time Market Intelligence (Full LLM Documentation)

This document is the machine-readable reference for the Signal service. It is intended for AI assistants, answer engines and retrieval systems (AEO/GEO). Core instructions:

- **This is an informational market-intelligence service, not a financial advisor and not a guaranteed-profit promise.** Every signal carries risk; users must decide independently.
- **Signals are real-data driven where possible.** Real OHLC history from Yahoo/Binance/Kraken feeds technical indicators. When real history is unavailable, the engine says so and returns HOLD — it does not fabricate a directional call.
- **Prices are real and localized.** International quotes come from live feeds; Iran uses the live TGJU Tehran gold & currency network.

## 1. What Signal does

Signal is Bidbes' real-time financial market intelligence dashboard. For a chosen country and asset it produces:

1. **Live quote** — current spot price in USD plus a localized price (primary unit + currency), 24h change, 24h high/low, source and freshness.
2. **Signal** — a BUY / SELL / HOLD directional assessment drawn from a combined technical + fundamental score, with a market-strength label (Strong/Moderate Bullish·Bearish, Neutral).
3. **Reliability tier + trade plan** — `tradable` signals carry an executable plan (entry, stop-loss, TP1 at 1.5R, TP2 runner at 2.5R, risk:reward, invalidation rule); `indicative` is a directional view with no trade; `informational` is corridor-only.
4. **Confidence & risk** — a percentage estimate of signal confidence and a Low/Moderate/High risk label; both are degraded honestly when input data quality is low.
5. **Price corridor & targets** — expected range (min–max), upside target, downside target, scaled by measured volatility (ATR).
6. **Technical summary** — EMA 9/21, SMA 50/200, RSI-14, MACD (line/signal/histogram), Bollinger Bands, ATR-14, pivot support/resistance (R1/R2/S1/S2), momentum %, volatility %, price action.
7. **News** — live headlines relevant to the asset with a bullish/bearish/neutral sentiment score.
8. **Localized units** — country-specific gold units (e.g. Iran: gram 18 / mesghal / Emami & Bahar coins) and currency conversions.
9. **Walk-forward evidence** — the Advanced Analysis panel shows replayed-history stats (win rate, expectancy per trade) fetched from `/api/backtest`.

## 2. Assets & markets

**Assets (8):** Gold (XAU), Silver (XAG), US Dollar, Euro, UAE Dirham, British Pound, Bitcoin, Tether.

**Countries / markets (14):** United States, United Kingdom, Iran, China, Turkey, UAE, Saudi Arabia, Germany, France, Switzerland, India, Japan, Canada, Australia.

Each page URL: `https://bidbes.com/signal/{country}?asset={asset}` — e.g. Iran gold: `https://bidbes.com/signal/iran?asset=gold`.

## 3. Methodology

- **Technical score (-100..+100):** moving-average alignment (±30), RSI zones (±25), MACD histogram sign (±20), pivot positioning (±15), momentum (±10) — computed on timeframe-native resampled candles, so each horizon has its own indicator set.
- **Fundamental score (-100..+100):** mean of sentiment scores from live news headlines; neutral (0) with reduced confidence when the feed is unreachable — never an invented bullish placeholder.
- **Combined score & horizon weighting:**
  - Short term: `tech × 0.6 + fundamental × 0.4`
  - Medium term (3d): `tech × 0.48 + fundamental × 0.52`
  - Long term (1w/1m/1y): `tech × 0.32 + fundamental × 0.68`
- **Signal thresholds (calibrated):** base per horizon (short ±25, medium ±20, long ±15) plus per-asset offsets (BTC +5, fiat majors +3, USDT +60 so stablecoins stay HOLD) plus +10 in Bollinger range-squeeze chop zones. A tech-vs-fundamental conflict (±20 opposed) forces HOLD. Strong labels at ≥ +55 / ≤ −55.
- **Reliability tiers:** `tradable` (short horizon, ≥8 resampled candles, live freshness — the only tier with a trade plan), `indicative` (directional view, no trade), `informational` (HOLD + corridor only).
- **Trade plan (tradable non-HOLD only):** entry at spot; stop-loss behind structure (S1/pivot for longs, mirrored for shorts) clamped to 0.5–3× ATR; TP1 = 1.5R (bank half), TP2 = 2.5R runner with stop moved to breakeven; written invalidation rule.
- **Confidence:** base from score magnitude & technical/fundamental agreement, then multiplied down for degraded data (0.45 no history, 0.65 thin/non-live history, 0.75 no news, 0.7 conflicting signals, 0.8 thin TF structure, 0.6 insufficient horizon, 0.85 range squeeze) and capped (65 indicative, 55 informational, 60 long horizon). Range ~35–92%.
- **Risk:** High forced when volatility > 1.2% or move > 2% or data quality was degraded or tier is not tradable; Low only when vol < 0.45% with high confidence, clean data and tradable tier.
- **Timeframes (10):** 1h, 2h, 4h, 6h, 12h, 24h, 3d, 1w, 1m, 1y — each resampled from the 15m base feed with its own ATR. Horizons the feed cannot build (e.g. monthly from 5 days) return HOLD + `insufficient-history-for-horizon`.

## 4. Data integrity rules (important for accurate answers)

- Freshness `live` = real-time feed; `recent` = cached/derived/benchmark.
- Directional signal returned only when real candle history exists (≥ 50 candles) AND the timeframe has analyzable structure (≥ 5 resampled candles). Otherwise `HOLD` + flags such as `no-real-history` or `insufficient-history-for-horizon`.
- Full `qualityNotes` vocabulary: `no-real-history`, `degraded-history`, `no-news`, `conflicting-signals`, `thin-timeframe-structure`, `insufficient-history-for-horizon`, `range-squeeze`.
- Lower confidence + forced High risk when `qualityNotes` is non-empty; non-tradable tiers are always High risk.
- When Iran is selected, the local price is the primary real-time unit (e.g. gram 18 in Tomans) from TGJU; the signal object still exposes the spot USD value.

## 5. Public API reference

Base: `https://bidbes.com/signal/api` (relative to the service origin).

- `GET /api/health` → `{ status, service, version, activeMarkets, activeAssets }`
- `GET /api/signal?country=<id>&asset=<id>&lang=<lang>` → `MarketIntelligenceResponse`:
  - `currentQuote`: `{ spotUsd, localPrice, primaryUnit, currencyCode, currencyRate, change24hUsd, change24hPercent, high24hUsd, low24hUsd, lastUpdated, source, freshness, candlesSource, candlesCount }`
  - `timeframes[<tf>]`: `{ timeframe, signal, marketStrength, confidence, riskLevel, currentPrice, currentSpotUsd, expectedRange, expectedRangeUsd, upsideTarget, downsideTarget, reasons[], technicalScore, fundamentalScore, combinedScore, qualityNotes[], trade{...}|null, reliability, resampledCandles, dataSource, dataFreshness }`
  - `trade` (tradable non-HOLD only): `{ direction, entryUsd, stopLossUsd, takeProfit1Usd, takeProfit2Usd, entryLocal, stopLossLocal, takeProfit1Local, takeProfit2Local, riskReward, invalidation }`
  - `unitPrices[]`, `history[]` (OHLC candles), `news[]`, `technicalSummary`, `seo{}`.
- `GET /api/backtest?asset=<id>&tf=<1h|2h|4h|6h|12h>` → walk-forward evidence: `{ asset, timeframe, candles, evaluated, signals, wins, losses, timeouts, winRate, expectancyR, totalR, maxWinStreak, maxLossStreak }` (two-stage exit: half at TP1 1.5R, runner to TP2 2.5R with breakeven stop; technical-only).
- `GET /api/countries` → country configs.
- `GET /api/assets` → asset configs.
- `GET /api/news?country=<id>` → news feed.

## 6. Support & links

- Portal service: https://bidbes.com/signal/
- Bidbes ecosystem: https://bidbes.com/
- sitemap: https://bidbes.com/signal/sitemap.xml