Telemetry Report API

The Telemetry API is how a DepthSight node tells the hub about a finished trade. It is write-only and anonymous: there is no public registry of identities, only the machine-level binding between a node_uuid and its secret, verified with an HMAC signature over the exact request body.

The hub API lives in api/hub_router.py under the /api/v1/hub prefix. Node-local mining endpoints live in api/routes/config.py (prefix /api/v1, JWT-authenticated). All timestamps are UTC.

---

1. Authentication

Every hub request that touches mining uses the same credential headers, derived from the node's identity (node_uuid / node_secret).

Header	Value
X-Node-UUID	The node's node_uuid.
X-Node-Secret	The raw telemetry secret (TLS only; the hub stores only its SHA-256).
X-Node-Signature	Hex HMAC-SHA256 of the exact body bytes, keyed by the raw secret (report endpoints only).

Allowed values are validated against HubNode.secret_hash and the node is checked for the is_banned flag. Endpoints that only read (mining status, referrals, node list) accept the two credential headers without a body signature; the /telemetry/report path requires the signature.

Signing a preamble (schemas)

Sources: controller.py

The signature is computed over json.dumps(payload, sort_keys=True) — the exact bytes the hub will hash. telemetry_sync.py signs the same way for offline re-uploads.

---

2. Telemetry Report Payload

POST /api/v1/hub/telemetry/report accepts a single JSON object (camelCase):

Field	Type	Required	Description
symbol	string	✓	Trading pair, e.g. BTCUSDT
direction	string	✓	LONG / SHORT
entryPrice	float	✓	Average entry price
exitPrice	float	✓	Average exit price
pnlPercent	float	–	Net PnL % of the trade
tradeDurationSec	float	–	Hold time in seconds (eligibility gate, default ≥ 30)
exitReason	string	–	e.g. TP, SL, EXIT
tradeMode	string	✓	Must be LIVE to be eligible
strategyBlocks	array	–	[{type, params}] used for swarm insights
marketContext	object	–	{session?, natr?, adx?, volume_ratio?}
exchangeId	string	–	e.g. weex, bybit — must be in eligibleExchanges
marketType	string	–	spot / futures
brokerTradeId	string	–	Unique broker trade id (dedup key)
entryBrokerTradeIds	string[]	–	All entry client order ids
closeBrokerTradeIds	string[]	–	All close (TP/SL/exit) client order ids
tradeVolumeUsdt	float	–	Notional open+close volume (rebate basis)
attributionNodeUuid	string	–	Target miner node (defaults to the authenticated node)
sourceNodeUuid	string	–	The mining server hosting the miner (commission target)

Response — 201 Created {"status": "success", "message": "Telemetry report submitted successfully."}. Errors: 401 no credentials, 403 bad signature/attribution/source, 404 node unregistered, 409 brokerTradeId already claimed by another node.

Both attributionNodeUuid and sourceNodeUuid are client-supplied but server-validated: attribution to a different user's node is forbidden, and the source must be flagged is_mining_server (_verify_attribution, _verify_source_server).

---

3. Hub Endpoints

Method	Path	Auth / access	Purpose
POST	/api/v1/hub/nodes/register	Node secret (+ wallet signature for wallet nodes)	Register/update a node, bind wallet/referrer
POST	/api/v1/hub/nodes/ping	Node secret	Heartbeat + server reward share
POST	/api/v1/hub/nodes/revoke-telemetry	Wallet signature	Revoke a node's telemetry credential
GET	/api/v1/hub/nodes	Public	Active network map (pinged in the last 5 min)
GET	/api/v1/hub/mining/config	Public	Active mining config
POST	/api/v1/hub/mining/config	Admin	Update mining config
GET	/api/v1/hub/mining/status	Node credentials	Node's live mining status & estimate
GET	/api/v1/hub/mining/referrals	User / node	Referral tree of the account
GET	/api/v1/hub/mining/node-trades	Node credentials	Paginated telemetry trades for the node + its referrals
POST	/api/v1/hub/telemetry/report	Node sign	Submit a finished-trade telemetry report
GET	/api/v1/hub/telemetry/insights	Public	Swarm intelligence aggregates
POST	/api/v1/hub/mining/process-epoch	Admin	Manually finalize a past epoch
POST	/api/v1/hub/nodes/designate-operator	Admin	Mark a node as the fee-root operator

