Skip to main content
Before you promote your first agent to live trading, it helps to understand the mechanics that govern how Halyrd works. This page explains each core concept clearly — from the paper/live split through to the two-layer risk model and how strategies are defined and versioned.

​
Paper mode vs live mode

Halyrd’s two modes — paper and live — run the same agent code. The only thing that changes between them is how orders are filled. In paper mode, the agent gets a real executable quote from TWAK (the same source it would use to make a live trade), applies a pessimistic fill model that includes swap fees, gas, and slippage, and records the result against a virtual portfolio. The simulated fills are deliberately not optimistic — they reflect what you would actually receive on BSC. In live mode, the agent calls TWAK to sign and broadcast a real swap transaction on BSC mainnet. The signal logic, fee filter, and risk checks that ran in paper mode run identically.
Because paper and live price trades from the same TWAK quote source, there is no hidden gap between how paper results were calculated and what live execution would look like. The track record you build in paper mode is an honest one.

​
Evaluation

While the agent runs in paper mode it builds a track record. The Risk Engine continuously measures that record against three criteria. Only when all three are satisfied does the agent receive an ELIGIBLE status. 1. Positive expectancy after fees The average profit per closed trade, once swap fees, gas costs, and slippage are subtracted, must be positive. An agent that wins often but loses more than it earns on fees does not pass this criterion. 2. Trade floor of closed trades A minimum number of completed round-trips must exist before expectancy is treated as meaningful. Below this floor, a run of lucky early trades produces a misleadingly good number. The evaluation window extends automatically if the trade floor has not been reached when the window would otherwise close. 3. No max-drawdown breach during the window The agent’s equity must not have hit its hard drawdown ceiling at any point during the evaluation window. A single breach resets eligibility for that config version.
An agent that stalls before reaching the trade floor — because it rarely finds trades that clear the fee filter — is giving you accurate information: its capital is too small relative to fixed per-trade costs to generate enough activity. This is not a product limitation; it is the correct, capital-agnostic signal.

​
Promotion

Promotion is the moment your agent switches from simulated fills to real BSC transactions. It is manual by default: the dashboard shows you the evaluation results, and you make the decision to flip the agent live. When you confirm promotion, the dashboard moves the status badge from ELIGIBLE to LIVE, the first real signed transaction hash appears as a milestone on the equity chart, and TWAK’s guardrails activate for all subsequent orders. If your agent has not yet been marked ELIGIBLE, you can still promote using force promote. This path is always available — the evaluation produces evidence, not a lock — but the dashboard shows an additional warning to make the decision deliberate.
Force-promoting an agent that has not passed evaluation means trading with real funds before the agent has demonstrated risk discipline in paper mode. Review the journal and equity curve carefully before proceeding.

​
Demotion

Halyrd demotes agents automatically when a risk rule is breached in live mode. The agent never silently continues trading past a limit. Daily drawdown breach → live locked until the next UTC day If the agent’s equity falls by more than the configured daily drawdown percentage within a single UTC day, live trading is paused until midnight UTC. The agent does not stop running — it keeps paper-trading through the lockout, building track record data and journaling every decision. The dashboard shows a PAPER sub-badge so the current mode is never ambiguous. Live trading resumes automatically when the new UTC day begins. Max drawdown breach → demoted to paper until you re-approve If the agent’s equity falls below the hard max-drawdown ceiling, it immediately flattens all positions to USDT and returns to paper mode. It will not go live again until you review its paper-mode results and manually approve re-promotion. The journal records the exact rule that fired and when.

​
Risk Engine — the policy layer

The Risk Engine is Halyrd’s intelligent, strategy-aware safety layer. It runs identically in both paper and live mode. Before every trade it asks: would this order risk breaching any configured rule? After every hourly equity snapshot it checks whether any threshold has been crossed. When the Risk Engine blocks a trade, the block appears in the journal with a plain-English explanation (“Trade blocked: would breach daily drawdown limit”), in the risk desk’s policy column, and as a real-time update the dashboard displays immediately. The Risk Engine is smart but fallible. It lives in the application code, it depends on correct state, and like all code it can have bugs. That is exactly why TWAK guardrails exist as a separate, independent layer beneath it.

