Spaces:

Really-amin
/

SimpleChatbot

Sleeping

App Files Files Community

SimpleChatbot / DEVELOPER_DOCUMENTATION.md

Amin

Persist Hermes advisory provider config and stop boot-time overwrites.

255b13e 5 days ago

preview code

Raw

History Blame Contribute Delete

66.8 kB

Hermes Futures Desk — Complete Developer Documentation

Canonical combined developer reference for the UI v3 repository snapshot. The modular source documents live under asset-space/docs/.

Developer Guide
Architecture
API Reference
Datasource Pipeline and Contracts
Frontend Guide
Environment Configuration
Deployment Runbook
Security and Safety
Operations and Troubleshooting
Testing and Verification
Contributing
Project Status

Hermes Futures Desk — Complete Developer Guide

1. Purpose

Hermes Futures Desk is an authenticated Futures analysis and risk-management layer installed into the existing Hermes Agent runtime. It discovers markets, normalizes real market data, produces deterministic LONG, SHORT, or NO_TRADE outcomes, calculates a bounded trade plan, applies server-side risk controls, and optionally routes a fully revalidated plan to the existing Paper execution path.

The system is intentionally conservative:

Datasource 4 is authoritative for Futures verification and safety.
Binance public data may fill missing or unusable market fields but cannot override DS4 safety.
Datasource 2 provides complementary context only.
External AI provides advisory explanation only.
The browser is never trusted to authorize execution.
No new web server, FastAPI application, port, or trading engine is created.

2. Runtime summary

