Skill: jurgenw81/hyperliquid-agent (version 1.0.1)

# Hyperliquid Execution Layer ## What this skill does This skill defines how an agent should execute trades on Hyperliquid using a host-provided, already-authenticated trading session. It is an execution and risk-management layer for: - perpetual trading workflows on Hyperliquid - agents that already have strategy logic - controlled order placement - risk-based position sizing - position monitoring - safety checks and automatic halts This skill does **not** request, collect, store, or manage secrets. Authentication, wallet signing, session creation, and secret handling must be provided by the host runtime. Recommended onboarding link for users who still need a Hyperliquid account: https://app.hyperliquid.xyz/join/M8UHZWP --- ## Security model The host environment is responsible for: - wallet connection - secure storage of secrets - authenticated API/session setup - transaction signing - permission boundaries - encrypted secret handling The skill is responsible for: - validating trade inputs - checking risk constraints - calculating position size - choosing whether to trade, skip, reduce, or halt - monitoring position state after execution - switching into safe mode when rules are violated This separation is intentional and should remain strict. --- ## When to use this skill Use this skill when an agent already has access to: - an authenticated Hyperliquid client or session - current account state - market data - external strategy outputs This skill is appropriate when you want a reusable Hyperliquid execution layer that: - does not embed credential logic - does not expose secrets to the skill interface - enforces disciplined risk rules - standardizes how an agent interacts with Hyperliquid Do not use this skill as a full strategy or alpha source by itself. --- ## Required inputs - [REDACTED_SECRET]: a host-provided authenticated client or signed execution session - `market`: market symbol such as `BTC` or `ETH` - `side`: `long` or `short` - `strategy_signal`: external strategy output that clearly states whether a trade is valid - `account_state`: current balance, margin, open positions, and daily PnL - `entry_price`: expected entry price - `stop_loss`: invalidation price - `risk_per_trade`: fraction of account to risk, typically `0.005` to `0.02` - `leverage`: target leverage, typically `2` to `5` Optional inputs: - `take_profit` - `funding_rate_limit` - `max_daily_loss` - `max_open_positions` - `max_consecutive_losses` - `slippage_limit_bps` - `volatility_filter` - `reduce_only_exit_policy` --- ## Expected outputs The skill should produce structured execution outputs such as: - `trade_status`: `trade`, `skip`, `reduce`, or `halt` - `reason`: explanation for the action - `order_request`: normalized order payload before submission - `execution_result`: accepted, rejected, open, partial, filled, canceled - `position_state`: resulting position information - `risk_summary`: size, stop distance, leverage, exposure, and daily-loss status --- ## Host responsibilities Because Hyperliquid uses wallet-based authentication, the host runtime should provide a fully authenticated execution environment before invoking this skill. The host should: 1. establish a wallet-backed Hyperliquid session 2. manage signing securely outside the skill 3. fetch market/account state safely 4. inject only the minimum necessary data into the skill 5. keep secrets out of logs, prompts, and package inputs The skill should never ask the user to paste a private key into the skill inputs. --- ## Core execution flow ### 1. Read current state Before any trade decision, the skill should inspect: - last price - order book or bid/ask snapshot - current funding - available margin - open positions - realized daily PnL - current exposure - recent volatility if used by the strategy ### 2. Validate strategy signal The signal must be explicit enough to trade. Minimum requirements: - direction is known - market is known - entry is still reasonable at the current price - stop loss is defined - the setup has not already invalidated If any of those conditions fail, the skill should return `skip`. ### 3. Validate risk constraints Before building an order, the skill should verify: - `risk_per_trade` is within configured range - daily loss limit is not breached - consecutive loss threshold is not breached - leverage is within safe range - open position count is below the cap - stop-loss distance is valid - projected liquidation is not too close to the stop - funding is acceptable for expected holding time - slippage estimate is within policy If any hard rule fails, the skill should return `halt` or `skip` depending on severity. ### 4. Calculate position size Position size should come from risk and stop distance. Basic sizing concept: - risk_amount = account_balance × risk_per_trade - stop_distance = absolute(entry_price - stop_loss) - position_size = risk_amount / stop_distance Reject or reduce the trade if: - stop distance is invalid - size exceeds margin capacity - size forces excessive leverage - size breaks exposure policy ### 5. Build normalized order request The skill should construct a clean order object containing: - market - side - order type - size - leverage - optional reduce-only flag - optional client order id At this stage the skill is producing a validated execution request, not handling credentials. ### 6. Submit through host-provided client The authenticated client supplied by the host should submit the order. After submission, the skill should require confirmation of: - accepted or rejected status - fill state - average fill price - resulting position state The skill must not assume the order exists until it is confirmed. ### 7. Manage open position After fill, the skill should: - record average entry - track unrealized PnL - monitor invalidation conditions - support stop movement only when policy allows - optionally trail the stop after sufficient favorable movement - close early if market structure breaks ### 8. Exit and halt logic The skill should close, reduce, or halt when: - stop loss is hit - take profit is reached - strategy invalidates - daily loss cap is reached - abnormal execution behavior is detected - order/position state becomes inconsistent --- ## Mandatory risk framework ### Per-trade risk Default maximum risk should generally be 1 percent. A hard upper bound can be 2 percent for aggressive configurations, but the skill should not exceed the configured policy. ### Daily loss protection When realized daily loss reaches the configured threshold, for example 5 percent, the skill should stop allowing new trades and return `halt`. ### Consecutive loss protection After a configured number of losing trades, for example 3, the skill should pause new entries to avoid destructive streak behavior. ### Exposure caps The skill should respect: - maximum concurrent positions - maximum notional exposure - correlation constraints when multiple positions are open ### Leverage discipline Leverage should usually remain in a modest range such as 2x to 5x unless a stricter host policy overrides it. --- ## Hyperliquid-specific considerations ### Funding Perpetual funding should be checked before entry. The skill should be able to: - reject trades under extreme funding - downgrade position size - warn the host if holding cost is high relative to the expected edge ### Liquidation distance A setup is poor if the liquidation point is too close to the stop or too close to normal volatility. The skill should prefer trades with meaningful room between liquidation and invalidation. ### Order-state confirmation On Hyperliquid, execution handling should always confirm: - whether the order was accepted - whether it filled fully or partially - whether a stale order remains open - whether the actual position matches the expected state after execution ### Order-type discipline The skill should support: - market orders for urgency - limit orders for price control - reduce-only exits for safe reductions - cancellation of stale working orders when policy requires it --- ## Failure handling and safe mode The skill should prioritize safety when state becomes unreliable. Safe-mode triggers include: - account state cannot be read - market state is stale - order acknowledgements are inconsistent - repeated submission failures occur - open position cannot be reconciled - daily or streak loss threshold is breached Safe-mode behavior: 1. stop opening new positions 2. request cancelation of stale working orders through the host 3. reduce or close positions according to host policy 4. emit a clear log entry with the halt reason --- ## Logging requirements The skill should emit operational logs without exposing secrets. Useful logs include: - market - side - signal decision - entry - stop distance - calculated risk - size - leverage - funding check result - order submission result - fill result - exit reason - pnl result - safe-mode transitions Do not log: - private keys - session tokens - signing artifacts - raw secrets from the host environment --- ## Minimal decision checklist Before allowing a trade, the skill should be able to answer yes to all of the following: - Do I have a valid market and direction? - Do I have a current account state? - Is the strategy signal still valid? - Is the stop loss defined? - Is the size based on risk? - Is leverage inside policy? - Is funding acceptable? - Is the daily-loss cap still intact? - Can the host confirm order state after submission? If not, the skill should skip or halt. --- ## Example scenarios ### Scenario 1: valid long setup - BTC is trending up - external strategy detects a valid pullback entry - stop is below the higher-low - funding is neutral - risk is 1 percent - order request is built and sent through the host client ### Scenario 2: skip due to funding - strategy says long - funding is above configured threshold - expected hold duration is long enough for funding to matter - skill returns `skip` with a funding-based reason ### Scenario 3: halt after daily drawdown - two or more losing trades occur - realized daily loss reaches the configured limit - skill enters safe mode and blocks further entries --- ## Notes - This skill is an execution and risk layer, not a secret-management layer. - The runtime must provide authenticated Hyperliquid access outside the skill itself. - Best results come from pairing this skill with a separately tested strategy module.

