YieldClaw

Autonomous vault manager and product builder for Orderly Network Strategy Vaults.

YieldClaw handles the full vault lifecycle — creation, automated trading, risk management, depositor operations, and share price reporting — as a single TypeScript process. It can run standalone with SQLite persistence or in ephemeral environments like Starchild AI with in-memory state.

What It Does

Create vaults on Orderly (OmniVault or Standard), configure fee structures, deposit limits, and lock periods.

Run automated strategies defined in YAML — signal evaluation, position sizing, entry/exit logic, trailing stops, and PnL settlement every 3 hours.

Manage risk with hard limits, a 4-level circuit breaker, and state reconstruction from live API data on every startup.

Serve depositors — user deposits, withdrawals, share redemptions, position tracking, and NAV/share price reporting.

Expose everything over 32 REST endpoints + SSE event streaming for real-time monitoring.

Quick Start

Prerequisites

Node.js >= 20
An Orderly Network account with an Ed25519 trading key pair
A Strategy Vault ID (or create one with yieldclaw vault create)

Install

git clone https://github.com/<your-org>/YieldClaw.git
cd YieldClaw
npm install
npm run build

Configure

cp .env.example .env

Fill in your credentials:

NETWORK=testnet
ACCOUNT_ID=0x...
ORDERLY_KEY_PUBLIC=ed25519:...
ORDERLY_KEY_PRIVATE=ed25519:...
VAULT_ID=your-vault-id
STRATEGY_PATH=./strategies/example-momentum.yaml

Create a Vault

yieldclaw vault create \
  -n "ETH Momentum Vault" \
  -b <BROKER_ID> \
  -t omnivault \
  --perf-fee 0.20 \
  --min-deposit 100

Register as Strategy Provider

yieldclaw vault register -v <VAULT_ID> -b <BROKER_ID>

Start Trading

# Standalone (SQLite persistence)
yieldclaw start -v <VAULT_ID> -s ./strategies/example-momentum.yaml

# Ephemeral / Starchild (in-memory, no DB)
yieldclaw start -v <VAULT_ID> -s ./strategies/example-momentum.yaml --memory

# Multi-vault mode
yieldclaw start -c ./config/multi-vault.yaml

Strategy Definition

Strategies are YAML files that define what to trade and how:

name: eth-momentum-v1
version: "1.0"
description: "ETH momentum strategy with funding rate confirmation"

universe:
  symbols:
    - PERP_ETH_USDC
  maxConcurrentPositions: 1

allocation:
  maxCapitalPct: 25
  maxLeverage: 3
  rebalanceIntervalSec: 300

signals:
  - type: momentum
    weight: 0.7
    params:
      fastPeriod: 12
      slowPeriod: 26
  - type: funding_rate
    weight: 0.3
    params:
      threshold: 0.01
      direction: contrarian

entry:
  minSignalStrength: 0.4
  confirmationPeriods: 1
  orderType: MARKET

exit:
  takeProfitPct: 3.0
  stopLossPct: 1.5
  trailingStopPct: 2.0
  maxHoldingPeriodSec: 43200
  signalReversal: true

timing:
  cycleIntervalSec: 30
  dataWindowSec: 86400

Available Signal Types

Signal	Description
`momentum`	EMA crossover (fast/slow period)
`mean_reversion`	Z-score deviation from rolling mean
`funding_rate`	Contrarian funding rate strategy
`volume_spike`	Volume anomaly detection
`composite`	Weighted combination of multiple signals

Validate before running:

yieldclaw validate ./strategies/my-strategy.yaml

CLI Reference

Core Commands

Command	Description
`yieldclaw start`	Start the CLAW trading loop
`yieldclaw validate <path>`	Validate a strategy YAML
`yieldclaw policy <path>`	Generate a Guardian policy

Vault Management (SP)

Command	Description
`vault create`	Create a new vault on Orderly
`vault info`	Vault info + statistics
`vault register`	Register SP trading key
`vault deposit`	Deposit USDC as SP
`vault withdraw`	Withdraw USDC as SP
`vault fees`	View SP fee earnings
`vault share-price`	Current share price / NAV / AUM
`vault depositors`	List all depositors
`vault snapshot`	Full vault state in one call
`vault performance`	APY, Sharpe, drawdown, win rate