Hugging Face Space / Docker container
└── /opt/hermes                         Upstream Hermes Agent source/runtime
    ├── dashboard on 0.0.0.0:7860      Existing Hermes web application
    ├── tools/futures_dashboard_api.py  Installed repository overlay
    ├── tools/templates/...html         Installed Luxury dashboard template
    ├── trading/*                       Installed Futures modules
    └── .hermes_futures_overlay_manifest.json

/opt/data
├── scripts/                            Entrypoint, persistence, runtime audit
├── hermes_overlay/                     Restored/persisted copy; not preferred over image overlay
├── futures_symbols_cache.json          Optional symbol cache
├── telegram_state.json                 Telegram owner/watchlist/alert state
└── persistent Hermes data

/opt/hermesface_overlay                 Immutable overlay copied from the current image

The Docker image clones Hermes Agent into /opt/hermes, installs Python/Node dependencies, copies repository scripts into /opt/data/scripts, and copies the current overlay into both /opt/data/hermes_overlay and /opt/hermesface_overlay. At startup, scripts/sync_hf.py installs the overlay into /opt/hermes, writes a SHA-256 manifest, patches the existing Hermes dashboard to include the routers, and starts the dashboard on port 7860.

3. Main modules

Module	Responsibility
`scripts/entrypoint.sh`	Runtime directory creation, dashboard auth configuration, and handoff to `sync_hf.py`.
`scripts/sync_hf.py`	Persistence restore/sync, overlay installation, manifest generation, router mounting, Telegram polling isolation, and process startup.
`hermes_overlay/tools/futures_dashboard_api.py`	Authenticated Futures HTTP routes, runtime file diagnostics, symbol catalog, market endpoint, analysis route, and Paper revalidation route.
`hermes_overlay/tools/templates/hermes_futures_desk_luxury.html`	Luxury Obsidian & Gold single-page dashboard.
`hermes_overlay/trading/dual_datasource_client.py`	DS4 → Binance → DS2 acquisition, normalization, provenance, health metadata, and `noTradeGuard` aggregation.
`hermes_overlay/trading/binance_public_client.py`	Unauthenticated Binance Futures fallback and explicit regional-restriction reporting.
`hermes_overlay/trading/trade_cycle.py`	Deterministic signal scoring, SL/TP construction, risk sizing, plan creation, and optional Paper orchestration.
`hermes_overlay/trading/risk.py`	Risk profiles, leverage caps/haircut, quantity sizing, and hard risk gates.
`hermes_overlay/trading/futures_execution.py`	Existing Paper account/position book and execution validation.
`hermes_overlay/trading/state.py`	Bounded in-memory dashboard state; no decision authority.
`hermes_overlay/trading/symbols.py`	Symbol normalization for DS4 and CCXT formats.
`hermes_overlay/external_ai/advisory.py`	Optional OpenRouter → Google → Hugging Face advisory chain.
`hermes_overlay/tools/telegram_bot.py`	Webhook-only, analysis-only Telegram adapter and owner bootstrap.
`scripts/verify_futures_runtime.py`	Read-only deployed runtime audit; never calls Paper Execute.

4. End-to-end request flow

4.1 Market display

Browser requests GET /api/futures/market with symbol, interval, and limit.
Router normalizes the symbol and calls get_market_context().
Datasource client requests DS4 with bounded KuCoin-compatible millisecond from/to parameters.
Missing, unusable, or stale fields are requested from Binance public fallback.
Datasource 2 is queried for complementary context and may fill only still-missing legitimate fields.
Each normalized field receives source, timestamp, freshness, validity, and fallback metadata.
The endpoint returns only real normalized values or an explicit partial, stale, or unavailable state.
The browser renders charts and diagnostics without modifying server decisions.

4.2 Deterministic analysis

Browser sends POST /api/futures/analyze.
Server runs run_futures_cycle(..., execute=False).
DS4 safety state, Futures verification, required fields, and freshness gates are checked first.
A deterministic score is calculated only from normalized real inputs.
A directional plan is created only when score and confirmation thresholds pass.
SL/TP are derived from ATR and configured reward-to-risk rules.
Risk sizing calculates quantity from equity loss at Stop Loss.
Slippage is estimated from the real order book.
The result is stored as a bounded server-side plan and returned with a planId.

4.3 Paper execution

Paper execution is not a continuation of browser state. The server performs all checks again:

requested symbol is a verified Futures contract;
planId matches the latest server plan;
symbol and risk profile have not changed;
plan was not already executed;
plan has not expired;
decision is LONG or SHORT;
DS4 verification and trading readiness remain valid;
noTradeGuard is false;
plan is marked executable and risk-approved;
runtime trading mode is paper;
a fresh analysis-only cycle still authorizes the plan.

Only after these checks does the server invoke the existing Paper execution path.

5. Datasource authority

Datasource 4 → Binance public fallback → Datasource 2

Datasource 4 owns contract verification and all Futures safety semantics. The critical fields are:

contract
ticker
orderbook
funding
openInterest

OHLCV, indicators, sentiment, and ATR are also normalized and attributed. Missing or non-fresh critical fields activate noTradeGuard and set tradingReadiness=blocked.

Binance public data is unauthenticated and field-level only. HTTP 451 is represented as Regionally restricted; it is never reported as healthy. Datasource 2 cannot verify Futures, clear noTradeGuard, or override DS4 data that is present and usable.

6. Health model

The code deliberately separates:

transportStatus: whether the HTTP request succeeded;
dataUsability: whether parsed data is suitable for use;
freshness: whether provider timestamp or authoritative DS4 state proves freshness;
completeness: whether expected fields were supplied;
mergeStatus: whether the combined context is complete;
tradingReadiness: whether deterministic safety gates allow a plan.

A successful HTTP response does not make market data fresh. Fallback data without a provider timestamp remains unknown and cannot pass a Futures freshness gate.

7. Analysis and plan states

Analysis states

NOT_ANALYZED
ANALYZING
LONG
SHORT
NO_TRADE
ANALYSIS_FAILED
STALE
API_UNAVAILABLE

Plan types

directional_plan: a valid directional plan before final execution checks.
non_executable_plan: directional values exist but one or more safety/risk gates block execution.
rejected/no-direction analysis: NO_TRADE with no executable plan geometry.

Market endpoint states

available: real candles and required display fields are fresh and usable.
partial: values exist but freshness or completeness is not fully proven.
stale: required display data is stale or invalid.
unavailable: real candles or a current price could not be obtained.

8. Deterministic scoring and risk rules

Default analysis thresholds are environment-overridable:

Setting	Default
Minimum absolute signal score	`0.55`
Minimum signal components	`3`
Minimum direction confirmations	`2`
Stop ATR multiplier	`1.2`
Take Profit reward-to-risk	`1.8`
Minimum stop distance	`20` bps
Plan maximum age	`20` seconds
Requested leverage	`5x`

Risk profiles:

Profile	Equity risk	Maximum leverage
Conservative	1%	5x
Moderate	3%	10x
Aggressive	5%	15x

Sizing is based on loss at Stop Loss:

risk_amount   = account_equity × risk_percent
stop_distance = abs(entry_price - stop_loss)
quantity      = risk_amount / stop_distance

When ATR is at least 3% of price, effective leverage is reduced by 50% and never increased beyond the risk-profile cap.

9. Frontend behavior

The dashboard is a single packaged HTML template with inline CSS and JavaScript. It uses the existing authenticated FastAPI origin and fetch(..., credentials='same-origin', cache='no-store').

Major features:

symbol search and verified/market-only catalog counts;
local watchlist and recent markets;
real candle/line chart, four intervals, three candle limits, volume, crosshair, and tooltip;
market source, freshness, funding, Open Interest, best bid/ask/spread, and readiness;
display-only diagnostics from returned candles;
per-field provenance;
deterministic analysis and Paper Execute controls;
plan geometry and execution checklist;
datasource detail cards and sanitized technical diagnostics;
Paper account and positions;
local activity/history, JSON export, copy summary, density/theme preferences;
manual and automatic refresh controls.

Browser storage never grants server permission. Selecting a historical symbol or changing risk invalidates the current browser plan and requires a new server analysis.

10. Authentication

The upstream Hermes dashboard is protected by its existing authentication middleware. The Futures router also supports local HTTP Basic enforcement when HERMES_ADMIN_PASSWORD is set:

username: HERMES_DASHBOARD_BASIC_AUTH_USERNAME (default: admin)
password: HERMES_ADMIN_PASSWORD

entrypoint.sh writes a hashed credential into Hermes config.yaml before the server binds publicly. Secrets must be configured as Hugging Face Space secrets or injected environment variables, never committed.

11. Telegram model

Telegram is webhook-only and analysis-only:

POST /api/telegram/webhook validates X-Telegram-Bot-Api-Secret-Token.
Owner bootstrap uses a one-time private-chat /claim <secret> command.
Authorized users come from configured IDs or the persisted owner.
Commands call run_futures_cycle(..., execute=False) only.
Direct delivery may use a proxy; proactive delivery may use an HMAC relay.
Polling must remain disabled.

No Telegram command can execute a Futures position.

12. Runtime integrity

During overlay installation, sync_hf.py copies the current image overlay into /opt/hermes and writes .hermes_futures_overlay_manifest.json. The status endpoint compares repository/overlay/runtime/template/router hashes when those paths are available.

Runtime status semantics:

verified: evidence exists and all expected hashes match;
mismatch: evidence exists and one or more hashes differ;
unknown: required evidence is unavailable.

Missing files must never be reported as verified.

13. Development workflow

Start from the current repository files under asset-space/hermes_overlay.
Do not copy old loose reference files over the repository.
Keep changes focused and additive to the API contract.
Preserve the single server and port architecture.
Add tests for normalization, provenance, state transitions, and server-side execution checks.
Run static checks and focused Futures tests.
Review secrets and generated files before commit.
Deploy through the existing Space workflow.
Verify the installed hashes and authenticated routes.
Inspect browser Console and Network.
Never click Paper Execute during deployment verification.

14. Read-only runtime audit

export HERMES_ADMIN_PASSWORD='...'
export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
export HF_TOKEN='...' # required when the target Space is private
python scripts/verify_futures_runtime.py \
  --base-url https://really-amin-simplechatbot.hf.space \
  --symbol BTCUSDT \
  --analyze \
  --report .runtime_audit/futures_runtime_audit.json

The utility checks /futures, status, symbols, positions, all market intervals, and optionally one analysis-only request. It never calls /api/futures/paper/execute.

15. Known deployment limitations

Binance public Futures endpoints may return HTTP 451 in the current Hugging Face region.
Real DS4 payload names and provider timestamps must be verified against live deployed responses.
The current package has static validation results but not a completed authenticated production verification cycle.
The UI uses a single large HTML template; future refactoring must preserve runtime template installation and avoid introducing a second frontend server.

16. Definition of done

A change is complete only when:

the correct template and router are installed and hash-verified;
authenticated routes return expected structured responses;
real market data renders for 1m, 5m, 15m, and 1h or returns an explicit unavailable state;
Console has no critical error and Network requests are authenticated;
datasource health and attribution are truthful;
deterministic safety logic is unchanged;
Telegram remains webhook-only;
no secret is exposed;
no trade is executed during verification.

Architecture

System context

flowchart LR
    U[Authenticated browser] -->|same-origin HTTPS| H[Hermes dashboard / FastAPI :7860]
    T[Telegram webhook] --> H
    H --> R[Futures dashboard router]
    R --> C[Deterministic trade cycle]
    R --> S[Dashboard state]
    C --> D[Dual datasource client]
    D --> DS4[Datasource 4\nAuthoritative]
    D --> B[Binance public\nFallback]
    D --> DS2[Datasource 2\nComplementary]
    C --> K[Risk / sizing]
    C --> E[Paper execution]
    C -. advisory only .-> A[External AI]

Container and filesystem architecture

flowchart TD
    I[Docker image] --> O1[/opt/hermesface_overlay\nimmutable current-image overlay]
    I --> O2[/opt/data/hermes_overlay\npersisted/restored copy]
    I --> S[/opt/data/scripts]
    B[scripts/entrypoint.sh] --> Y[scripts/sync_hf.py]
    Y -->|prefer| O1
    Y -->|fallback only| O2
    Y -->|copy modules| H[/opt/hermes]
    Y --> M[overlay manifest]
    Y --> P[patch existing dashboard router]
    P --> W[Hermes dashboard :7860]

The immutable /opt/hermesface_overlay is preferred so a restored dataset containing an older overlay cannot downgrade the current image.

Layer responsibilities

HTTP and UI layer

futures_dashboard_api.py owns request validation, authentication dependency, response shaping, runtime diagnostics, and browser-facing error semantics. It does not implement signal scoring or sizing.

Datasource layer

dual_datasource_client.py owns:

HTTP acquisition;
KuCoin-compatible time range construction;
nested payload discovery;
field normalization;
source priority;
field provenance;
source health metadata;
noTradeGuard, missing-field, stale-field, merge, and readiness results.

Decision layer

trade_cycle.py owns deterministic score calculation, decision thresholds, SL/TP construction, risk module orchestration, plan expiry, and optional execution handoff.

Risk layer

risk.py owns risk profile lookup, leverage caps, volatility haircut, quantity calculation, margin/notional gates, daily-loss and position-count gates.

Execution layer

futures_execution.py owns Paper mode, account/position state, exchange adapter boundaries, slippage estimation, and protective order behavior. The dashboard route never directly constructs an exchange order.

State layer

state.py stores only a bounded view of the latest context/plan for the dashboard. It removes raw exchange payloads and does not authorize any decision.

Trust boundaries

Boundary	Trusted for decisions?	Notes
Browser controls and localStorage	No	Convenience only; server revalidates everything.
Datasource 4	Yes, for verification/safety	Still subject to parsing, freshness, and completeness checks.
Binance public	No, as authority	Field fallback only; cannot clear DS4 guard.
Datasource 2	No, as authority	Complementary context only.
External AI	No	Advisory explanation only.
Telegram input	No	Authorized, rate-limited, analysis-only commands.
Server-side latest plan	Partially	Must still pass freshness and execution revalidation.

Router installation

sync_hf.py modifies the existing Hermes dashboard code to include:

from tools.futures_dashboard_api import router as _futures_dashboard_router
app.include_router(_futures_dashboard_router)
from tools.telegram_bot import router as _telegram_router
app.include_router(_telegram_router)

The patch is idempotent and must not create a new FastAPI app.

Persistence

Hermes data under /opt/data may be synchronized to a private Hugging Face Dataset. The repository overlay is also copied into the image, but the immutable image overlay is the source used for installation. Runtime state such as Telegram owner data and symbol cache lives under /opt/data and must not be committed.

Failure behavior

DS4 unreachable: merge may use fallback data for display, but Futures verification/readiness remains blocked.
Binance HTTP 451: source status is restricted/unavailable; no bypass is attempted.
DS2 unavailable: complementary context is degraded; it does not independently block a plan unless it was the only attempted fill for a still-missing field.
Market endpoint exception: HTTP 503 with structured API_UNAVAILABLE payload.
Analysis exception: HTTP 503, state becomes ANALYSIS_FAILED, previous plan is cleared from current state.
Template read failure: minimal fallback page is served and trading remains blocked.

API Reference

Base and authentication

All Futures routes are mounted on the existing Hermes FastAPI application and port. In production, use the Space base URL and an authenticated browser/session or HTTP Basic credentials.

When HERMES_ADMIN_PASSWORD is set, Futures API routes require:

Authorization: Basic <base64(username:password)>

Default username: admin, configurable with HERMES_DASHBOARD_BASIC_AUTH_USERNAME.

All Futures responses set Cache-Control: no-store. /futures also sets no-cache headers and runtime SHA-256 headers.

`GET /futures`

Returns the packaged HTML dashboard.

Important response headers:

X-Hermes-Template-SHA256
X-Hermes-Router-SHA256
Cache-Control: no-store, no-cache, must-revalidate, max-age=0

`GET /api/futures/status`

Returns application status, runtime-file evidence, market health, latest bounded plan state, source metadata, account summary, and diagnostics.

Representative shape:

{
  "application": {
    "status": "online",
    "runtimeStatus": "verified | mismatch | unknown",
    "runtimeFiles": {}
  },
  "marketData": {"status": "healthy | degraded | unavailable"},
  "tradingReadiness": "ready | blocked",
  "mergeStatus": "complete | partial | unknown",
  "analysisState": "NOT_ANALYZED",
  "sourceMetadata": {
    "datasource4": {},
    "binance": {},
    "datasource2": {}
  },
  "fieldSources": {},
  "fieldMetadata": {},
  "verifiedFutures": false,
  "missingRequiredFields": [],
  "staleRequiredFields": [],
  "latestTradePlan": null,
  "latestPlanId": null,
  "latestSignalScore": null,
  "riskApproved": false,
  "tradingMode": "paper",
  "equity": 10000.0,
  "realizedPnlToday": 0.0,
  "openPositionCount": 0,
  "serverTime": 0
}

Consumers should treat additional fields as additive and avoid strict whole-object equality.

`GET /api/futures/symbols`

Returns the merged catalog.

{
  "symbols": [
    {
      "symbol": "BTCUSDT",
      "baseAsset": "BTC",
      "quoteAsset": "USDT",
      "futuresVerified": true,
      "marketOnly": false,
      "contractType": "PERPETUAL",
      "status": "TRADING",
      "source": "datasource4",
      "rank": 1,
      "updatedAt": "2026-07-21T00:00:00Z"
    }
  ],
  "source": "...",
  "updatedAt": "...",
  "counts": {
    "total": 0,
    "verifiedFutures": 0,
    "marketOnly": 0
  }
}

Catalog membership alone does not authorize execution. Only items with futuresVerified=true are eligible for Paper revalidation.

`GET /api/futures/positions`

Returns Paper mode and enriched open positions.

{
  "mode": "paper",
  "positions": [
    {
      "symbol": "BTC/USDT:USDT",
      "side": "long",
      "size": 0.01,
      "entryPrice": 60000.0,
      "markPrice": 60500.0,
      "unrealizedPnl": 5.0
    }
  ]
}

Mark price enrichment is best-effort. Missing mark data produces null, not zero.

`GET /api/futures/market`

Query parameters:

Parameter	Type	Default	Constraints
`symbol`	string	`BTCUSDT`	length 3–32; normalized server-side
`interval`	enum	`5m`	`1m`, `5m`, `15m`, `1h`
`limit`	integer	`120`	20–500

Example:

GET /api/futures/market?symbol=BTCUSDT&interval=5m&limit=120

Successful/partial shape:

{
  "state": "available | partial | stale | unavailable",
  "analysisState": "NOT_ANALYZED | STALE | API_UNAVAILABLE",
  "dataUsability": "usable | degraded | unavailable",
  "reason": null,
  "symbol": "BTCUSDT",
  "interval": "5m",
  "limit": 120,
  "candles": [
    {"timestamp": 0, "open": 0, "high": 0, "low": 0, "close": 0, "volume": 0}
  ],
  "currentPrice": null,
  "markPrice": null,
  "change24h": null,
  "volume24h": null,
  "fundingRate": null,
  "openInterest": null,
  "source": "datasource4 | binance_public | datasource2 | mixed | unavailable",
  "sourcesUsed": [],
  "fieldSources": {},
  "fieldMetadata": {},
  "freshness": "fresh | stale | invalid | unknown",
  "verifiedFutures": false,
  "futuresVerification": {},
  "warnings": [],
  "missingFields": [],
  "analysisRequiredFieldsMissing": [],
  "staleRequiredFields": [],
  "mergeStatus": "complete | partial | unavailable",
  "tradingReadiness": "ready | blocked",
  "rejectionReasons": [],
  "sourceMetadata": {},
  "technicalDiagnostics": {},
  "fetchedAt": 0
}

If acquisition raises, the route returns HTTP 503 with the same high-level keys, empty candles, null values, state=unavailable, analysisState=API_UNAVAILABLE, and blocked readiness.

No mock candles are permitted in production responses.

`POST /api/futures/analyze`

Request:

{
  "symbol": "BTCUSDT",
  "risk_profile": "moderate",
  "include_external_context": false
}

Allowed risk profiles:

conservative
moderate
aggressive

Unknown request fields are rejected.

Representative response:

{
  "planId": "server-generated-reference",
  "symbol": "BTCUSDT",
  "decision": "LONG | SHORT | NO_TRADE",
  "analysis_state": "LONG | SHORT | NO_TRADE",
  "score": null,
  "confidence": null,
  "components": {},
  "core_reasons": [],
  "warnings": [],
  "entry": null,
  "stop_loss": null,
  "take_profit": null,
  "reward_to_risk": null,
  "risk_profile": "moderate",
  "risk_percent": null,
  "requested_leverage": 5,
  "effective_leverage": null,
  "quantity": null,
  "estimated_slippage_percent": null,
  "risk_approved": false,
  "rejection_reasons": [],
  "noTradeGuard": true,
  "plan_type": "directional_plan | non_executable_plan",
  "executable": false,
  "futuresVerified": false,
  "trading_readiness": "blocked",
  "created_at": "...",
  "expires_at": "...",
  "external_advisory": null
}

A NO_TRADE response is a successful deterministic evaluation, not an HTTP failure. An internal analysis failure returns HTTP 503 with detail="Futures analysis failed" and clears the current plan state.

`POST /api/futures/paper/execute`

Request:

{
  "symbol": "BTCUSDT",
  "risk_profile": "moderate",
  "planId": "server-generated-reference"
}

The endpoint may return:

403 for unverified contract or non-Paper mode;
409 for superseded/unknown plan, symbol/risk change, expiry, prior execution, blocked readiness, failed fresh revalidation, or non-executable plan;
422 for invalid request shape/symbol;
200 for the final Paper result.

The endpoint is intentionally absent from the read-only audit tool.

Telegram routes

`POST /api/telegram/webhook`

Public webhook ingress protected by:

X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>

Limits request body to 256 KiB, applies per-user rate limiting, requires owner/allowed-user authorization, and invokes analysis-only commands.

`GET /api/telegram/status`

Returns enabled/mode/webhook/proxy/relay/authorized-user/alert-scheduler status. It does not expose tokens or user IDs.

`GET /api/telegram/bootstrap/status`

Requires the same Telegram secret header and returns only:

{"ok": true, "ownerClaimed": true, "bootstrapConsumed": true}

Datasource Pipeline and Contracts

Priority and authority

Datasource 4 → Binance public fallback → Datasource 2

Priority describes fill order, not equal trust.

Datasource 4

Authoritative for:

Futures contract verification;
dataState;
noTradeGuard;
safety status and rejection reasons;
primary Futures market fields.

Binance public

unauthenticated;
called only for missing, unusable, or stale fields;
cannot verify a contract or clear DS4 safety;
HTTP 451 is restricted / Regionally restricted;
provider timestamps are required to claim freshness.

Datasource 2

complementary news, sentiment, indicator, order-book, volume, trending, gainers, and correlation context;
may fill a still-missing legitimate field only after Binance;
cannot become Futures verification or safety authority.

Datasource 4 request

The DS4 snapshot endpoint is called with:

/api/short-hunter/snapshot/{SYMBOL}

Parameters:

interval: 1m | 5m | 15m | 1h
limit: 1..500 internally; market API exposes 20..500
from: epoch milliseconds
to: epoch milliseconds

normalize_epoch_milliseconds() accepts contemporary epoch seconds or milliseconds and prevents double conversion. build_kucoin_time_range() enforces supported interval, bounded limit, positive ordered timestamps, and millisecond units.

Normalized fields

The merged envelope may contain:

contract
ticker
ohlcv
orderbook
funding
openInterest
indicators
sentiment
atr
market_context

Contract

Normalized contract data should expose symbol, status, type/instrument, and explicit verification evidence when present. The presence of a generic contract object alone does not prove Futures status. Verification requires an explicit DS4 flag or a recognized Futures/perpetual/swap contract type.

Ticker

Accepted aliases are normalized to a bounded ticker object. Consumers should prefer normalized canonical keys where available and tolerate provider-specific supplemental keys.

Common price candidates:

markPrice
lastPrice
last
price
close
indexPrice

OHLCV

Canonical candle shape:

{
  "timestamp": 0,
  "open": 0.0,
  "high": 0.0,
  "low": 0.0,
  "close": 0.0,
  "volume": 0.0
}

A usable OHLCV series requires at least four valid positive close values. The market endpoint never invents missing candles.

Order book

Canonical shape:

{
  "bids": [[60000.0, 0.5]],
  "asks": [[60001.0, 0.4]],
  "timestamp": 0
}

Both sides must have at least one valid level. Prices must be positive; quantities must be non-negative.

Funding

Canonical values may include:

currentFundingRate
fundingRate
lastFundingRate
rate
nextFundingTime

Open Interest

Canonical values may include:

openInterest
sumOpenInterest
oi
changeFraction
change24h
changePercent

Field usability

_is_usable(field, value) performs field-specific validation. Empty values, non-finite values, invalid OHLCV, incomplete order books, and invalid contract/funding/OI shapes are rejected.

Per-field provenance

Every owned field receives metadata:

{
  "value": "bounded or summarized value",
  "source": "datasource4 | binance_public | datasource2 | unavailable",
  "timestamp": "provider timestamp or null",
  "freshness": "fresh | stale | invalid | unknown",
  "validity": "valid | unavailable",
  "observedAt": "server observation time",
  "freshnessBasis": "field_timestamp | datasource4_dataState | missing_provider_timestamp | unavailable",
  "fallbackStatus": "primary | fallback | not_filled"
}

The public API bounds large values:

OHLCV becomes count plus latest candle summary where appropriate;
order book becomes level counts and best bid/ask summary;
diagnostics are sanitized and size-limited.

Freshness

Freshness is based on provider timestamp relative to interval, or on an explicit authoritative DS4 fresh state. Transport success alone is not freshness evidence.

Required fields with stale, invalid, or unknown freshness block readiness.

Critical fields and readiness

Critical fields:

contract
ticker
orderbook
funding
openInterest

The combined context sets:

missingRequiredFields
staleRequiredFields
noTradeGuard
noTradeReasons
mergeStatus
tradingReadiness

Readiness is ready only when no guard remains. DS4 verification failure, DS4 noTradeGuard, missing critical fields, or non-fresh critical fields results in blocked.

Source metadata

Each source returns structured fields:

{
  "name": "Datasource 4",
  "url": "...",
  "status": "ok | degraded | unreachable | unavailable | standby",
  "transportStatus": "healthy | degraded | unavailable | restricted | standby",
  "dataUsability": "usable | degraded | unavailable | not_used",
  "endpoint": "...",
  "httpStatus": 200,
  "latencyMs": 120.4,
  "lastSuccess": "...",
  "freshness": "fresh | stale | unknown",
  "completeness": "complete | partial | unknown",
  "suppliedFields": [],
  "missingFields": [],
  "reason": "concise operator-facing summary"
}

Detailed endpoint/provider errors belong only under technicalDiagnostics, separated by source and sanitized before exposure.

Merge diagnostics

Cross-source problems are not assigned to a datasource card. They appear under:

technicalDiagnostics.merge.status
technicalDiagnostics.merge.missingCriticalFields
technicalDiagnostics.merge.tradingReadiness
technicalDiagnostics.merge.rejectionReasons

Adding a new provider mapping

Capture a real redacted payload.
Add the narrowest legitimate alias to the relevant normalizer.
Preserve provider timestamp and source name.
Add field-specific validity checks.
Do not infer Futures verification from generic market data.
Do not let the provider clear DS4 guard state.
Add focused tests for positive, missing, malformed, stale, and ambiguous cases.
Verify source-specific diagnostics remain correctly attributed.

Frontend Guide

File and runtime

The entire Futures dashboard UI is packaged in:

hermes_overlay/tools/templates/hermes_futures_desk_luxury.html

The router reads this file at request time from its installed tools/templates directory and serves it at /futures. Do not add a second frontend server, bundler process, or port.

Design system

The UI uses an Obsidian & Gold workstation theme with a light-theme option. Operational values use readable sans-serif/monospace styling. Decorative serif/italic styling is limited to headings and visual accents.

Responsive modes cover desktop, tablet, and mobile. prefers-reduced-motion is respected.

Main UI regions

fixed/collapsible navigation and local market lists;
command deck with symbol, risk, advisory, Analyze, and Paper Execute controls;
selected-market header and chart;
market diagnostics and field provenance;
decision, score, risk approval, and execution mode;
trade-plan geometry and execution checklist;
signal reasons and components;
Paper account and positions;
datasource health and technical diagnostics;
Telegram operational status;
local activity/history and export actions.

API usage

The helper uses:

fetch(url, {
  credentials: 'same-origin',
  cache: 'no-store'
})

Primary calls:

GET  /api/futures/status
GET  /api/futures/symbols
GET  /api/futures/positions
GET  /api/futures/market
POST /api/futures/analyze
POST /api/futures/paper/execute
GET  /api/telegram/status

No backend route is declared in the template.

Refresh behavior

Default intervals:

clock and age labels: 1 second;
status and positions: 5 seconds while auto-refresh is enabled and page is visible;
market data: 15 seconds;
Telegram status: 60 seconds.

When the page becomes visible again, status and market data refresh if automatic refresh is enabled.

Chart behavior

Supported intervals:

1m 5m 15m 1h

Supported candle limits:

60 120 240

Modes:

Candles;
Line;
optional volume bars.

The chart is an inline SVG and uses only candles returned by the market endpoint. Crosshair, OHLCV legend, tooltip, current-price reference, price labels, visible high/low, range position, and last-candle age are derived from the returned series.

No visual interpolation or fallback is permitted to create production candles.

Display-only diagnostics

The UI calculates visible trend, average candle range, relative last-candle volume, realized variation, last-candle direction, and range position from the real returned candles. These values are explicitly informational and must never change:

LONG / SHORT / NO_TRADE
risk approval
noTradeGuard
Entry / SL / TP
leverage
quantity
execution eligibility

Local browser state

The UI stores only convenience preferences/history in localStorage.

Known keys:

hermes_theme
hermes_auto_refresh
hermes_compact

Watchlist, recent markets, local analysis history, and workspace activity use Hermes-prefixed local keys defined in the template. They are not synchronized to the server and are not trusted for execution.

Keyboard shortcuts

Key	Action
`/`	Focus and select symbol search.
`A`	Run analysis when not already analyzing.
`R`	Manual refresh.
`D`	Toggle display density.
`T`	Toggle theme.
`?`	Open shortcut help.
`Escape`	Close overlays/help.

There is deliberately no keyboard shortcut for Paper Execute.

Analysis state rendering

Use the server result to set one of:

NOT_ANALYZED
ANALYZING
LONG
SHORT
NO_TRADE
ANALYSIS_FAILED
STALE
API_UNAVAILABLE

Important rules:

initial state is “Waiting for analysis,” not NO_TRADE;
HTTP/network failure is ANALYSIS_FAILED or API_UNAVAILABLE;
score is “Unavailable” when components do not exist, not numeric zero;
expiry is prominent only for a valid directional plan;
rejected/incomplete analysis is not presented as executable;
changing symbol or risk invalidates the current browser plan;
server state remains authoritative.

Execute availability

The button is disabled unless the latest browser plan mirrors all required server fields. The UI displays a concrete disabled reason such as:

Run analysis first
No directional plan
Risk approval failed
noTradeGuard active
Market-only symbol
Plan expired
Symbol changed
Risk profile changed
Plan already executed
Required Futures fields unavailable

These checks improve UX but do not replace backend revalidation.

Adding a UI feature safely

Reuse existing API fields or add an additive backend field.
Render missing values as Unavailable, never zero or fabricated content.
Keep browser calculations labeled display-only.
Do not add another Execute path or shortcut.
Invalidate plan display when relevant controls change.
Keep DOM IDs unique and update static ID checks.
Preserve responsive and reduced-motion behavior.
Do not display raw provider errors or secrets.
Verify Console and Network in an authenticated deployed session.

Environment Configuration

Configure secrets in Hugging Face Space Settings or inject them at container runtime. Never commit a populated .env file.

Core persistence

Variable	Default	Purpose
`HF_TOKEN`	none	Hugging Face token with required repository access.
`HERMES_DATASET_REPO`	derived/none	Private Dataset used to persist `/opt/data`.
`AUTO_CREATE_DATASET`	`true`	Create the private Dataset when missing.
`SYNC_INTERVAL`	`60`	Persistence sync interval in seconds.
`HF_HUB_DOWNLOAD_TIMEOUT`	implementation default	Hub download timeout.
`HF_HUB_UPLOAD_TIMEOUT`	implementation default	Hub upload timeout.
`HERMES_HOME`	`/opt/data`	Persistent Hermes data root.
`MAX_BACKUPS`	script default	Backup retention used by persistence helper.

Dashboard authentication

Variable	Default	Purpose
`HERMES_ADMIN_PASSWORD`	none	Required production dashboard password.
`HERMES_ADMIN_USERNAME`	`admin`	Username written to Hermes dashboard config by entrypoint.
`HERMES_DASHBOARD_BASIC_AUTH_USERNAME`	`admin`	Username checked by Futures router and runtime audit.

For the audit tool only:

Variable	Purpose
`HERMES_DASHBOARD_COOKIE`	Existing authenticated session cookie when Basic auth is not used.
`HERMES_FUTURES_BASE_URL`	Default audit target base URL.

For a private Hugging Face Space, also provide HF_TOKEN to the audit process. The utility uses that bearer token only at the Hugging Face proxy, then uses HERMES_ADMIN_PASSWORD to establish the separate dashboard session cookie. Neither credential is written to the audit report.

Datasources

Variable	Default	Purpose
`DS4_BASE_URL`	DS4 Hugging Face Space URL	Authoritative Datasource 4 base.
`DS4_TIMEOUT_S`	`6`	DS4 request timeout.
`DS2_BASE_URL`	DS2 Hugging Face Space URL	Complementary Datasource 2 base.
`DS2_TIMEOUT_S`	`6`	DS2 request timeout.
`HERMES_SYMBOL_CACHE_PATH`	`/opt/data/futures_symbols_cache.json`	Symbol catalog cache.

Binance fallback

Variable	Default	Purpose
`BINANCE_PUBLIC_FALLBACK_ENABLED`	`true`	Enable unauthenticated field fallback.
`BINANCE_FUTURES_PUBLIC_BASE_URL`	`https://fapi.binance.com`	Binance Futures public base.
`BINANCE_FUTURES_TIMEOUT_S`	`5`	Request timeout.
`BINANCE_FUTURES_MAX_RETRIES`	`2`	Retry bound.
`BINANCE_KLINE_INTERVAL`	`5m`	Default fallback interval.
`BINANCE_KLINE_LIMIT`	`100`	Default kline count.
`BINANCE_ATR_PERIOD`	`14`	ATR lookback in fallback client.
`BINANCE_ORDERBOOK_LIMIT`	`20`	Depth level limit.
`BINANCE_OI_PERIOD`	`5m`	Open Interest history period.

A regional HTTP 451 must be surfaced honestly. Do not use raw IP, DNS bypass, or TLS bypass.

Deterministic analysis

Variable	Default	Purpose
`FUTURES_MIN_SIGNAL_SCORE`	`0.55`	Minimum absolute deterministic score.
`FUTURES_MIN_SIGNAL_COMPONENTS`	`3`	Minimum present scoring components.
`FUTURES_MIN_DIRECTION_CONFIRMATIONS`	`2`	Minimum components confirming direction.
`FUTURES_STOP_ATR_MULTIPLIER`	`1.2`	ATR stop-distance multiplier.
`FUTURES_TAKE_PROFIT_RR`	`1.8`	Target reward-to-risk.
`FUTURES_MIN_STOP_BPS`	`20`	Minimum stop distance in basis points.
`FUTURES_PLAN_MAX_AGE_SECONDS`	`20`	Plan expiry window.
`FUTURES_DEFAULT_LEVERAGE`	`5`	Requested leverage before caps/haircut.

Changing these variables changes deterministic behavior and requires explicit review, tests, and deployment evidence.

Execution and Paper account

Variable	Default	Purpose
`PAPER_EQUITY_USDT`	implementation default	Initial Paper account equity.
`FUTURES_EXCHANGE_ID`	implementation default	Exchange adapter ID.
`FUTURES_API_KEY`	none	Exchange credential boundary. Do not set for routine Paper-only development.
`FUTURES_API_SECRET`	none	Exchange secret.
`FUTURES_API_PASSPHRASE`	none	Optional exchange passphrase.

Do not introduce credentials into source, logs, diagnostics, screenshots, patches, or generated reports.

External advisory

Variable	Default	Purpose
`EXTERNAL_AI_ENABLED`	`true`	Allow advisory when explicitly requested.
`EXTERNAL_AI_TIMEOUT_SECONDS`	`8`	Legacy/advisory timeout.
`EXTERNAL_AI_TOTAL_TIMEOUT_SECONDS`	`15`	Outer advisory safety cap (`advisory.py`); Hermes per-task timeout is in `config.yaml`.
`OPENROUTER_ANALYSIS_MODEL`	configured model	OpenRouter model (initial persist only when preserve is off or chain obsolete).
`GOOGLE_ANALYSIS_MODEL`	configured model	Google model (initial persist only when preserve is off or chain obsolete).
`HF_ANALYSIS_MODEL`	configured model	Hugging Face model (initial persist only when preserve is off or chain obsolete).
`OPENROUTER_API_KEY`	none	OpenRouter credential.
`GOOGLE_API_KEY`	none	Google credential.

Provider routing is Hermes-native: fallback_providers + auxiliary.futures_advisory.fallback_chain in config.yaml. Advisory output cannot change the deterministic plan.

Telegram webhook

Variable	Default	Purpose
`TELEGRAM_ENABLED`	`false`	Enable webhook adapter.
`TELEGRAM_MODE`	`webhook`	Must remain webhook mode.
`TELEGRAM_PUBLIC_BASE_URL`	Space URL	Webhook target base.
`TELEGRAM_WEBHOOK_PATH`	`/api/telegram/webhook`	Webhook path.
`TELEGRAM_WEBHOOK_SECRET`	none	Telegram secret-token header value.
`TELEGRAM_BOOTSTRAP_SECRET`	none	One-time owner claim secret.
`TELEGRAM_ALLOWED_USER_IDS`	empty	Comma-separated authorized IDs.
`TELEGRAM_BOT_TOKEN`	none	Telegram bot token.
`TELEGRAM_PROXY_URL`	empty	Optional direct Bot API proxy.
`TELEGRAM_RELAY_URL`	empty	Optional proactive relay.
`TELEGRAM_RELAY_SECRET`	empty	HMAC relay secret.
`TELEGRAM_STATE_PATH`	`/opt/data/telegram_state.json`	Persisted owner/watchlist state.
`TELEGRAM_ALERTS_ENABLED`	`false`	External-scheduler alert evaluation status.
`TELEGRAM_COMMAND_RATE_LIMIT`	`10`	Commands per user per minute.
`TELEGRAM_SCAN_MAX_SYMBOLS`	`300`	Maximum verified catalog candidates.
`TELEGRAM_SCAN_SHORTLIST_SIZE`	`20`	Deterministic shortlist size.
`TELEGRAM_SCAN_RESULT_COUNT`	`10`	Displayed result count.
`TELEGRAM_SCAN_MAX_CONCURRENCY`	`4`	Analysis concurrency.

MCP isolation

Variable	Default	Requirement
`LINEAR_MCP_ENABLED`	`false`	Keep unchanged unless separately approved.
`UNREAL_ENGINE_MCP_ENABLED`	`false`	Keep disabled unless separately approved.

Runtime integrity paths

Advanced overrides used by diagnostics:

HERMES_FUTURES_OVERLAY_MANIFEST
HERMES_OVERLAY_SOURCE
HERMES_SYNC_SCRIPT

These should normally use their runtime defaults.

Deployment Runbook

Preconditions

Work from the current repository under asset-space.
Review all diffs.
Ensure no real .env, tokens, cookies, screenshots, cache, ZIP archives, runtime reports, or temporary probes are staged.
Confirm no architecture change introduces a second app, frontend server, or port.
Do not execute a trade during deployment verification.

Build behavior

The Dockerfile:

clones upstream Hermes Agent into /opt/hermes;
installs Node, web dashboard, Playwright, Python, CCXT, and HTTPX dependencies;
creates non-root user hermes and /opt/data directories;
copies scripts into /opt/data/scripts;
copies overlay into /opt/data/hermes_overlay and immutable /opt/hermesface_overlay;
starts /opt/data/scripts/entrypoint.sh.

Startup behavior

entrypoint.sh:

starts DNS pre-resolution in the background;
activates /opt/hermes/.venv;
creates persistent directories and baseline config files;
writes hashed dashboard Basic auth when HERMES_ADMIN_PASSWORD is configured;
calls scripts/sync_hf.py.

sync_hf.py:

restores persistent data when configured;
disables legacy Telegram gateway polling in webhook mode;
installs the current image overlay into /opt/hermes;
writes and verifies the overlay hash manifest;
mounts Futures and Telegram routers into the existing dashboard app;
starts Hermes dashboard on port 7860;
manages persistence/sync helpers.

Hugging Face deployment procedure

Review the final diff.
Commit the smallest coherent change.
Push to main of the repository backing Really-amin/SimpleChatbot.
Monitor Space build logs.
Wait until Space is fully RUNNING.
Record the serving repository revision.
Run the read-only runtime audit.
Open an authenticated browser session.
Inspect Console and Network.
Verify Telegram status and MCP isolation.

Read-only runtime audit

export HERMES_ADMIN_PASSWORD='...'
export HERMES_DASHBOARD_BASIC_AUTH_USERNAME='admin'
export HF_TOKEN='...' # required when the target Space is private
python scripts/verify_futures_runtime.py \
  --base-url https://really-amin-simplechatbot.hf.space \
  --symbol BTCUSDT \
  --analyze \
  --report .runtime_audit/futures_runtime_audit.json

Expected properties:

/futures returns 200;
body SHA-256 equals X-Hermes-Template-SHA256;
status, symbols, and positions return authenticated 200 responses;
each market interval returns 200 or structured 503;
market payload shape includes real canonical candle objects;
optional analysis returns 200;
paperExecuteCalled remains false.

Browser verification

Check:

no critical JavaScript error;
authenticated API requests are not redirected to login HTML;
/api/futures/market is requested for each selected interval;
chart code executes and state messages match payload;
no stale cached template is served;
selected-market header, provenance, diagnostics, plan, account, and datasource sections render;
Execute remains disabled unless a valid server plan exists;
do not click Execute.

Runtime file verification

Use /api/futures/status and /futures response headers to compare:

repository/image overlay template
repository/image overlay router
installed /opt/hermes template
installed /opt/hermes router
served HTML body
installation manifest

Interpretation:

verified: all available expected files match;
mismatch: at least one available expected hash differs;
unknown: evidence is missing; investigate filesystem/install path.

Rollback

Identify the last known healthy commit.
Revert only the faulty change; do not copy old reference directories over the current backend.
Push the revert.
Wait for Space rebuild and RUNNING state.
Repeat runtime audit and browser verification.
Confirm deterministic thresholds, Telegram webhook-only mode, and port 7860 remain unchanged.

Release evidence to retain

commit hash;
serving Space revision;
sanitized audit JSON;
static/focused/regression test summary;
runtime hash result;
Console/Network findings;
provider limitations such as Binance 451;
explicit statement that no secret was exposed and no trade was executed.

Security and Safety

Non-negotiable invariants

Do not change or weaken:

deterministic LONG, SHORT, and NO_TRADE decisions;
Datasource 4 authority;
noTradeGuard;
Futures verification;
provider timestamp and freshness checks;
risk approval;
Stop Loss and Take Profit rules;
leverage caps and volatility haircut;
quantity/sizing logic;
Paper execution validation;
Telegram webhook-only isolation;
single FastAPI application and port 7860 architecture.

Browser trust model

The browser is untrusted for execution. It may display and calculate convenience diagnostics, but the server ignores browser-derived authorization.

Server-side Paper checks include plan reference, symbol/risk identity, expiry, executed flag, direction, DS4 verification, readiness, guard state, risk approval, executable flag, Paper mode, and fresh re-analysis.

Secret handling

Never expose or commit:

HF_TOKEN
HERMES_ADMIN_PASSWORD
FUTURES_API_KEY
FUTURES_API_SECRET
FUTURES_API_PASSPHRASE
OPENROUTER_API_KEY
GOOGLE_API_KEY
TELEGRAM_BOT_TOKEN
TELEGRAM_WEBHOOK_SECRET
TELEGRAM_BOOTSTRAP_SECRET
TELEGRAM_RELAY_SECRET
cookies or Authorization headers

Diagnostics redact keys and text matching authorization, cookie, token, secret, password, or API key patterns. Continue to sanitize new error fields before they reach API responses or UI.

Market-data integrity

No fabricated production candles, prices, funding, Open Interest, or order-book levels.
Missing values are null/Unavailable, not zero.
HTTP success is not data freshness.
Provider errors in main UI are concise; detailed errors remain sanitized under Technical Diagnostics.
Binance regional restriction must not be bypassed with raw IP, DNS override, or disabled TLS.

External AI boundary

External AI may return market bias, confidence, summary, and warnings. It must never modify:

decision
risk approval
noTradeGuard
Entry
Stop Loss
Take Profit
leverage
quantity
execution availability

Bulk scans must not use advisory AI.

Telegram boundary

Webhook secret-token validation is mandatory.
Request size is bounded.
Owner bootstrap is one-time, secret-checked, and private-chat only.
Users are authorized by configured IDs or persisted owner.
Commands are rate-limited.
Callback nonces expire and are user-bound.
Telegram performs analysis only and contains no order path.
Polling remains disabled.

Development safety

During ordinary development and deployment verification:

do not call Paper Execute;
do not run Testnet or Live execution;
use the read-only audit script;
use Paper account endpoints only for display verification;
do not add an execution keyboard shortcut;
do not allow a UI feature to write plan or risk state directly.

Review checklist for security-sensitive changes

Does the change alter a deterministic threshold or formula?
Can fallback data override DS4 safety?
Can a missing timestamp be treated as fresh?
Can the browser enable execution without server state?
Can a raw error include a secret?
Can a Telegram request bypass authorization or webhook validation?
Does the change introduce a second network service or port?
Does it add an exchange credential requirement?
Are failure states blocked by default?

Operations and Troubleshooting

Diagnostic order

Confirm Space is RUNNING.
Fetch /futures and inspect response/hash headers.
Check /api/futures/status with authentication.
Inspect runtime file status and datasource metadata.
Check Browser Console and Network.
Inspect market endpoint for one symbol/interval.
Compare DS4 raw/normalized fields and timestamps.
Check provider-specific diagnostics.
Run one analysis-only request.
Do not test Paper Execute during diagnosis.

Common issues

Dashboard returns 401

Likely causes:

missing/incorrect HERMES_ADMIN_PASSWORD;
wrong Basic username;
browser session expired;
reverse proxy did not preserve auth.

Actions:

confirm HERMES_ADMIN_USERNAME and HERMES_DASHBOARD_BASIC_AUTH_USERNAME alignment;
re-authenticate;
verify entrypoint.sh logged successful auth configuration;
never print the password in logs or reports.

`/futures` returns 200 but old UI appears

Possible causes:

stale installed overlay;
wrong template path;
restored old overlay taking precedence;
CDN/browser cache;
duplicate old page implementation.

Actions:

compare X-Hermes-Template-SHA256 with body hash;
inspect application.runtimeFiles in status;
confirm /opt/hermesface_overlay is preferred;
confirm installed /opt/hermes/tools/templates/... matches manifest;
hard reload only after server-side evidence is checked.

Runtime status is `unknown`

unknown means evidence is absent, not that files match.

Actions:

verify manifest path and permissions;
verify overlay and runtime paths exist;
check HERMES_FUTURES_OVERLAY_MANIFEST, HERMES_OVERLAY_SOURCE, and HERMES_SYNC_SCRIPT overrides;
inspect overlay installation logs.

Runtime status is `mismatch`

Actions:

identify exact mismatched file in status payload;
compare repository/image overlay and /opt/hermes file;
verify sync_hf.py installed after persistence restore;
rebuild/redeploy from a clean commit.

Chart says market data unavailable

Check market endpoint payload:

HTTP 503 and API_UNAVAILABLE: acquisition exception;
state=unavailable: no real candles/current price;
state=stale: provider timestamp invalid or stale;
state=partial: freshness unknown or display fields incomplete.

Inspect:

warnings
missingFields
analysisRequiredFieldsMissing
staleRequiredFields
sourceMetadata
technicalDiagnostics

Do not replace missing candles with mock data.

Binance shows HTTP 451

This is an expected regional limitation in some Hugging Face regions.

Correct behavior:

transportStatus=restricted
httpStatus=451
dataUsability=unavailable
reason=Regionally restricted

Do not use raw-IP or TLS-bypass workarounds. DS4 safety remains authoritative.

KuCoin reports “Parameter 'from' must be milliseconds”

Verify DS4 request builder uses build_kucoin_time_range() and sends integer millisecond from and to. Check for upstream code that converts an already-millisecond value a second time.

Market data is HTTP 200 but readiness is blocked

Transport and readiness are separate. Inspect:

DS4 Futures verification;
DS4 noTradeGuard;
missing critical fields;
non-fresh critical fields;
merge rejection reasons.

A provider may be reachable while its data is unusable.

`NO_TRADE` displayed before analysis

The initial state must be NOT_ANALYZED. Check frontend initialization and /api/futures/status.analysisState. A network error must be ANALYSIS_FAILED or API_UNAVAILABLE, not NO_TRADE.

Signal score shows zero with no components

The UI must show Unavailable. Check whether latestSignalScore is null and whether signal components are empty. Do not coerce null to zero.

Execute button is disabled

This is normally correct. Read the visible reason and inspect:

latest plan exists
planId matches
symbol and risk match
plan not expired
LONG/SHORT decision
verified Futures
risk approved
noTradeGuard false
tradingReadiness ready
executable true
not already executed

Telegram says Owner setup required

No configured/persisted owner exists. Use the one-time private /claim <TELEGRAM_BOOTSTRAP_SECRET> flow. Remove/rotate the bootstrap secret after claim. Do not expose owner ID in dashboard status.

Telegram proactive alerts unavailable

Webhook responses can work without outbound connectivity, but proactive alerts need either:

direct Telegram access with optional proxy; or
configured relay URL and HMAC secret.

Keep polling disabled.

Logs and artifacts

Useful logs:

Space build log
entrypoint startup log
sync_hf overlay install/hash log
Hermes dashboard log under /opt/data/logs
sanitized runtime audit JSON
browser Console and Network export without credentials

Never attach raw cookies, Authorization headers, tokens, or unredacted provider payloads.

Testing and Verification

Test locations

hermes_overlay/tests/

Existing focused areas include:

Binance public fallback;
nested DS4 merge behavior;
external advisory boundary;
Futures dashboard/state;
Futures integration;
Luxury template markers;
optional MCP runtime isolation;
Telegram webhook;
trade-cycle field paths.

Recommended validation layers

1. Static validation

python -m compileall hermes_overlay scripts
node --check /tmp/hermes_dashboard_script.js
ruff check hermes_overlay scripts

Also check:

duplicate DOM IDs;
missing JavaScript DOM references;
undefined CSS custom properties;
git diff --check;
absence of secrets/generated files.

2. Focused unit tests

Required focus:

seconds-to-milliseconds conversion;
already-millisecond timestamps;
ordered bounded KuCoin ranges;
ticker/funding/Open Interest aliases;
malformed and ambiguous provider shapes;
per-field source/timestamp/freshness attribution;
transport health versus usability/readiness;
datasource-specific error attribution;
market endpoint canonical shape;
no fabricated values;
safe rejection when required fields are missing or non-fresh;
initial/failure UI states;
Execute-disabled reasons and server safety gates.

3. Futures regression suite

Run the existing Futures tests once after focused tests pass. Avoid repeatedly running unrelated broad suites while iterating on a narrow failure.

4. Read-only deployed audit

export HERMES_ADMIN_PASSWORD='...'
export HF_TOKEN='...' # required when the target Space is private
python scripts/verify_futures_runtime.py \
  --base-url https://really-amin-simplechatbot.hf.space \
  --symbol BTCUSDT \
  --analyze \
  --report .runtime_audit/futures_runtime_audit.json

The audit never calls Paper Execute.

5. Browser verification

Authenticated desktop and mobile verification must cover:

Console free of critical errors;
valid Network status and JSON payloads;
chart rendering for all intervals;
Candles/Line, volume, tooltip, crosshair;
watchlist/recent/history/export/density/theme/auto-refresh controls;
field provenance and datasource cards;
state machine and score semantics;
visible Execute-disabled reason;
no Paper Execute click.

Acceptance matrix

Area	Required result
Runtime files	`verified`, or documented investigation for `unknown`; never unexplained mismatch.
Status API	200 authenticated, structured source/runtime fields.
Symbols API	Accurate total/verified/market-only counts.
Positions API	Deliberate empty state or formatted real Paper positions.
Market API	Real canonical candles or explicit structured unavailable state.
Analysis API	Deterministic result; `NO_TRADE` is allowed and expected when unsafe.
Paper Execute	Not called during verification.
Binance 451	Clearly reported as regional restriction.
Telegram	Webhook-only; no polling adapter.
Secrets	None in source, logs, reports, screenshots, or package.

Testing safety

Tests must not:

place Paper/Testnet/Live orders;
require real exchange credentials;
fabricate production responses in deployed paths;
weaken guards to make assertions pass;
treat an unavailable score as zero;
report missing runtime evidence as verified.

Contributing

Change policy

Work from the current repository implementation, not old loose reference files.
Keep API changes additive and backward-compatible.
Keep the existing Hermes application and port 7860.
Prefer focused changes with explicit ownership boundaries.
Do not accept “implemented” without code review, tests, and deployed evidence.

Coding style

Python configuration:

Python target: 3.10+
line length: 120
formatter: Black
lint: Ruff

The runtime image currently uses a newer Python version, but overlay code should remain compatible with the configured project target unless deliberately changed.

Module ownership

Acquisition/normalization/provenance: dual_datasource_client.py.
Binance-only HTTP/normalization: binance_public_client.py.
Signal/plan orchestration: trade_cycle.py.
Risk formulas: risk.py.
Execution behavior: futures_execution.py.
Bounded dashboard memory: state.py.
HTTP contracts/runtime diagnostics: futures_dashboard_api.py.
Visual/UI behavior: Luxury template.
Webhook-only Telegram: telegram_bot.py.
Overlay installation/process startup: sync_hf.py.

Do not duplicate logic across layers.

Adding a field

Define the legitimate source and authority.
Add narrow normalization aliases.
Add field validity rules.
Preserve source, provider timestamp, freshness, and fallback status.
Add the field to public bounded metadata only if safe.
Add additive API output.
Render missing value as Unavailable.
Add focused tests.

Changing deterministic logic

A change to score thresholds, weights, SL/TP, leverage, risk profile, sizing, slippage threshold, or expiry is safety-sensitive. The pull request must include:

motivation;
before/after behavior;
test coverage;
risk analysis;
confirmation that DS4 authority and guard behavior remain intact;
production verification plan.

Frontend contributions

Keep a single template and existing route.
Avoid duplicate DOM IDs.
Avoid undefined CSS variables.
Preserve keyboard accessibility and reduced motion.
Never add a second Execute path or an execution shortcut.
Do not trust localStorage for plan authorization.
Keep raw errors out of primary cards.

Commit hygiene

Do not stage:

.env
credentials
cookies
tokens
.runtime_audit/
__pycache__/
*.pyc
cache files
runtime state
screenshots with secrets
ZIP packages
temporary probes

Pull request checklist

Scope is focused.
No architecture duplication.
No deterministic guard weakened.
Source attribution remains correct.
Missing/stale data fails closed.
Diagnostics are sanitized.
API is additive.
Static checks pass.
Focused tests pass.
Futures regression suite ran once.
Deployment audit/browser plan is documented.
No trade will be executed during verification.

Project Status

Snapshot

This documentation describes the UI v3 implementation package prepared on 2026-07-21.

Repository base recorded by the implementation package:

3ff79ee0fce31f8d09a7dac357904169d50d9f3e

Last known deployed revision before this package:

24d8dad11c0d7316446e9a26b0b074e8630de139

The package was deployed to Really-amin/SimpleChatbot at revision 7734da310dc743698dd1fce189d265311042b4f1 after a parent-revision check.

Implemented backend/runtime work

packaged Luxury template is the runtime source;
overlay installation and SHA-256 manifest;
runtime status verified / mismatch / unknown;
no-cache Futures responses;
KuCoin millisecond range construction;
conservative DS4 Futures verification;
DS4/Binance/DS2 normalization and priority;
per-field provenance and truthful freshness;
structured source health and merge readiness;
real market endpoint with four intervals;
explicit partial/stale/unavailable semantics;
deterministic state machine and non-executable plan semantics;
server-side plan/symbol/risk/expiry/readiness/risk revalidation;
stronger diagnostic redaction;
read-only runtime audit utility;
Telegram webhook-only and Linear MCP isolation preserved.

Implemented UI v3 work

watchlist and recent markets;
manual/automatic refresh and density/theme controls;
keyboard help without execution shortcut;
Candles/Line chart, volume, crosshair, tooltip, four intervals, three limits;
market header, source/freshness/readiness, order-book top values;
display-only diagnostics;
per-field provenance;
plan geometry and execution checklist;
analysis copy/export/history/activity;
expanded datasource and technical diagnostics;
responsive desktop/tablet/mobile layout.

Validation already recorded

Static validation reported:

modified Python files compiled;
dashboard JavaScript passed node --check;
DOM ID and static reference checks passed;
CSS custom-property checks passed;
whitespace checks passed;
package ZIP integrity passed.

Behavioral tests, Futures regression tests, authenticated production verification, and deployment are complete for the current revision. The sanitized evidence is retained in deployment_reports/simplechatbot_runtime_audit_7734da3_20260722.json.

Production verification evidence

93 Futures tests passed; static/security checks passed.
Authenticated audit passed all 14 checks; all four intervals returned real candles.
Runtime overlay and served template hashes matched (runtimeStatus=verified).
BTCUSDT analysis returned NO_TRADE; no Paper Execute request was made.
Browser Market view rendered real candles with no console errors; Execute remained disabled.
Telegram remained disabled in webhook mode; the existing external bot webhook was not changed.
No secret was committed, uploaded, or written to the audit report.

Hermes Futures Desk — Complete Developer Documentation

Contents

Hermes Futures Desk — Complete Developer Guide

1. Purpose

2. Runtime summary

3. Main modules

4. End-to-end request flow

4.1 Market display

4.2 Deterministic analysis

4.3 Paper execution

5. Datasource authority

6. Health model

7. Analysis and plan states

Analysis states

Plan types

Market endpoint states

8. Deterministic scoring and risk rules

9. Frontend behavior

10. Authentication

11. Telegram model

12. Runtime integrity

13. Development workflow

14. Read-only runtime audit

15. Known deployment limitations

16. Definition of done

Architecture

System context

Container and filesystem architecture

Layer responsibilities

HTTP and UI layer

Datasource layer

Decision layer

Risk layer

Execution layer

State layer

Trust boundaries

Router installation

Persistence

Failure behavior

API Reference

Base and authentication

GET /futures

GET /api/futures/status

GET /api/futures/symbols

GET /api/futures/positions

GET /api/futures/market

POST /api/futures/analyze

POST /api/futures/paper/execute

Telegram routes

POST /api/telegram/webhook

GET /api/telegram/status

GET /api/telegram/bootstrap/status

Datasource Pipeline and Contracts

Priority and authority

Datasource 4

Binance public

Datasource 2

Datasource 4 request

Normalized fields

Contract

Ticker

OHLCV

Order book

Funding

Open Interest

Field usability

Per-field provenance

Freshness

Critical fields and readiness

Source metadata

Merge diagnostics

Adding a new provider mapping

Frontend Guide

File and runtime

Design system

Main UI regions

API usage

Refresh behavior

Chart behavior

Display-only diagnostics

`GET /futures`

`GET /api/futures/status`

`GET /api/futures/symbols`

`GET /api/futures/positions`

`GET /api/futures/market`

`POST /api/futures/analyze`

`POST /api/futures/paper/execute`

`POST /api/telegram/webhook`

`GET /api/telegram/status`

`GET /api/telegram/bootstrap/status`

`/futures` returns 200 but old UI appears

Runtime status is `unknown`

Runtime status is `mismatch`

`NO_TRADE` displayed before analysis