Strategy Engine

Declarative strategy intents — define what you want, the engine runs it. Covers the intent model, template presets, validation, parameter derivation, and agent orchestration.

1. Intent model

A StrategyIntent is a declarative specification of an index-tracking strategy. You describe what you want — the ticker to track, the capital to deploy, the risk constraints — and the Strategy Engine activates agents that execute it. You never write agent orchestration logic; the engine derives it from your parameters.

Lifecycle states

What the engine does

When an intent transitions to active, the Strategy Engine:

1. Validates all parameters against known-good ranges and cross-field sanity rules.
2. Derives operational parameters (expected rolls/year, estimated annual cost).
3. Selects the required agent set based on strategy type.
4. Allocates vaults on-chain via the PoolVault template.
5. Starts the rebalancing loop: monitor price, roll at threshold, enforce constraints.
6. Writes runtime state back to the intent (runtime field) so the frontend can poll it.

2. Full schema

The canonical TypeScript type for StrategyIntent (from packages/agent-sdk/src/intents.ts). Every field is shown with its type and purpose.

// ── Type aliases ──
type StrategyType = 'treasury' | 'hedge' | 'leverage' | 'yield' | 'custom';
type IntentStatus = 'active' | 'paused' | 'completed' | 'cancelled' | 'error';
type RollStrategy = 'standard' | 'shortDated' | 'manual';
type NotificationChannel = 'email' | 'push' | 'inapp' | 'webhook';

// ── Sub-objects ──
interface CollateralSpec {
  asset: 'USDC' | 'WETH' | 'WBTC';  // collateral asset
  amount: string;                    // decimal string, e.g. "10000.00"
}

interface IntentConfig {
  strikeRatio: number;          // 0.01–1.0, e.g. 0.50 = 50% strike
  maturityDays: number;         // 1–365, option maturity in calendar days
  rebalanceThreshold: number;   // >= 1.0, rotate when price < strike * threshold
  autoRoll: boolean;            // auto-roll at maturity / threshold breach
  rollStrategy: RollStrategy;   // standard | shortDated | manual
}

interface IntentConstraints {
  maxAnnualDriftBps: number;      // max tolerated annual drift (basis points)
  maxSlippagePerRollBps: number;  // max slippage per roll (basis points)
  maxCapital: string;             // hard capital cap (decimal string)
  stopLossDriftBps: number;       // unwind if drift exceeds this (basis points)
}

interface IntentNotifications {
  onRoll: boolean;               // notify on each roll
  onThresholdBreach: boolean;    // notify when rebalance threshold is crossed
  onStopLoss: boolean;           // notify if stop-loss triggers
  channels: NotificationChannel[];  // at least one channel
}

interface IntentRuntime {
  vaultIds: string[];          // active on-chain vault contract IDs
  currentDriftBps: number;     // live annualized drift in basis points
  totalRolls: number;          // count of rolls executed so far
  totalCostBps: number;        // cumulative realized slippage in bps
  lastRollAt: string;          // ISO 8601 timestamp of last roll
  lastRollCostBps: number;     // slippage cost of last roll in bps
}

// ── Top-level intent ──
interface StrategyIntent {
  id: string;                      // auto-generated: intent-{unixms}-{8hex}
  owner: string;                   // Canton party (from JWT sub)
  type: StrategyType;              // strategy preset
  status: IntentStatus;            // lifecycle state
  statusReason?: string;           // e.g. "Stop-loss triggered: drift exceeded 5%"

  collateral: CollateralSpec;      // what capital to deploy
  ticker: string;                  // e.g. "BTC/USDC"

  config: IntentConfig;            // strategy parameters
  constraints: IntentConstraints;  // risk guardrails
  notifications: IntentNotifications;  // alert preferences

  runtime?: IntentRuntime;         // live state (populated by agents)
}

3. Strategy templates

Five pre-configured templates with backtest-optimal defaults. Each template provides a complete config + constraints + notifications triple. Use createFromTemplate(type, overrides) to merge user values over the template defaults.

Notification defaults

Template descriptions