Depositor (User) Operations

Command	Description
`vault user deposit`	Deposit USDC, receive shares
`vault user withdraw`	Withdraw by amount or share count
`vault user position`	View shares, value, P&L
`vault user transactions`	Deposit/withdrawal history
`vault user redemptions`	Pending redemption requests

API Endpoints

The API server starts automatically on HEALTH_PORT (default 8080) when running yieldclaw start.

Trading (GET — requires `HEALTH_TOKEN`)

Endpoint	Description
`/health`	Health check
`/api/v1/status`	NAV, state, circuit breaker
`/api/v1/positions`	Open positions
`/api/v1/signals`	Latest signal evaluations
`/api/v1/risk`	Circuit breaker, drawdown, exposure
`/api/v1/strategy`	Current strategy config
`/api/v1/metrics`	Cycle metrics history
`/api/v1/trades`	Trade history
`/api/v1/guardian-policy`	Generated Guardian policy
`/api/v1/events`	SSE real-time event stream

Control (POST — requires `ADMIN_TOKEN`)

Endpoint	Description
`/api/v1/pause`	Pause trading
`/api/v1/resume`	Resume trading
`/api/v1/strategy`	Hot-reload strategy parameters
`/api/v1/flatten`	Emergency close all positions

Vault Management

Endpoint	Description
`GET /api/v1/vaults`	List managed vaults
`GET /api/v1/vault/info`	Vault info
`GET /api/v1/vault/stats`	Vault statistics
`GET /api/v1/vault/performance`	Performance metrics
`GET /api/v1/vault/fund`	Fund info + period + transactions
`GET /api/v1/vault/periods`	Period history
`GET /api/v1/vault/share-price`	Share price, NAV, AUM
`GET /api/v1/vault/depositors`	Depositor list
`GET /api/v1/vault/snapshot`	Full vault snapshot
`POST /api/v1/vault/create`	Create vault
`POST /api/v1/vault/config`	Update vault config
`POST /api/v1/vault/deposit`	SP deposit
`POST /api/v1/vault/withdraw`	SP withdraw

Depositor Endpoints

Endpoint	Description
`GET /api/v1/vault/user/position`	Depositor position
`GET /api/v1/vault/user/transactions`	Depositor history
`GET /api/v1/vault/user/redemptions`	Pending redemptions
`POST /api/v1/vault/user/deposit`	User deposit
`POST /api/v1/vault/user/withdraw`	User withdraw

Architecture

src/
├── claw/           # Core trading loop, state machine, signal evaluator, trade executor
├── signals/        # Momentum, mean reversion, funding rate, volume spike, composite
├── risk/           # Hard limits, circuit breaker (4-level), trailing stops
├── execution/      # DirectProvider (API), GuardianProvider (intent-based), policy generator
├── vault/          # VaultManager, multi-vault orchestrator, performance analytics
├── store/          # StateStore interface → SqliteStateStore | MemoryStateStore
├── api/            # 32 REST endpoints + SSE, auth, rate limits, IP allowlisting
├── client/         # Orderly Network client + Strategy Vault client, Ed25519 signing
├── strategy/       # YAML parser, Zod validation, AI-safe restricted schema
├── config/         # Environment config, hard limit defaults
├── types/          # Vault, trade, market type definitions
└── util/           # Logger (with sanitization), math, time, retry

CLAW Loop Cycle (every 30s)

Fetch positions, balances, tickers, klines, orderbook, funding rates
Update NAV and peak NAV
Check period boundaries (3h) — settle PnL if needed
Evaluate signals across the symbol universe
Run risk checks against hard limits
Update circuit breaker level
Make entry/exit decisions with confirmation + sizing
Execute orders via DirectProvider or GuardianProvider
Check trailing stops (two-phase: breathe/lock)
Persist state + flush metrics

Risk Management

Hard Limits: Max drawdown, daily loss, position size, leverage, exposure, order frequency, data staleness
Circuit Breaker: GREEN (full trading) → YELLOW (50% sizing) → ORANGE (no new entries) → RED (flatten all + halt)
Trailing Stops: Two-phase system with profit tiers — breathe phase allows pullback, lock phase tightens the floor
State Reconstruction: On startup, critical state (NAV, circuit breaker, trailing stops, open positions) is rebuilt from the Orderly API — no dependence on local persistence

