cryptodataapi-com Hyperliquid Traders API

openapi: 3.2.0
info:
  title: Crypto Data Hyperliquid Traders API
  description: 'Real-time crypto market intelligence API. Built for AI agents: gasless USDC payments via x402 protocol, one-call onboarding, and 180+ endpoints for prices, derivatives, funding, and sentiment.'
  version: '2026-10-28'
servers:
- url: https://cryptodataapi.com
tags:
- name: Hyperliquid Traders
  description: Top-trader leaderboard, wallet positions/signals/trades, watchlists, and copy signals.
paths:
  /api/v1/hyperliquid/top-traders:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Top Traders
      description: Scored leaderboard of top traders filtered by performance criteria.
      operationId: get_top_traders_api_v1_hyperliquid_top_traders_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLTopTradersResponse'
      security:
      - APIKeyHeader: []
  /api/v1/hyperliquid/wallet-positions:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Wallet Positions
      description: Current positions for tracked wallets. For non-tracked addresses, queries Hyperliquid on-demand.
      operationId: get_wallet_positions_api_v1_hyperliquid_wallet_positions_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: query
        required: false
        schema:
          description: Filter by wallet address (0x...)
          title: Address
          type:
          - string
          - 'null'
        description: Filter by wallet address (0x...)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWalletPositionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/wallet-signals:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Wallet Signals
      description: 'Position change signals: entries, exits, size increases/decreases.'
      operationId: get_wallet_signals_api_v1_hyperliquid_wallet_signals_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: minutes
        in: query
        required: false
        schema:
          type: integer
          maximum: 1440
          minimum: 1
          description: Look-back window in minutes
          default: 10
          title: Minutes
        description: Look-back window in minutes
      - name: address
        in: query
        required: false
        schema:
          description: Filter by wallet address (0x...). Comma-separated for multiple.
          title: Address
          type:
          - string
          - 'null'
        description: Filter by wallet address (0x...). Comma-separated for multiple.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWalletSignalsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/trader-profiles:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Trader Profiles
      description: Trade profiles with win rate, PnL, classification, and edges.
      operationId: get_trader_profiles_api_v1_hyperliquid_trader_profiles_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: query
        required: false
        schema:
          description: Filter by wallet address (0x...)
          title: Address
          type:
          - string
          - 'null'
        description: Filter by wallet address (0x...)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLTraderProfilesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/trader-profiles/refresh:
    post:
      tags:
      - Hyperliquid Traders
      summary: Refresh Trader Profiles
      description: 'Force a synchronous refresh of trade profiles for all tracked wallets.


        Pro Plus tier — expensive (~15-30s, sequential Hyperliquid calls). Use after

        a deploy or when cached profiles look stale; the daily 19:00 UTC scheduled

        refresh covers normal operation.'
      operationId: refresh_trader_profiles_api_v1_hyperliquid_trader_profiles_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /api/v1/hyperliquid/leaderboard/refresh:
    post:
      tags:
      - Hyperliquid Traders
      summary: Refresh Leaderboard
      description: 'Force a synchronous refresh of the Hyperliquid leaderboard cache.


        Pro Plus tier — fetches a ~28 MB payload and takes ~25-30s. Use when

        /copy-signals or /wallets/search return 0 results and you suspect the

        in-memory leaderboard is empty (e.g. a startup fetch timed out). The

        2-min position refresh job will also auto-recover an empty leaderboard;

        this endpoint is for forcing it sooner.'
      operationId: refresh_leaderboard_api_v1_hyperliquid_leaderboard_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /api/v1/hyperliquid/wallets/search:
    get:
      tags:
      - Hyperliquid Traders
      summary: Search Wallets
      description: 'Search the cached top-leaderboard pool for wallets matching arbitrary gates.


        Read-only — does not modify the watchlist. Pool is the same ~50-wallet set

        that auto-watchlist evaluation considers. Refreshed daily at 19:00 UTC.'
      operationId: search_wallets_api_v1_hyperliquid_wallets_search_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: min_score
        in: query
        required: false
        schema:
          type: number
          maximum: 100
          minimum: 0
          description: Minimum top-trader score
          default: 0
          title: Min Score
        description: Minimum top-trader score
      - name: min_win_rate
        in: query
        required: false
        schema:
          description: Minimum 30d win rate (0-1)
          title: Min Win Rate
          type:
          - number
          - 'null'
          maximum: 1
          minimum: 0
        description: Minimum 30d win rate (0-1)
      - name: min_profit_factor
        in: query
        required: false
        schema:
          description: Minimum profit factor
          title: Min Profit Factor
          type:
          - number
          - 'null'
          minimum: 0
        description: Minimum profit factor
      - name: min_trades_30d
        in: query
        required: false
        schema:
          description: Minimum trades in 30d. Defaults to 30 to filter tiny-sample wallets. Pass 0 explicitly to disable.
          title: Min Trades 30D
          type:
          - integer
          - 'null'
          minimum: 0
        description: Minimum trades in 30d. Defaults to 30 to filter tiny-sample wallets. Pass 0 explicitly to disable.
      - name: min_avg_duration_hours
        in: query
        required: false
        schema:
          description: Min avg trade duration (hours)
          title: Min Avg Duration Hours
          type:
          - number
          - 'null'
          minimum: 0
        description: Min avg trade duration (hours)
      - name: exclude_types
        in: query
        required: false
        schema:
          description: Comma-separated trader types to exclude, e.g. 'hft,scalper'
          title: Exclude Types
          type:
          - string
          - 'null'
        description: Comma-separated trader types to exclude, e.g. 'hft,scalper'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: Max wallets to return
          default: 50
          title: Limit
        description: Max wallets to return
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWalletSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/watchlist:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Watchlist
      description: List all watchlisted wallet addresses.
      operationId: get_watchlist_api_v1_hyperliquid_watchlist_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWatchlistResponse'
      security:
      - APIKeyHeader: []
    post:
      tags:
      - Hyperliquid Traders
      summary: Add To Watchlist
      description: 'Add wallet addresses to the watchlist. Automatically starts tracking for signals.


        The watchlist is a shared, collector-wide poll set, so mutations are gated to

        Pro / Pro Plus — a free key must not be able to inflate or alter the set that

        drives every consumer''s wallet signals.'
      operationId: add_to_watchlist_api_v1_hyperliquid_watchlist_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistAddDetailedRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWatchlistResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
    delete:
      tags:
      - Hyperliquid Traders
      summary: Remove From Watchlist
      description: Remove wallet addresses from the watchlist.
      operationId: remove_from_watchlist_api_v1_hyperliquid_watchlist_delete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistRemoveRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWatchlistResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/hyperliquid/watchlist/auto:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Auto Watchlist
      description: Get current auto-managed watchlist configuration and status.
      operationId: get_auto_watchlist_api_v1_hyperliquid_watchlist_auto_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLAutoWatchlistResponse'
      security:
      - APIKeyHeader: []
    post:
      tags:
      - Hyperliquid Traders
      summary: Create Auto Watchlist
      description: Auto-populate watchlist from top traders based on configurable criteria.
      operationId: create_auto_watchlist_api_v1_hyperliquid_watchlist_auto_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoWatchlistRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLAutoWatchlistResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
    delete:
      tags:
      - Hyperliquid Traders
      summary: Delete Auto Watchlist
      description: Disable auto-management and remove all auto-managed entries.
      operationId: delete_auto_watchlist_api_v1_hyperliquid_watchlist_auto_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLAutoWatchlistResponse'
      security:
      - APIKeyHeader: []
  /api/v1/hyperliquid/copy-signals:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Copy Signals
      description: 'Top traders with their recent signals in a single response.


        Replaces the 3-step workflow (top-traders → watchlist → signals) with one call.

        Only returns traders that have signals in the given time window.


        Profile filters (min_win_rate, min_profit_factor, min_trades_30d,

        min_avg_duration_hours, exclude_types) are optional and only applied when

        passed — preserves backward compatibility. Recommended: pass

        min_trades_30d=30 to drop tiny-sample wallets.'
      operationId: get_copy_signals_api_v1_hyperliquid_copy_signals_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: min_score
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 0
          description: Minimum trader score
          default: 80
          title: Min Score
        description: Minimum trader score
      - name: minutes
        in: query
        required: false
        schema:
          type: integer
          maximum: 1440
          minimum: 1
          description: Signal look-back window in minutes
          default: 60
          title: Minutes
        description: Signal look-back window in minutes
      - name: min_win_rate
        in: query
        required: false
        schema:
          description: Minimum 30d win rate (0-1)
          title: Min Win Rate
          type:
          - number
          - 'null'
          maximum: 1
          minimum: 0
        description: Minimum 30d win rate (0-1)
      - name: min_profit_factor
        in: query
        required: false
        schema:
          description: Minimum profit factor
          title: Min Profit Factor
          type:
          - number
          - 'null'
          minimum: 0
        description: Minimum profit factor
      - name: min_trades_30d
        in: query
        required: false
        schema:
          description: Minimum trades in 30d. Pass 30+ to filter tiny-sample wallets (e.g. '100% WR over 2 trades'). Not auto-defaulted here for backward compatibility.
          title: Min Trades 30D
          type:
          - integer
          - 'null'
          minimum: 0
        description: Minimum trades in 30d. Pass 30+ to filter tiny-sample wallets (e.g. '100% WR over 2 trades'). Not auto-defaulted here for backward compatibility.
      - name: min_avg_duration_hours
        in: query
        required: false
        schema:
          description: Min avg trade duration (hours)
          title: Min Avg Duration Hours
          type:
          - number
          - 'null'
          minimum: 0
        description: Min avg trade duration (hours)
      - name: exclude_types
        in: query
        required: false
        schema:
          description: Comma-separated trader types to exclude, e.g. 'hft,scalper'
          title: Exclude Types
          type:
          - string
          - 'null'
        description: Comma-separated trader types to exclude, e.g. 'hft,scalper'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLCopySignalsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/trader-profile/{address}:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Trader Profile
      description: On-demand trade profile for ANY Hyperliquid address. Fetches fill history and computes stats.
      operationId: get_trader_profile_api_v1_hyperliquid_trader_profile__address__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          title: Address
        example: '0x880ac484a1743862989a441d6d867238c7aa311c'
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          description: Analysis period in days
          default: 30
          title: Days
        description: Analysis period in days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLTraderProfileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/hyperliquid/wallet-trades/{address}:
    get:
      tags:
      - Hyperliquid Traders
      summary: Get Wallet Trades
      description: Historical trades for any Hyperliquid address with summary statistics.
      operationId: get_wallet_trades_api_v1_hyperliquid_wallet_trades__address__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          title: Address
        example: '0x880ac484a1743862989a441d6d867238c7aa311c'
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          description: Trade history period in days
          default: 30
          title: Days
        description: Trade history period in days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HLWalletTradesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AutoWatchlistRequest:
      properties:
        mode:
          type: string
          title: Mode
          description: Source mode (currently only 'top_traders')
          default: top_traders
        max_wallets:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Max Wallets
          description: Max wallets in auto-managed set
          default: 15
        min_score:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Min Score
          description: Minimum top-trader score
          default: 80
        filters:
          $ref: '#/components/schemas/AutoWatchlistFilters'
        auto_refresh:
          type: boolean
          title: Auto Refresh
          description: Re-evaluate daily and update automatically
          default: true
      type: object
      title: AutoWatchlistRequest
    HLAutoWatchlistResponse:
      properties:
        managed:
          type: boolean
          title: Managed
        wallet_count:
          type: integer
          title: Wallet Count
        wallets:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Wallets
        config:
          additionalProperties: true
          type: object
          title: Config
        next_refresh:
          title: Next Refresh
          type:
          - string
          - 'null'
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - managed
      - wallet_count
      - wallets
      - config
      title: HLAutoWatchlistResponse
      description: Auto-managed watchlist result.
    HLTopTradersResponse:
      properties:
        traders:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Traders
        total_leaderboard_size:
          type: integer
          title: Total Leaderboard Size
          default: 0
        after_filter:
          type: integer
          title: After Filter
          default: 0
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - traders
      title: HLTopTradersResponse
      description: Scored leaderboard of top Hyperliquid traders.
    HLTraderProfileResponse:
      properties:
        profile:
          additionalProperties: true
          type: object
          title: Profile
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - profile
      title: HLTraderProfileResponse
      description: Single trader profile (on-demand for any address).
    HLTraderProfilesResponse:
      properties:
        profiles:
          additionalProperties: true
          type: object
          title: Profiles
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - profiles
      title: HLTraderProfilesResponse
      description: Trade profiles with win rate, PnL stats, and classification.
    HLCopySignalsResponse:
      properties:
        traders:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Traders
        window_minutes:
          type: integer
          title: Window Minutes
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - traders
      - window_minutes
      title: HLCopySignalsResponse
      description: Top traders with their recent signals in a single response.
    HLWalletSearchResponse:
      properties:
        wallets:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Wallets
        count:
          type: integer
          title: Count
        filters:
          additionalProperties: true
          type: object
          title: Filters
        pool_size:
          type: integer
          title: Pool Size
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - wallets
      - count
      - filters
      - pool_size
      title: HLWalletSearchResponse
      description: Wallets from the cached top-leaderboard pool that satisfy the given gates.
    HLWalletTradesResponse:
      properties:
        address:
          type: string
          title: Address
        trades:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Trades
        summary:
          additionalProperties: true
          type: object
          title: Summary
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - address
      - trades
      - summary
      title: HLWalletTradesResponse
      description: Historical trades for a wallet with summary statistics.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WatchlistAddEntry:
      properties:
        address:
          type: string
          title: Address
        label:
          title: Label
          type:
          - string
          - 'null'
        notes:
          title: Notes
          type:
          - string
          - 'null'
      type: object
      required:
      - address
      title: WatchlistAddEntry
    HLWalletPositionsResponse:
      properties:
        wallets:
          additionalProperties: true
          type: object
          title: Wallets
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - wallets
      title: HLWalletPositionsResponse
      description: Current positions for tracked wallets.
    AutoWatchlistFilters:
      properties:
        min_win_rate:
          title: Min Win Rate
          description: Minimum 30d win rate (0-1)
          type:
          - number
          - 'null'
          maximum: 1.0
          minimum: 0.0
        min_profit_factor:
          title: Min Profit Factor
          description: Minimum profit factor
          type:
          - number
          - 'null'
          minimum: 0.0
        min_trades_30d:
          title: Min Trades 30D
          description: Minimum trades in 30d. Defaults to 30 when filters are provided, to prevent tiny-sample wallets (e.g. '100% WR over 2 trades') from passing. Pass 0 explicitly to disable.
          type:
          - integer
          - 'null'
          minimum: 0.0
        min_avg_duration_hours:
          title: Min Avg Duration Hours
          description: Min avg trade duration (hours)
          type:
          - number
          - 'null'
          minimum: 0.0
        exclude_types:
          title: Exclude Types
          description: Trader types to exclude, e.g. ['hft','scalper']
          items:
            type: string
          type:
          - array
          - 'null'
      type: object
      title: AutoWatchlistFilters
    WatchlistAddDetailedRequest:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/WatchlistAddEntry'
          type: array
          title: Entries
      type: object
      required:
      - entries
      title: WatchlistAddDetailedRequest
    WatchlistRemoveRequest:
      properties:
        addresses:
          items:
            type: string
          type: array
          title: Addresses
      type: object
      required:
      - addresses
      title: WatchlistRemoveRequest
    HLWatchlistResponse:
      properties:
        addresses:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Addresses
        count:
          type: integer
          title: Count
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - addresses
      - count
      title: HLWatchlistResponse
      description: Current watchlist addresses.
    HLWalletSignalsResponse:
      properties:
        signals:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Signals
        window_minutes:
          type: integer
          title: Window Minutes
        updated_at:
          title: Updated At
          type:
          - string
          - 'null'
      type: object
      required:
      - signals
      - window_minutes
      title: HLWalletSignalsResponse
      description: Position change signals (entry/exit/increase/decrease).
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key