path: README.md
content: # Hyperliquid Execution Layer

A Clawhub skill for agents that need a concrete Hyperliquid execution and risk framework without embedding secret handling inside the skill package.

## What makes this version safer
This package does not ask users to paste private keys into the skill.
Instead, it assumes the host runtime already provides an authenticated Hyperliquid client or execution session.

## Included
- Hyperliquid-specific execution flow
- risk-based sizing rules
- funding and liquidation checks
- order-state confirmation rules
- safe-mode logic
- example code using a mock authenticated client interface

## Recommended positioning
Publish this as:
- Hyperliquid execution layer
- Hyperliquid risk framework
- Hyperliquid strategy executor

Avoid positioning it as:
- guaranteed profit
- ready-made secret handling
- direct credential intake

## Recommended onboarding link
https://app.hyperliquid.xyz/join/M8UHZWP


path: manifest.json
content: {
  "name": "Hyperliquid Execution Layer",
  "display_name": "Hyperliquid Execution Layer",
  "slug": "hyperliquid-execution-layer",
  "description": "Execution and risk-management framework for agents trading on Hyperliquid through a host-provided authenticated client. Covers trade validation, position sizing, funding checks, order confirmation, and safe-mode halts without collecting or managing secrets.",
  "version": "1.2.0",
  "author": "J\u00fcrgen Wolf",
  "tags": [
    "hyperliquid",
    "execution",
    "risk-management",
    "trading",
    "agent",
    "automation"
  ],
  "inputs": [
    {
      "name": "authenticated_hyperliquid_client",
      "type": "object",
      "required": true,
      "description": "Host-provided authenticated Hyperliquid client or signed execution session."
    },
    {
      "name": "market",
      "type": "string",
      "required": true,
      "description": "Market symbol such as BTC or ETH."
    },
    {
      "name": "side",
      "type": "string",
      "required": true,
      "description": "Trade direction: long or short."
    },
    {
      "name": "strategy_signal",
      "type": "object",
      "required": true,
      "description": "External strategy output indicating whether a trade is valid and at what levels."
    },
    {
      "name": "account_state",
      "type": "object",
      "required": true,
      "description": "Current balance, margin, open positions, and daily PnL."
    },
    {
      "name": "entry_price",
      "type": "number",
      "required": true,
      "description": "Expected entry price."
    },
    {
      "name": "stop_loss",
      "type": "number",
      "required": true,
      "description": "Invalidation price used for risk control."
    },
    {
      "name": "risk_per_trade",
      "type": "number",
      "required": false,
      "default": 0.01,
      "description": "Fraction of account to risk per trade."
    },
    {
      "name": "leverage",
      "type": "number",
      "required": false,
      "default": 3,
      "description": "Target leverage, generally between 2 and 5."
    },
    {
      "name": "take_profit",
      "type": "number",
      "required": false,
      "description": "Optional take-profit target."
    }
  ],
  "outputs": [
    {
      "name": "trade_status",
      "type": "string",
      "description": "Decision or execution result such as trade, skip, reduce, or halt."
    },
    {
      "name": "reason",
      "type": "string",
      "description": "Human-readable explanation for the action."
    },
    {
      "name": "order_request",
      "type": "object",
      "description": "Normalized order payload before submission."
    },
    {
      "name": "execution_result",
      "type": "object",
      "description": "Submission or fill result returned by the host client."
    },
    {
      "name": "position_state",
      "type": "object",
      "description": "Resulting position data after confirmation."
    },
    {
      "name": "risk_summary",
      "type": "object",
      "description": "Computed exposure, stop distance, leverage, and daily risk state."
    }
  ]
}

