{
  "schema": "tradecat_auto.agent_soft_endpoint_policy.v1",
  "schema_version": "1.0.0",
  "purpose": "Soft-layer endpoint catalog extracted from the bundled Binance USDⓈ-M skill/API snapshots for Agent/Hermes market-context prompts; hard safety gates remain in code.",
  "source_snapshots": [
    {
      "path": "resources/agent_market_context/binance/upstream/binance-skills-hub-main/skills/binance/derivatives-trading-usds-futures/SKILL.md",
      "role": "upstream skill endpoint inventory"
    },
    {
      "path": "resources/agent_market_context/binance/api-docs/币安全部api.md",
      "role": "archived Chinese API endpoint and parameter summary"
    },
    {
      "path": "resources/agent_market_context/binance/api-docs/币安API完整文档汇总.md",
      "role": "archived Chinese API full-document summary"
    }
  ],
  "allowed_market_context_families": [
    {
      "family": "klines",
      "endpoint": "/fapi/v1/klines",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch recent candles for price path, volatility, volume expansion, and event-time alignment."
    },
    {
      "family": "order_book_depth",
      "endpoint": "/fapi/v1/depth",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch public order-book depth for spread, imbalance, and shallow-liquidity warnings."
    },
    {
      "family": "book_ticker",
      "endpoint": "/fapi/v1/ticker/bookTicker",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch best bid/ask for execution-price sanity checks in paper/watch reports."
    },
    {
      "family": "24h_ticker",
      "endpoint": "/fapi/v1/ticker/24hr",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch 24h price/volume context around a sheet anomaly."
    },
    {
      "family": "funding_rate",
      "endpoint": "/fapi/v1/fundingRate",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch funding history to flag crowded or expensive perp positioning."
    },
    {
      "family": "premium_index",
      "endpoint": "/fapi/v1/premiumIndex",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch mark/index price and current funding fields for basis/funding context."
    },
    {
      "family": "open_interest",
      "endpoint": "/fapi/v1/openInterest",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch current open interest for participation and squeeze-risk context."
    },
    {
      "family": "open_interest_history",
      "endpoint": "/futures/data/openInterestHist",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch historical open interest to compare OI change with price/volume change."
    },
    {
      "family": "long_short_ratios",
      "endpoints": [
        "/futures/data/topLongShortAccountRatio",
        "/futures/data/topLongShortPositionRatio",
        "/futures/data/globalLongShortAccountRatio"
      ],
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch public long/short ratio series for crowding context."
    },
    {
      "family": "taker_buy_sell_volume",
      "endpoint": "/futures/data/takerlongshortRatio",
      "method": "GET",
      "authentication_required": false,
      "agent_use": "Fetch taker buy/sell volume ratio to describe aggressive flow."
    }
  ],
  "hard_forbidden_endpoint_categories": [
    {
      "category": "real_order_lifecycle",
      "examples": [
        "/fapi/v1/order",
        "/fapi/v1/openOrders",
        "/fapi/v1/allOrders",
        "/fapi/v1/allOpenOrders",
        "/fapi/v1/batchOrders",
        "/fapi/v1/algoOrder"
      ],
      "reason": "TradeCat public never places, cancels, modifies, queries, or imports real exchange orders."
    },
    {
      "category": "real_account_state",
      "examples": [
        "/fapi/v2/account",
        "/fapi/v3/account",
        "/fapi/v2/balance",
        "/fapi/v3/balance",
        "/fapi/v2/positionRisk",
        "/fapi/v3/positionRisk",
        "/fapi/v1/userTrades"
      ],
      "reason": "Account, balance, position, and real fill state must come only from local paper ledger state in this repo."
    },
    {
      "category": "margin_or_leverage_mutation",
      "examples": [
        "/fapi/v1/leverage",
        "/fapi/v1/marginType",
        "/fapi/v1/positionSide/dual",
        "/fapi/v1/multiAssetsMargin"
      ],
      "reason": "Leverage/margin/account-mode changes are signed trading actions and are outside public/read-only + paper/watch."
    }
  ],
  "hard_forbidden_state_keys": [
    "account_state",
    "account_info",
    "balance",
    "balances",
    "open_orders",
    "all_orders",
    "order_history",
    "exchange_order_id",
    "client_order_id",
    "position_risk",
    "position_amt",
    "user_trades",
    "real_orders"
  ]
}