Hermes ⇄ Trader Strategy Contract (v0.1)

This document defines what Hermes needs from Trader-managed strategies in order to make selection decisions.

Scope

Trader runs the strategies.
Hermes selects which configured strategy is active for each account and market.
A strategy is bound to a specific account and market.
Hermes queries strategies to see the available options for that account-market pair.
Trader may turn strategies on or off when instructed by Hermes.
Trader does not decide the global strategy choice on its own.

What a strategy represents

A strategy is an account-market specific operating mode. It is not a generic idea detached from venue, balance, or market context.

Required strategy bindings

Each configured strategy must be tied to:

strategy_id
account_id
market
base_currency
quote_currency
enabled_state

Hermes should be able to ask, for a given account and market, which strategies exist and whether they are currently enabled.

What Hermes needs from a strategy

When Hermes queries a strategy, it must receive the information below.

Identity and binding

strategy_id
strategy_name
account_id
market
base_currency
quote_currency
enabled_state
mode

Balance and exposure

account_balance
available_balance
base_position
quote_position
open_orders
reserved_balance
exposure
free_margin where relevant

Market suitability

expected_market_regime
avoided_market_regime
risk_profile
liquidity_expectation
event_risk_expectation
volatility_expectation

Live operating state

status
recent_changes
decision_history
current_intent
last_transition
last_update
uncertainty
confidence

Execution feedback

fills
slippage
latency
rejections
execution_quality
stress
venue_health

Strategy explanation

current_reason
key_drivers
warnings
constraints

Hermes decision inputs

Hermes should decide using the returned strategy snapshot plus external market information. The minimum decision inputs are:

market regime
liquidity state
event risk
sentiment pressure
current strategy state
balance and exposure state
execution quality
confidence and uncertainty
recent changes

Strategy response shape

A strategy query should return a compact structured snapshot with nested sections. Only information that changes Hermes decisions should be included.

Example:

{
  "identity": {
    "strategy_id": "btc-vienna-trend-1",
    "strategy_name": "trend_following",
    "account_id": "acc-01",
    "market": "BTC/USD",
    "base_currency": "BTC",
    "quote_currency": "USD"
  },
  "control": {
    "enabled_state": "on",
    "mode": "active"
  },
  "fit": {
    "expected_market_regime": "trend",
    "avoided_market_regime": "range",
    "risk_profile": "medium",
    "liquidity_expectation": "normal",
    "event_risk_expectation": "low",
    "volatility_expectation": "moderate"
  },
  "position": {
    "account_balance": {
      "base": 0.42,
      "quote": 18500.0
    },
    "available_balance": {
      "base": 0.12,
      "quote": 9400.0
    },
    "base_position": 0.30,
    "quote_position": 0.0,
    "reserved_balance": 1200.0,
    "open_orders": 2,
    "exposure": "long",
    "free_margin": 8200.0
  },
  "state": {
    "status": "running",
    "recent_changes": ["scaled in", "trimmed exposure"],
    "decision_history": ["held", "added", "held"],
    "current_intent": "follow upward structure",
    "last_transition": "2026-04-15T18:10:00Z",
    "last_update": "2026-04-15T18:25:00Z"
  },
  "assessment": {
    "confidence": 0.78,
    "uncertainty": "low",
    "current_reason": "trend intact, balance sufficient, execution stable",
    "key_drivers": ["trend", "balance", "liquidity"],
    "warnings": ["minimum_hold_minutes=15"]
  },
  "execution": {
    "fills": 12,
    "slippage": 0.0012,
    "latency": "normal",
    "rejections": 0,
    "execution_quality": "good",
    "stress": "low",
    "venue_health": "good"
  }
}

Strategy modes

A strategy may expose modes, but modes are not separate strategies. Examples:

slow trend
strong trend
cautious mean reversion
high-volatility breakout

Enabled and disabled state

Hermes must be able to see whether a strategy is:

on
off
paused
error
observe
active

Trader may manage those states internally, but Hermes needs a clear readback of them.

Control responsibility

Hermes may instruct Trader to:

switch a strategy on
switch a strategy off
keep a strategy on
keep a strategy off
shift risk mode
pause a strategy
resume a strategy

Trader should not invent a strategy decision that conflicts with Hermes without an explicit safety reason.

Selection rules

Hermes selects strategies per account-market combination using:

regime fit
balance and exposure fit
execution quality
current confidence
current uncertainty
recent state changes
event pressure
liquidity quality

Strategy taxonomy

Keep the strategy set small and orthogonal:

idle
defensive
trend_following
mean_reversion
grid
breakout
event_driven

First implementation order

Make the query result shape exact.
Make balance and exposure mandatory in strategy snapshots.
Make strategy bindings explicit per account and market.
Keep Hermes control limited to on/off and risk posture.
Implement idle and defensive first.
Implement trend_following and mean_reversion next.
Add grid, breakout, and event_driven after the core set is stable.
Add tests for balance reporting, selection inputs, and enable/disable control.

Versioning

This is v0.1. Future changes should stay focused on the information Hermes needs to make better decisions, not on exposing implementation detail.

Hermes_Trader_Contract_v0.1.md 5.8 KB Histórico Raw