# SmartPerps Coin Bias — Hyperliquid Perpetuals Sentiment

> SmartPerps Coin Bias — Hyperliquid Perpetuals Sentiment is a paid API for AI agents from api.youraitools.co, paid per call via x402, $0.02/call, status unknown (last checked 2026-10-23).

Returns the directional bias (long/short), confidence, top positions, and liquidation clusters for a specific Hyperliquid perpetual futures ticker based on a tracked cohort of top traders

## Facts

- Endpoint: GET https://api.youraitools.co/smartperps/v1/coin?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-23
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/smartperps-coin-bias-hyperliquid-perpetuals-sentiment-eda576c8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_ng_1pFcQMmwW9he38YP7E

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability smartperps-coin-bias-hyperliquid-perpetuals-sentiment-eda576c8
```

Example prompt: What's the current SmartPerps bias for ETH on Hyperliquid — are the top traders net long or short, and how confident is the signal?

## When to prefer this

Use this endpoint when you need real-time directional sentiment and position data for a specific Hyperliquid perpetual futures market sourced from a tracked cohort of top-performing traders. It is distinctly useful for on-chain smart-money analysis — not just open interest from exchange APIs — because it surfaces individual top-trader positions, 30-day PnL rankings, leverage, and liquidation proximity. Prefer it over generic exchange APIs when you want cohort-level behavioral intelligence rather than raw order book or funding rate data.

## Known failure modes

- Invalid or unrecognized ticker symbol returns an error or empty result
- Symbol not traded on Hyperliquid perps market returns no data
- Stale snapshot if cohort refresh is delayed (snapshot_age_s will be elevated)
- sources_failed array may indicate partial data if some data sources were unavailable
- Payment failure via x402 if USDC balance is insufficient (HTTP 402)
- Rate limiting if too many requests in a short window

## How this service works

Smart money tracker API (Hyperliquid). Full smart-money positioning for one Hyperliquid perp from the top-120 30-day-PnL cohort: lite plus 1h/4h/24h flows, average entry per side vs mark, average leverage, uPnL per side, concentration, liquidation price bands by distance from mark (count and notional per band, never per account) and the 10 largest cohort positions (truncated addresses, no liquidation price). Fail-closed. Not financial advice. Past performance does not guarantee future results.

## Output

Returns a JSON object containing: directional bias label (e.g. strong_short), confidence level (high/medium/low), a bias_note explaining the reading, current mark price, average leverage of the cohort, counts of long and short traders, long/short/net notional USD, top individual positions with address, side, size, entry price, leverage, unrealized PnL, 30-day PnL, and liquidation distance, plus liquidation cluster breakdowns by proximity bucket. Also includes cohort metadata (size, coverage, refresh time) and snapshot age.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "symbol"
     ],
     "properties": {
      "symbol": {
       "type": "string",
       "description": "Hyperliquid perp ticker, e.g. BTC, ETH, SOL, HYPE, kPEPE (BTC-PERP, ETH-USD, SOLUSDT accepted)"
      }
     },
     "description": "Search intents: smart money positioning, hyperliquid top traders, whale flows, liquidation levels, trader leverage, smart money entries"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "bias": "strong_short",
  "tier": "coin",
  "flows": {
   "1h": null,
   "4h": null,
   "24h": null
  },
  "cohort": {
   "size": 120,
   "covered": 120,
   "coverage_pct": 100,
   "cohort_refreshed_at": "2026-10-23T01:08:26.080Z"
  },
  "symbol": "ETH",
  "bias_note": "Most of the cohort's notional and most cohort traders in this coin are short.",
  "checked_at": "2026-10-23T01:08:30.196Z",
  "confidence": "high",
  "disclaimer": "Not financial advice. Past performance does not guarantee future results. Descriptive statistics of public Hyperliquid positions at snapshot time; past PnL of the cohort says nothing about future results and positions can change at any moment. SmartPerps never trades, holds funds or keys.",
  "mark_price": 2389,
  "snapshot_at": "2026-10-23T01:08:26.080Z",
  "avg_leverage": 12.84,
  "traders_long": 10,
  "top_positions": [
   {
    "side": "short",
    "size": 106464.1028,
    "margin": "cross",
    "address": "0x5b5d…c060",
    "leverage": 5,
    "entry_price": 2322.73,
    "notional_usd": 254342742,
    "trader_30d_pnl_usd": 114316598,
    "unrealized_pnl_usd": -7054831,
    "cohort_rank_30d_pnl": 1
   },
   {
    "side": "short",
    "size": 66302.7619,
    "margin": "cross",
    "address": "0xb83d…6e36",
    "leverage": 5,
    "entry_price": 2375.32,
    "notional_usd": 158397298,
    "trader_30d_pnl_usd": 102801123,
    "unrealized_pnl_usd": -906592,
    "cohort_rank_30d_pnl": 2
   }
  ],
  "traders_short": 40,
  "avg_entry_long": 2454.489627,
  "snapshot_age_s": 4,
  "sources_failed": [],
  "avg_entry_short": 2381.656074,
  "net_notional_usd": -755197408,
  "long_notional_usd": 62204218,
  "concentration_note": null,
  "short_notional_usd": 817401626,
  "liquidation_clusters": {
   "longs": [
    {
     "price_to": 2389,
     "positions": 0,
     "price_from": 2341,
     "within_pct": "0-2",
     "notional_usd": 0
    },
    {
     "price_to": 2341,
     "positions": 0,
     "price_from": 2270,
     "within_pct": "2-5",
     "notional_usd": 0
    },
    {
     "price_to": 2270,
     "positions": 0,
     "price_from": 2150,
     "within_pct": "5-10",
     "notional_usd": 0
    }
   ],
   "shorts": [
    {
     "price_to": 2437,
     "positions": 0,
     "price_from": 2389,
     "within_pct": "0-2",
     "notional_usd": 0
    },
    {
     "price_to": 2508,
     "positions": 0,
     "price_from": 2437,
     "within_pct": "2-5",
     "notional_usd": 0
    },
    {
     "price_to": 2628,
    
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/smartperps-coin-bias-hyperliquid-perpetuals-sentiment-eda576c8/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.youraitools.co](https://www.zero.xyz/host/api.youraitools.co/llms.txt)