--- name: graphadvocate.com description: graphadvocate.com provides trader analytics and risk scoring for two prediction/derivatives platforms: Hyperliquid perpetuals and Polymarket prediction markets. It returns derived metrics—skill scores, classifications, PnL breakdowns, liquidation rates, and funding burn—computed from historical on-chain data. All endpoints are read-only analytics snapshots; no execution, streaming, or order book data is available. host: graphadvocate.com --- # graphadvocate.com graphadvocate.com serves agents and analysts who need to evaluate the quality, risk, and composition of traders or vaults on Hyperliquid and Polymarket. It covers individual wallet due diligence, market-level holder screening, and vault evaluation. Its distinguishing feature is a consistent scoring framework (skill score, sharp/neutral/retail classification, Sharpe-like ratio) applied uniformly across both platforms, enabling comparable quality assessments across different market types. ## When to use this host Use graphadvocate.com when an agent needs historical skill scoring, risk classification, or PnL analytics for Hyperliquid perpetuals wallets/vaults or Polymarket prediction market wallets. It is the right choice for copy-trading eligibility checks, vault due diligence, and smart-money identification on those two platforms specifically. Do not use it for: real-time price feeds, order book data, or trade execution on any platform; spot trading analysis on Hyperliquid or any non-Hyperliquid DEX; prediction market wallets outside Polymarket; or streaming position updates. For live Hyperliquid market data, use a Hyperliquid-native API or a general DeFi data provider. For Polymarket live pricing or order flow, use Polymarket's own API or a dedicated prediction market data feed. ## Capabilities ### Hyperliquid Trader Evaluation Assess the quality and risk profile of individual Hyperliquid perpetuals wallets, returning composite skill scores, liquidation history, funding burn, and counterparty risk flags. - **`score-hyperliquid-trader`** — Returns a composite skill score (0–100) for a Hyperliquid perpetuals trader, including classification, liquidation rate, funding burn, profit factor, PnL, and volume metrics. - **`fetch-hyperliquid-risk`** — Returns counterparty risk metrics for a Hyperliquid account including liquidation rate, funding burn, skill score, and recent outflow flag. ### Hyperliquid Market Screening Identify and classify the highest-volume traders on a specific Hyperliquid perpetuals market, enabling bulk discovery of sharp vs. retail participants. - **`screen-hyperliquid-traders`** — Returns the top N traders for a given Hyperliquid coin, each ranked by volume and scored as sharp, neutral, or retail based on realized PnL and skill metrics. ### Hyperliquid Vault Evaluation Score and classify a Hyperliquid vault by leader skill, depositor concentration, redemption pressure, and lifetime USDC flow history. - **`fetch-hyperliquid-vault-data`** — Returns a scored evaluation of a Hyperliquid vault including quality score, leader skill, redemption pressure, depositor concentration, lifetime USDC flows, and top depositor breakdown. ### Polymarket Trader Analytics Retrieve full or quick PnL dossiers for Polymarket wallets, including win rate, skill score, open positions, and realized/unrealized PnL across markets. - **`fetch-polymarket-pnl`** — Returns a full Polymarket trader dossier for a given wallet address, including aggregate scores and per-market realized/unrealized PnL with open positions. - **`fetch-polymarket-pnl-quick`** — Returns a fast Polymarket wallet skill snapshot including realized PnL, unrealized PnL, win rate, skill score, and open position count. ### Polymarket Market Holder Screening Screen the top holders of a specific Polymarket market condition, classifying them as sharp, neutral, or retail and flagging ghost-fill risk and smart-money concentration. - **`screen-polymarket-holders`** — Returns ranked top holders of a Polymarket market with per-wallet skill score, classification (sharp/neutral/retail), Sharpe-like ratio, win rate, and ghost-fill risk. ## Workflows ### Hyperliquid Wallet Due Diligence *Use when an agent needs a comprehensive risk and quality assessment of a single Hyperliquid wallet before copy-trading or counterparty exposure decisions.* 1. **`fetch-hyperliquid-risk`** — Retrieve counterparty risk metrics including liquidation rate, funding burn, and recent outflow flag to establish a risk baseline. 2. **`score-hyperliquid-trader`** — Retrieve the full composite skill score, profit factor, PnL-to-volume ratio, and classification to assess overall trading quality beyond raw risk. ### Hyperliquid Market-to-Wallet Pipeline *Use when an agent needs to discover top traders on a Hyperliquid market and then drill into the risk profile of specific wallets of interest.* 1. **`screen-hyperliquid-traders`** — Screen the top N traders on a given Hyperliquid coin to identify high-volume sharp candidates. 2. **`fetch-hyperliquid-risk`** — For selected wallets from the screen, retrieve counterparty risk metrics to filter out high-liquidation or suspicious-outflow addresses. 3. **`score-hyperliquid-trader`** — Retrieve the full skill score for shortlisted wallets to confirm quality before copy-trading or further analysis. ### Polymarket Smart Money Assessment *Use when an agent needs to evaluate a Polymarket market's holder composition and then verify the track record of specific wallets identified as sharp.* 1. **`screen-polymarket-holders`** — Screen top holders of a Polymarket condition to identify sharp-classified wallets and assess overall market composition and ghost-fill risk. 2. **`fetch-polymarket-pnl-quick`** — Run a quick skill snapshot on wallets flagged as sharp to confirm their historical win rate and PnL before acting on their positioning. 3. **`fetch-polymarket-pnl`** — Optionally retrieve the full PnL dossier for the most relevant wallets, including per-market open positions and detailed scoring. ## Skill reference ### `score-hyperliquid-trader` **Hyperliquid Trader Score** — Returns a composite skill score (0–100) for a Hyperliquid perpetuals trader, including classification, liquidation rate, funding burn, profit factor, PnL, and volume metrics. *Use when:* Use when an agent needs to evaluate the trading quality or risk profile of a Hyperliquid perps wallet address, such as for due diligence, leaderboard ranking, or copy-trading eligibility checks. *Not for:* Do not use for spot trading analysis or non-Hyperliquid DEX performance; use a general DeFi analytics API instead. Not suitable for real-time streaming price or position data. **Inputs:** - `user` (string, required) — Ethereum wallet address of the Hyperliquid perpetuals trader to score. **Returns:** Returns a JSON object with skill_score (0–100), classification, sharpe_like, pnl_bps_of_volume, liquidation stats, funding burn, profit_factor, trade count, coins traded, realized PnL, total volume, and fees in USDC. **Example:** `{"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"}` --- ### `screen-hyperliquid-traders` **Hyperliquid Trader Screen** — Returns the top N traders for a given Hyperliquid coin, each ranked by volume and scored as sharp, neutral, or retail based on realized PnL and skill metrics. *Use when:* Use when an agent needs to identify and classify the highest-volume traders on a specific Hyperliquid perpetuals market, including their realized PnL, skill score, liquidation count, and trade sample size. *Not for:* Do not use for streaming live position data or order book snapshots; this is a batch screening result, not a real-time feed. **Inputs:** - `coin` (string, required) — Hyperliquid coin ticker symbol to screen traders for. - `n` (integer, required) — Number of top traders to return, ranked by coin volume in USDC. **Returns:** Returns coin, aggregate counts by classification (sharp/neutral/retail), and an array of up to N ranked traders each with wallet address, USDC volume, realized PnL, skill score, classification, liquidation count, and trade sample size. **Example:** `{"coin": "BTC", "n": 10}` --- ### `fetch-hyperliquid-vault-data` **Hyperliquid Vault Data** — Returns a scored evaluation of a Hyperliquid vault including quality score, leader skill, redemption pressure, depositor concentration, lifetime USDC flows, and top depositor breakdown. *Use when:* Use when an agent needs to evaluate a specific Hyperliquid vault by address, including its risk classification, depositor concentration, redemption pressure, lifetime deposit/withdrawal history, and top depositor activity. *Not for:* Do not use for live price feeds, trading execution, or querying vaults across multiple protocols; this endpoint is specific to Hyperliquid vault addresses only. **Inputs:** - `vault` (string, required) — Hyperliquid vault contract address to evaluate. **Returns:** Returns a vault dossier with quality score 54.9, classification neutral, 10,285 depositors, lifetime deposits 501.5M USDC, withdrawals 435.1M USDC, redemption pressure 0.867, and a top-5 depositor breakdown. **Example:** `{"vault": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"}` --- ### `fetch-hyperliquid-risk` **Hyperliquid Risk Check** — Returns counterparty risk metrics for a Hyperliquid account including liquidation rate, funding burn, skill score, and recent outflow flag. *Use when:* Use when an agent needs to assess the risk profile of a Hyperliquid wallet address, including whether it has been liquidated, how much funding it pays relative to volume, and whether it has suspicious recent outflows. *Not for:* Do not use for real-time price feeds or open position data; this returns historical and derived risk metrics only, not live order book or position state. **Inputs:** - `user` (string, required) — Hyperliquid account address (EVM-style hex) to evaluate for counterparty risk. **Returns:** Returns a structured risk snapshot with risk_level, liquidation_count, liquidation_rate_bps, funding_paid_per_volume_bps, skill_score, classification, recent outflow flag, sample size, methodology descriptions, and a generated_at timestamp. **Example:** `{"user": "0xecb63caa47c7c4e77f60f1ce858cf28dc2b82b00"}` --- ### `screen-polymarket-holders` **Polymarket Market Holder Screen** — Returns ranked top holders of a Polymarket market with per-wallet skill score, classification (sharp/neutral/retail), Sharpe-like ratio, win rate, and ghost-fill risk. *Use when:* Use when an agent needs to evaluate the composition of a Polymarket market's top holders — e.g., to assess whether smart money is concentrated on one side, gauge ghost-fill risk, or identify sharp vs. retail positioning before placing or analyzing a bet. *Not for:* Do not use for real-time price feeds or order book data; this is a holder-level analytics snapshot, not a live market quote or liquidity depth tool. **Inputs:** - `condition_id` (string, required) — Polymarket condition ID (hex string) identifying the market to screen. - `n` (integer) — Number of top holders to return and analyze. **Returns:** Returns market metadata, aggregate sharp/neutral/retail counts, ghost-fill risk breakdown, and a ranked array of up to N holders each with wallet address, USDC position size, side, skill score, Sharpe-like ratio, win rate, and ghost-fill risk level. **Example:** `{"condition_id": "0x6331a779482df72d904c3c1e12b6409ff836bc06f8c97945cba9b25ada2c605c", "n": 10}` --- ### `fetch-polymarket-pnl` **Polymarket PnL Tracker** — Returns a full Polymarket trader dossier for a given wallet address, including aggregate scores and per-market realized/unrealized PnL with open positions. *Use when:* Use when an agent needs profit-and-loss analytics for a Polymarket trader wallet, including win rate, Sharpe-like score, classification, and a breakdown of open positions with buy cost, current price, and PnL per market. *Not for:* Do not use for real-time price feeds or order execution on Polymarket; this is a read-only historical and current-position analytics endpoint. **Inputs:** - `address` (string, required) — Polymarket trader wallet address to retrieve PnL data for. - `wallet` (string) — Alternative wallet address field accepted by the endpoint. - `timeframe` (string) — Time window for the analysis (e.g. '7d'). **Returns:** Returns a wallet dossier with aggregate scores (skill_score, win_rate, sharpe_like, realized/unrealized/total PnL in USDC) and an array of open position records with per-market PnL breakdown. **Example:** `{"address": "0x7e571E959cC7C75Ccdd2eAC24f8775ea2eAa2F09", "wallet": "0x38e598961dd0456a7fb2e758bd433d3e59fb8a4a", "timeframe": "7d"}` --- ### `fetch-polymarket-pnl-quick` **Polymarket PnL Quick** — Returns a fast Polymarket wallet skill snapshot including realized PnL, unrealized PnL, win rate, skill score, and open position count. *Use when:* Use when an agent needs a quick profit-and-loss summary for a Polymarket wallet address, including skill classification, Sharpe-like ratio, and position-level PnL figures without waiting for a full analytics pipeline. *Not for:* Do not use for non-Polymarket prediction market wallets or for streaming live price feeds; this is a single-shot snapshot, not a real-time feed. **Inputs:** - `wallet` (string, required) — Ethereum wallet address to analyze on Polymarket. - `chain` (string) — Blockchain network identifier (e.g. 'base'). - `address` (string) — Contract or market address context for the query. - `timeframe` (string) — Lookback window for the PnL snapshot (e.g. '7d', '30d'). - `quoteToken` (string) — ERC-20 token address used as the quote currency for PnL calculations. - `positionsToken` (string) — Token address representing the positions to evaluate. **Returns:** Returns a wallet PnL snapshot with skill_score, classification, sharpe_like, win_rate, sample sizes, realized_pnl_usdc, unrealized_pnl_usdc, total_pnl_usdc, open_positions_count, and a generated_at timestamp. **Example:** `{"wallet":"0x38e598961dd0456a7fb2e758bd433d3e59fb8a4a","chain":"base","address":"0x7e571E959cC7C75Ccdd2eAC24f8775ea2eAa2F09","timeframe":"7d","quoteToken":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","positionsToken":"EfPoo4wWgxKVToit7yX5VtXXBrhao4G8L7vrbKy6pump"}` ---