​
TWAK guardrails — the physics layer

The TWAK guardrails operate at the transaction-signing layer, outside Halyrd’s application code entirely. They are configured on the Trust Wallet Agent Kit signer and enforced before any transaction can be broadcast.
GuardrailWhat it enforces
Token allowlistOnly tokens on the approved list can be swapped. The allowlist always covers at least every token on your active watchlist.
Per-trade capNo single swap can exceed a configured maximum size.
Daily volume capTotal daily swap volume is capped regardless of how many individual trades occur.
Slippage protectionEvery swap includes a maximum-slippage bound enforced at signing time.
Kill switchRevoking the TWAK session immediately prevents the agent from signing any further transactions.
When TWAK refuses a transaction, the refusal appears in the risk desk’s physics column alongside the reason. The TWAK guardrails are simple but infallible. They do not know your strategy intent or equity history — they only know whether a specific transaction falls within the permitted envelope. Even if Halyrd’s own code contains a logic error, even if the LLM component behaves unexpectedly, TWAK will not sign a transaction that violates its limits.
The Risk Engine decides what is smart. TWAK decides what is physically possible. A trade must pass both checks before it executes.

​
StrategySpec — declarative strategy definition

Every Halyrd strategy is defined as a StrategySpec: a YAML document that describes indicators, entry and exit conditions, a regime filter, and position-sizing parameters. The spec is declarative — it describes rules, not executable code — which means it can be backtested, validated, and audited before it is ever attached to a live agent. A minimal spot strategy spec looks like this: 
market_mode: spot
name: "mean-reversion-v1"
signals:
  entry:
    all_of:
      - { indicator: price_vs_sma, op: "<=", value: -0.05, window: 48 }
      - { indicator: rsi,          op: "<=", value: 25,    window: 14 }
      - { indicator: fear_greed,   op: "<=", value: 40 }
  exit:
    any_of:
      - { indicator: price_vs_sma, op: ">=", value: 0.0 }
      - { indicator: rsi,          op: ">=", value: 65 }
regime_filter:
  stand_aside_when:
    - { indicator: funding_rate, op: ">=", value: 0.03 }
params: { position_size_pct: 90, max_concurrent: 1 }
The market_mode field is required and must be set first. On spot mode, the parser rejects any signal configuration that would produce a short sell — spot trading is long-only, exiting to USDT between positions. StrategySpecs drive both the in-app backtester and the live signal engine. The same YAML you test in the research area is what the agent loads when it runs.

​
Strategy versions

Every time you change a strategy’s parameters, Halyrd creates a new strategy version with a unique ID. The old version is retired; the new one starts accumulating its own track record from scratch. The config versions page in the dashboard shows a timeline of every version you have tried: which parameters each used, when each ran, whether it was retired early or ran to completion, and which one is currently active. If a version was promoted to live, that milestone appears in its history. This is an auditable record of how you arrived at your current configuration — not a learning loop, not parallel A/B testing, but a sequential evidence trail you can point to and review.

​
Capital-agnostic fee filter

Before any signal reaches the Risk Engine, it must pass the fee filter: the expected edge on the trade must exceed three times the total cost of executing it (swap fee + gas + estimated slippage). Because gas is a fixed cost per trade regardless of position size, this filter behaves differently at different capital levels. At larger account sizes, a given percentage move produces enough absolute profit to clear the three-times hurdle easily, and more trades pass. At smaller account sizes, the fixed gas cost represents a larger fraction of the profit, and fewer trades pass. This is intentional. The filter does not lower its bar as your account shrinks — it accurately reflects how many trades are genuinely worth taking. An agent that runs in low-activity mode at small capital sizes is not broken; it is correctly telling you that the edge available in the market does not justify the cost structure at that size. Every skipped trade — whether blocked by the fee filter, the Risk Engine, or a failed quote — appears in the journal with a reason. You can see exactly how the filter is behaving for your configuration.