treasury — Treasury Management

Conservative yield generation for DAO treasuries. Low drift (200 bps cap), capital preservation focus. Suitable for stablecoin holdings seeking modest yield without meaningful directional risk. Default max capital of 1B reflects DAO scale.

hedge — Portfolio Hedge

Protect existing crypto holdings against drawdowns. Lower strike (0.30 = cheaper protection, lower coverage). Short-dated rolls (14-day maturity, shortDated strategy). For active portfolio managers hedging directional exposure.

leverage — Leveraged Exposure

Amplified directional exposure. Highest strike (0.80) for maximum delta per unit of capital. Most aggressive ranges — 2000 bps drift tolerance, 5000 bps stop-loss. 7-day maturity with shortDated rolls. For sophisticated traders comfortable with significant downside risk.

yield — Yield Generation

Passive yield from options premium. Mid-range strike (0.50), longest maturity (60 days) for lowest roll frequency and cost. Threshold breach notifications off by default — designed for depositors seeking steady returns without active management.

custom — Custom Strategy

Full manual control — no defaults enforced, all parameters must be explicitly configured. autoRoll and all notifications off by default. rollStrategy is manual. For advanced users with specific requirements not covered by the presets.

4. Validation rules

Every intent goes through a two-stage validation pipeline before it can be activated. Stage 1 blocks invalid intents with errors; Stage 2 produces warnings for configurations that are technically legal but likely misconfigured.

4.1 Parameter ranges (hard errors)

4.2 Cross-field sanity checks (warnings)

4.3 Type-specific warnings

4.4 Validation response shape

Validation returns a structured result — never throws. Errors block activation; warnings are advisory.

interface ValidationResult {
  valid: boolean;     // false if any errors exist
  errors: string[];   // hard blockers — intent cannot activate
  warnings: string[]; // advisory — intent can activate but may be misconfigured
}

5. Parameter derivation

When the Strategy Engine activates an intent, it derives three operational parameters from the config and constraints. These drive the agent orchestration plan and appear in the frontend as pre-flight estimates.

Cost model quick reference

These are worst-case estimates — actual costs depend on market conditions at roll time. The paper documents empirical drift of ~1–4%/year; real-world costs are typically 30–50% of these ceilings.

6. Agent orchestration

Each strategy type requires a specific set of agents to execute. The Strategy Engine selects and launches them automatically when the intent transitions to active.

7. TypeScript example

End-to-end example: create a BTC/USDC treasury intent, validate it, activate it, and poll for runtime state. Production-quality code using the Agent SDK.

import {
  createFromTemplate,
  validateStrategyConfig,
  deriveParams,
  type StrategyIntent,
} from '@medici/agent-sdk';

// ── Step 1: Create from template with overrides ──
const strategy = createFromTemplate('treasury', {
  config: { strikeRatio: 0.55 },  // slightly more aggressive than default 0.50
});

console.log('Config:', strategy.config);
console.log('Constraints:', strategy.constraints);
console.log('Notifications:', strategy.notifications);

// ── Step 2: Validate ──
const validation = validateStrategyConfig(
  'treasury',
  strategy.config,
  strategy.constraints,
);

if (!validation.valid) {
  console.error('Validation errors:', validation.errors);
  process.exit(1);
}
if (validation.warnings.length > 0) {
  console.warn('Warnings:', validation.warnings);
}

// ── Step 3: Derive operational params ──
const params = deriveParams(strategy.config, strategy.constraints);
console.log('Expected rolls/year:', params.expectedRollsPerYear);
console.log('Max annual cost (bps):', params.estimatedMaxAnnualCostBps);
console.log('Paper-optimal:', params.isPaperOptimal);

// ── Step 4: Build the create-intent request ──
const request = {
  type: 'treasury' as const,
  ticker: 'BTC/USDC',
  collateral: { asset: 'USDC' as const, amount: '50000.00' },
  config: strategy.config,
  constraints: strategy.constraints,
  notifications: strategy.notifications,
};

