Building your own

Write a strategy bundle from scratch: STRATEGY.md, strategy.yaml, optional tools, custom data, and the mistakes to avoid.

Writing a strategy is mostly an exercise in being precise about what you want. The new bundle format keeps that precision in three places: prose for the agent, config for the runtime, and tools for optional outside context.

By the end of this page you should be able to write a useful first bundle. Do not expect to write a great one on the first pass. That comes from running it, reading the decision log, and revising.

Start with the trade

Before you write files, write one sentence:

I want to fade extreme funding on liquid perps, except in vol spikes.

If you cannot say what you are trying to do in one sentence, you are not ready to configure the bundle. Once you have the sentence, split it into three surfaces:

  • STRATEGY.md: how the agent should think.
  • strategy.yaml: what Engine is allowed to run.
  • Optional tools.yaml: what external context the agent may fetch.

Step 1: write STRATEGY.md

Start with the playbook. Keep it readable. A good STRATEGY.md explains the setup, the vetoes, and the workflow.

# Funding Harvester

Trade against extreme negative funding on liquid perps when open interest
confirms that shorts are still crowding in.

## Entry setup

- Look for funding that is deeply negative and sustained.
- Prefer markets where open interest is rising, not falling.
- Avoid thin books and high-volatility liquidation cascades.
- If the setup is marginal, abstain.

## Exit and management

- Use a stop where the crowding thesis is invalidated.
- Take profit when funding normalizes or price squeezes into resistance.
- Trail stops only after the trade has moved enough to protect entry.

## Rules

entry: funding_1h < -0.003 AND oi_delta_4h > 0.03 AND realized_vol_24h < 0.80
exit: pnl_pct >= 0.02 OR drawdown <= -0.012
size: fixed_pct(0.03) capped at position_pct

The ## Rules block is required only for rules and both modes. If your strategy is pure thesis mode, you can omit it and let the agent reason from the prose.

Step 2: write strategy.yaml

strategy.yaml is where hard boundaries live. It tells Engine which markets to snapshot, how often to tick, how big positions can be, and what context the agent should see.

name: funding-harvester
slug: funding-harvester
author: "0x4f2a000000000000000000000000000000000001"
version: 1.0.0
universe: [BTC-PERP, ETH-PERP, SOL-PERP, HYPE-PERP]
capacity_usd: 500000
cadence: 5m
mode: both
data: [hl.funding, hl.oi, hl.marks]
risk:
  max_leverage: 2
  max_drawdown: 0.08
  position_pct: 0.05
  daily_loss_limit: 0.032
  stop_loss: 0.012
  take_profit: 0.02
fees:
  perf: 0.10
  hurdle: 0
  hwm: true
inputs: [market_context, positions, account, regime_tags, memory]
permissions:
  can_emit_trade_intents: true
  can_execute_orders_directly: false
outputs: [TradeIntent, NoTrade]
when_to_use: Use in liquid markets when funding is stretched but volatility is not in cascade mode.
min_conviction: 0.55

A few fields matter more than the rest:

Universe. Start explicit. Naming BTC-PERP, ETH-PERP, SOL-PERP, and HYPE-PERP teaches you faster than a broad category.

Mode. Use rules for deterministic thresholds, thesis for contextual setups, and both when rules should gate but the agent should still confirm.

Risk. position_pct is enforced. The agent can ask for more, but Engine clamps the order to the cap. max_drawdown and daily_loss_limit stop future ticks through risk events.

Inputs. Include the context your playbook needs. If you omit inputs, Engine includes every available category.

Minimum conviction. Use min_conviction when you want marginal trades downgraded to abstain.

Step 3: add tools only when needed

If your thesis depends on outside context the default snapshot does not contain, add a tool. A tool is an HTTPS endpoint the agent can call by name.

tools:
  - name: fetch_news
    description: Returns recent headlines and sentiment for a symbol.
    endpoint: https://api.example.com/news
    method: POST
    auth:
      type: bearer
      secret: NEWS_API_KEY
    input_schema:
      type: object
      properties:
        symbol: { type: string }
      required: [symbol]
    output_schema:
      type: object
      properties:
        headlines: { type: array }
        news_sentiment_score: { type: number }