Deployment Modes

Mode	Flag	Storage	Best For
Standalone	(default)	SQLite	Servers, VPS, Docker
Ephemeral	`--memory`	In-memory	Starchild AI, serverless
Multi-vault	`-c config.yaml`	Either	Managing multiple vaults

In --memory mode, an AI-safe parameter schema is enforced for hot-reload requests (tighter bounds on leverage, sizing, fees).

Security

Key Protection: Ed25519 private key buffer zeroed after each signing operation; env vars scrubbed from process.env after startup
Log Sanitization: Keys, wallet addresses, and JWTs are automatically redacted from all log output
API Auth: Separate read (HEALTH_TOKEN) and write (ADMIN_TOKEN) bearer tokens
IP Allowlisting: ALLOWED_IPS restricts API access to specific addresses
Withdrawal Limits: Per-request cap, daily cap, cooldown between withdrawals
Rate Limiting: Flatten cooldown, auth brute-force detection
CORS: Configurable allowed origins

Environment Variables

Variable	Required	Description
`NETWORK`	Yes	`testnet` or `mainnet`
`ACCOUNT_ID`	Yes	Orderly account address
`ORDERLY_KEY_PUBLIC`	Yes	Ed25519 public key
`ORDERLY_KEY_PRIVATE`	Yes	Ed25519 private key
`VAULT_ID`	No	Default vault ID
`STRATEGY_PATH`	No	Path to strategy YAML
`LOG_LEVEL`	No	`debug`, `info`, `warn`, `error`
`DB_PATH`	No	SQLite database path (default: `./yieldclaw.db`)
`CYCLE_INTERVAL_SEC`	No	Loop interval (default: 30)
`HEALTH_PORT`	No	API server port (default: 8080)
`HEALTH_TOKEN`	No	Bearer token for read endpoints
`ADMIN_TOKEN`	No	Bearer token for write endpoints
`CORS_ORIGINS`	No	Comma-separated allowed origins
`ALLOWED_IPS`	No	Comma-separated allowed IPs
`MAX_WITHDRAW_USD`	No	Max single withdrawal (default: 10000)
`DAILY_WITHDRAW_LIMIT_USD`	No	Max daily withdrawals (default: 50000)
`WITHDRAW_COOLDOWN_SEC`	No	Seconds between withdrawals (default: 300)

Programmatic Usage

YieldClaw exports everything as a library:

import {
  ClawLoop,
  OrderlyClient,
  StrategyVaultClient,
  DirectProvider,
  VaultManager,
  MemoryStateStore,
  loadStrategy,
  loadConfig,
} from "yieldclaw";

const config = loadConfig();
const client = new OrderlyClient(config.network, tradingKey, config.accountId);
const svClient = new StrategyVaultClient(config.network, tradingKey, config.accountId);
const store = new MemoryStateStore();
await store.init();

const strategy = await loadStrategy("./strategies/my-strategy.yaml");
const provider = new DirectProvider(client);

const claw = new ClawLoop(client, svClient, provider, {
  vaultId: "my-vault",
  accountId: config.accountId,
  strategy,
  store,
});

claw.on("trade_executed", (event) => console.log(event));
claw.on("circuit_breaker_change", (event) => console.log(event));

await claw.start();

Development

npm install          # Install dependencies
npm run typecheck    # Type check without emitting
npm test             # Run tests
npm run build        # Build to dist/
npm run dev          # Run with tsx (development)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
skills/yieldclaw		skills/yieldclaw
src		src
strategies		strategies
test		test
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

YieldClaw

What It Does

Quick Start

Prerequisites

Install

Configure

Create a Vault

Register as Strategy Provider

Start Trading

Strategy Definition

Available Signal Types

CLI Reference

Core Commands

Vault Management (SP)

Depositor (User) Operations

API Endpoints

Trading (GET — requires HEALTH_TOKEN)

Control (POST — requires ADMIN_TOKEN)

Vault Management

Depositor Endpoints

Architecture

CLAW Loop Cycle (every 30s)

Risk Management

Deployment Modes

Security

Environment Variables

Programmatic Usage

Development

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Trading (GET — requires `HEALTH_TOKEN`)

Control (POST — requires `ADMIN_TOKEN`)

Packages