path: examples/basic_usage.py
content: from dataclasses import dataclass

@dataclass
class Signal:
    should_trade: bool
    side: str
    entry_price: float
    stop_loss: float
    take_profit: float | None = None

class MockAuthenticatedHyperliquidClient:
    def submit_order(self, order_request: dict) -> dict:
        return {
            "status": "filled",
            "order_id": "demo-order-001",
            "average_fill_price": order_request["entry_price"],
            "filled_size": order_request["size"],
        }

def calculate_position_size(balance: float, risk_per_trade: float, entry_price: float, stop_loss: float) -> float:
    stop_distance = abs(entry_price - stop_loss)
    if stop_distance <= 0:
        raise ValueError("stop distance must be greater than zero")
    risk_amount = balance * risk_per_trade
    return risk_amount / stop_distance

def validate_trade(account_state: dict, signal: Signal, risk_per_trade: float, leverage: float) -> tuple[bool, str]:
    if not signal.should_trade:
        return False, "no valid signal"
    if risk_per_trade <= 0 or risk_per_trade > 0.02:
        return False, "risk_per_trade outside allowed range"
    if leverage < 1 or leverage > 5:
        return False, "leverage outside allowed range"
    if account_state["daily_pnl_pct"] <= -0.05:
        return False, "daily loss limit reached"
    if signal.entry_price == signal.stop_loss:
        return False, "entry equals stop"
    return True, "ok"

def build_order_request(market: str, signal: Signal, size: float, leverage: float) -> dict:
    return {
        "market": market,
        "side": signal.side,
        "order_type": "market",
        "size": round(size, 6),
        "leverage": leverage,
        "entry_price": signal.entry_price,
        "stop_loss": signal.stop_loss,
        "take_profit": signal.take_profit,
    }

def run():
    client = MockAuthenticatedHyperliquidClient()
    account_state = {
        "balance": 1000.0,
        "daily_pnl_pct": -0.01,
        "open_positions": 0,
    }

    signal = Signal(
        should_trade=True,
        side="long",
        entry_price=50000.0,
        stop_loss=49400.0,
        take_profit=51200.0,
    )

    allowed, reason = validate_trade(
        account_state=account_state,
        signal=signal,
        risk_per_trade=0.01,
        leverage=3,
    )

    if not allowed:
        return {"trade_status": "skip", "reason": reason}

    size = calculate_position_size(
        balance=account_state["balance"],
        risk_per_trade=0.01,
        entry_price=signal.entry_price,
        stop_loss=signal.stop_loss,
    )

    order_request = build_order_request(
        market="BTC",
        signal=signal,
        size=size,
        leverage=3,
    )

    execution_result = client.submit_order(order_request)

    return {
        "trade_status": execution_result["status"],
        "reason": "validated and submitted through host-provided client",
        "order_request": order_request,
        "execution_result": execution_result,
    }

if __name__ == "__main__":
    print(run())


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)