// ── Step 5: Submit to Ledger Service ──
const response = await fetch('https://canton.int.medici.loan/api/v1/intents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify(request),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Create failed: ${err.error} — ${err.message}`);
}

const { intent } = await response.json();
console.log('Intent created:', intent.id, 'status:', intent.status);

// ── Step 6: Poll runtime state (every 30s) ──
const poll = async (intentId: string) => {
  const res = await fetch(
    `https://canton.int.medici.loan/api/v1/intents/${intentId}`,
    { headers: { Authorization: `Bearer ${token}` } },
  );
  const { intent: fresh } = await res.json();
  if (fresh.runtime) {
    console.log(`Drift: ${fresh.runtime.currentDriftBps} bps | Rolls: ${fresh.runtime.totalRolls} | Cost: ${fresh.runtime.totalCostBps} bps`);
  }
};

const interval = setInterval(() => poll(intent.id), 30_000);

// Stop polling when done
process.on('SIGINT', () => { clearInterval(interval); });

8. cURL example

Create, inspect, and manage a strategy intent directly via the Ledger Service REST API. All examples use BTC/USDC as the tracked ticker.

8.1 Create a treasury intent

# Set your base URL and JWT token
BASE="https://canton.int.medici.loan"
TOKEN="$(curl -s -X POST https://keycloak.int.medici.loan/realms/medici/protocol/openid-connect/token \
  -d grant_type=password \
  -d client_id=app-user-validator \
  -d username=alice \
  -d password="$PASSWORD" \
  -d client_secret="$CLIENT_SECRET" | jq -r '.access_token')"

# Create the intent
curl -s -X POST "$BASE/api/v1/intents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "treasury",
    "ticker": "BTC/USDC",
    "collateral": {"asset": "USDC", "amount": "50000.00"},
    "config": {
      "strikeRatio": 0.50,
      "maturityDays": 30,
      "rebalanceThreshold": 1.5,
      "autoRoll": true,
      "rollStrategy": "standard"
    },
    "constraints": {
      "maxAnnualDriftBps": 200,
      "maxSlippagePerRollBps": 10,
      "maxCapital": "50000.00",
      "stopLossDriftBps": 500
    },
    "notifications": {
      "onRoll": true,
      "onThresholdBreach": true,
      "onStopLoss": true,
      "channels": ["inapp", "webhook"]
    }
  }' | jq .

# Response (201):
# {
#   "intent": {
#     "id": "intent-1719763200000-a1b2c3d4",
#     "owner": "alice",
#     "type": "treasury",
#     "status": "active",
#     "ticker": "BTC/USDC",
#     "collateral": {"asset": "USDC", "amount": "50000.00"},
#     "config": { ... },
#     "constraints": { ... },
#     "notifications": { ... },
#     "createdAt": "2026-06-30T12:00:00Z",
#     "updatedAt": "2026-06-30T12:00:00Z"
#   },
#   "fetchedAt": "2026-06-30T12:00:00Z"
# }

8.2 List, pause, and cancel

# List all active intents
curl -s "$BASE/api/v1/intents?status=active" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Get a specific intent
INTENT_ID="intent-1719763200000-a1b2c3d4"
curl -s "$BASE/api/v1/intents/$INTENT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Pause it
curl -s -X POST "$BASE/api/v1/intents/$INTENT_ID/pause" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Resume it
curl -s -X POST "$BASE/api/v1/intents/$INTENT_ID/resume" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Cancel it (soft-delete — terminal)
curl -s -X DELETE "$BASE/api/v1/intents/$INTENT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

# List strategy templates (no auth required)
curl -s "$BASE/api/v1/strategies" | jq .

# Portfolio summary
curl -s "$BASE/api/v1/portfolio" \
  -H "Authorization: Bearer $TOKEN" | jq .

8.3 Update an intent

# Update config and constraints (partial — only changed fields)
curl -s -X PUT "$BASE/api/v1/intents/$INTENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "strikeRatio": 0.55,
      "maturityDays": 45
    },
    "constraints": {
      "maxAnnualDriftBps": 300
    }
  }' | jq .

Full API Reference →