GET /api/v1/hub/mining/status

Returns (MiningStatusResponse):

{
  isMiningEnabled, eligibleExchanges, rebateRates,
  currentEpochDate, dailyEmission,          // halving-adjusted
  yourTotalMined, yourEpochReward,          // live estimate
  epochTotalRebates, participatingNodes,
  nodeReferralCode, referrerNodeUuid, hasWelcomeBonus,
  totalOperatorFeeCollected,
  yourTotalVolume, serverTotalVolume, yourMarketShare, yourEpochRebates
}

yourEpochReward is a live intraday estimate of MiningLedger for the current day and mirrors the exact epoch math (estimate_live_epoch_reward).

GET /api/v1/hub/mining/node-trades

Paginated view of a node's own telemetry plus that of directly referred nodes, with statusFilter (PENDING/VERIFIED/SKIPPED/ALL), exchange and search (symbol / broker trade id) filters. Each item carries tradeVolumeUsdt, verificationStatus, verificationError, verifiedVolumeUsdt, rewardTokens[].

GET /api/v1/hub/telemetry/insights

Swarm-intelligence insights aggregated over the last N days (optional symbol): groups reports by the sorted strategyBlocks combo, requires at least 5 trades per combo, and returns winRate, totalTrades, avgPnlPercent and the top bestExitReasons.

---

4. Local Node Mining API

These endpoints run on every DepthSight instance (JWT auth, config_router, prefix /api/v1). Non-hub nodes proxy hub data transparently when possible.

Method	Path	Description
GET	/api/v1/config/mining/status	Local node mining status (LocalMiningStatusResponse)
POST	/api/v1/config/mining/activate	Enable mining for the user, link referral, register the node
POST	/api/v1/config/mining/deactivate	Stop mining + telemetry for the user
GET / PUT	/api/v1/config/mining/node-config	Node-wide mining config (admin)
GET	/api/v1/config/mining/trades	Paginated local telemetry trades list (proxies /hub/mining/node-trades on non-hub)
POST	/api/v1/config/node/wallet/nonce	Create a SIWE ownership message for a wallet address
POST	/api/v1/config/node/wallet/verify	Verify wallet signature, bind deterministic node_uuid
GET	/api/v1/config/node/wallet/status	Current wallet / node binding
POST	/api/v1/config/node/wallet/disconnect	Unbind the wallet (keeps node history)

POST /api/v1/config/mining/activate

Body: { "referrerCode": "..." }. Requires a bound wallet (WALLET_REQUIRED otherwise). Activates is_mining_enabled = true, turns on shareTelemetry, registers the deterministic wallet node with the hub and returns the same LocalMiningStatusResponse as the status endpoint.

Mining status payload (LocalMiningStatusResponse)

{
  isMiningEnabled, nodeUuid, nodeName, registeredOnHub,
  nodeReferralCode, referrerNodeUuid, referrerReferralCode,
  hasWelcomeBonus, totalMined, config, stats,
  isGlobalMiningEnabled, userRewardSharePercent,
  userTradeVolume, userEstimatedRebate
}

---

5. Idempotency & Offline Sync

• brokerTradeId is the dedup key. Re-submitting the same one is a 409 conflict that the client treats as success (the local row is marked SENT).
• Reports saved locally while offline get verification_status = LOCAL_ONLY, then telemetry_sync.resync_pending_telemetry_reports() (or the Celery sync_pending_telemetry_task) uploads them in FIFO batches of 50 and flips them to SENT. It is skipped automatically when IS_CENTRAL_HUB=true; a local node without identity is skipped gracefully.
• The X-Node-Signature must be recomputed for every re-upload because it binds the exact request bytes, and the hub enforces the current hash of the secret.