Then tell the agent when to use it in STRATEGY.md:

Before entering a news-driven breakout, call `fetch_news` for the candidate
symbol. Trade only when the returned headlines support the direction of the
breakout. Abstain if the tool is unavailable.

Tools are for on-demand context. They are not run automatically. The agent decides whether the cost and latency are justified for the current tick.

Step 4: add custom data when rules need it

Custom data sources are cadence-pulled numeric signals. Use them when the value should appear in the tick snapshot and be usable by rules.

data_sources:
  - name: sentiment
    webhook_url: https://signals.example.com/sentiment
    identifiers: [sentiment_score]
    per_market: true
    ttl_seconds: 60
    auth_header_env: NEWS_API_KEY

With that declared, a ## Rules block can reference sentiment_score:

entry: sentiment_score > 0.70 AND realized_vol_24h < 0.80
exit: pnl_pct >= 0.03 OR drawdown <= -0.015
size: fixed_pct(0.02) capped at position_pct

A few things to know:

  • Per-market sources are supported. Set per_market: true and the resolver requests values for the universe.
  • Auth uses strategy secrets. Do not put credentials in the bundle. Store the value in Engine and reference it by env-style name.
  • TTLs keep values fresh. Set short TTLs for fast signals and longer TTLs for slow regime labels.
  • Failures are visible. The agent sees unavailable custom signals, and rules comparisons against missing values do not fire.

Complete example

Here is a compact bundle that uses rules plus thesis confirmation:

strategy bundle
STRATEGY.md
-----------
# Funding Harvester

Trade against extreme negative funding on liquid perps when open interest
confirms that shorts are still crowding in.

## Entry setup
- Funding is deeply negative and sustained.
- Open interest is rising, not falling.
- Volatility is not in cascade mode.
- Abstain when the book is thin or signals conflict.

## Exit and management
- Use a stop where the crowding thesis is invalidated.
- Take profit when funding normalizes or price squeezes into resistance.
- Trail stops only after the trade has protected entry.

## Rules
entry: funding_1h < -0.003 AND oi_delta_4h > 0.03 AND realized_vol_24h < 0.80
exit: pnl_pct >= 0.02 OR drawdown <= -0.012
size: fixed_pct(0.03) capped at position_pct

strategy.yaml
-------------
name: funding-harvester
slug: funding-harvester
author: "0x4f2a000000000000000000000000000000000001"
version: 1.0.0
universe: [BTC-PERP, ETH-PERP, SOL-PERP, HYPE-PERP]
capacity_usd: 500000
cadence: 5m
mode: both
data: [hl.funding, hl.oi, hl.marks]
risk:
  max_leverage: 2
  max_drawdown: 0.08
  position_pct: 0.05
  daily_loss_limit: 0.032
  stop_loss: 0.012
  take_profit: 0.02
fees:
  perf: 0.10
  hurdle: 0
  hwm: true
inputs: [market_context, positions, account, regime_tags, memory]
permissions:
  can_emit_trade_intents: true
  can_execute_orders_directly: false
outputs: [TradeIntent, NoTrade]
when_to_use: Use in liquid markets when funding is stretched but volatility is not in cascade mode.
min_conviction: 0.55

Two mistakes everyone makes

Putting hard limits only in prose. If a limit should be enforced, put it in strategy.yaml. STRATEGY.md guides the agent, but the runtime enforces config.

Adding a tool for every idea. Tools are powerful, but they add latency and failure modes. Put always-needed numeric signals in data_sources[]. Put expensive or rich context in tools.yaml. Leave everything else in prose.

No abstain condition. A strategy that does not say when to sit out will eventually force trades in a regime it does not understand. Write vetoes clearly.

Operational notes

  • The validator runs before deploy. It catches malformed YAML, missing references, unknown rule identifiers, invalid tool schemas, and unsafe endpoints.
  • Endpoint probes run on publish. Data sources and tools are probed unless you publish as draft and set secrets later.
  • Hot reload works. Saved changes are picked up on the next tick. Open positions are not closed automatically.
  • Versioning is built in. Each publish writes a new version and stores the full bundle.

What's next

See Examples for complete bundles, including a rules-first strategy, a thesis-first momentum strategy, and a strategy with an author-declared tool.