alphayou-net Traders API
Scored Hyperliquid traders and their positions.
Scored Hyperliquid traders and their positions.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/alphayou-net:alphayou-net-traders-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: AlphaYou Public Traders API
version: 1.0.0
summary: Read-only access to AlphaYou's scored Hyperliquid trader data.
description: 'AlphaYou scores Hyperliquid perpetuals traders from public on-chain records and lets users copy them from wallets they control.
The endpoints below are public and require no authentication. They are read-only: nothing here places an order, moves funds, or changes an account.
Account, strategy, basket and vault endpoints also exist under `/api`. They act on real user funds, require a Privy access token issued to the signed-in wallet, and are intentionally not described here.
Rate limiting is per IP and returns 429 with a `Retry-After` header. Errors are JSON in the `Error` schema on every documented endpoint.
AlphaYou is not a fund, broker, or investment adviser. Trader data is evidence, not advice, and a qualifying score is not a prediction.'
termsOfService: https://app.alphayou.net/terms
contact:
name: AlphaYou
email: info@alphayou.net
url: https://app.alphayou.net
servers:
- url: https://app.alphayou.net
description: Production
tags:
- name: Traders
description: Scored Hyperliquid traders and their positions.
paths:
/api/traders:
get:
tags:
- Traders
operationId: listTraders
summary: List scored traders
description: 'The public trader feed, already filtered to the published quality floor: perpetuals account value above $100,000, perpetuals profit above $20,000, Mirror Score above 7.0, and composite leverage of at least 0.3x. Filter parameters can only tighten those floors for unauthenticated callers; a looser value is clamped rather than honoured.'
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: offset
in: query
schema:
type: integer
minimum: 0
default: 0
- name: sort_by
in: query
description: Feed item field to sort on, e.g. `trader_score`, `total_pnl`, `annualised_roi_pct`.
schema:
type: string
default: trader_score
- name: sort_order
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
- name: bucket
in: query
description: Asset class currently held. Repeat the parameter to OR several together.
schema:
type: array
items:
type: string
enum:
- bluechips
- altcoins
- indices
- stocks
- forex
- commodities
- preipo
- name: assets
in: query
description: Restrict to traders holding these specific assets. Repeat the parameter for several. A bare ticker (ANTH, NVDA, BTC) matches that market on any venue; a prefixed name (io:ANTH, xyz:NVDA) matches only that market.
schema:
type: array
items:
type: string
- name: address
in: query
description: Return a single trader by address.
schema:
type: string
- name: min_score
in: query
schema:
type: number
minimum: 0
maximum: 10
- name: min_pnl
in: query
schema:
type: number
- name: min_account_value
in: query
schema:
type: number
minimum: 0
- name: max_account_value
in: query
schema:
type: number
minimum: 0
- name: max_dd
in: query
description: Maximum observed drawdown, percent.
schema:
type: number
minimum: 0
- name: min_roi
in: query
schema:
type: number
- name: min_weeks
in: query
schema:
type: integer
minimum: 0
- name: min_r2
in: query
schema:
type: number
minimum: 0
maximum: 1
- name: min_composite_leverage
in: query
schema:
type: number
minimum: 0
- name: min_efficiency_pct
in: query
schema:
type: number
- name: min_unrealized_pnl
in: query
schema:
type: number
- name: max_unrealized_pnl
in: query
schema:
type: number
- name: max_staleness_hours
in: query
schema:
type: number
minimum: 1
maximum: 8760
- name: only_with_positions
in: query
description: Drop traders with no open position. Cleanest for a copy surface.
schema:
type: boolean
default: false
responses:
'200':
description: A page of scored traders.
content:
application/json:
schema:
$ref: '#/components/schemas/TraderFeed'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/meta:
get:
tags:
- Traders
operationId: getTraderMeta
summary: Feed freshness and coverage
description: How many wallets are tracked, how they split across tiers, and when the feed was last updated.
responses:
'200':
description: Feed metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/TraderMeta'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/{address}:
get:
tags:
- Traders
operationId: getTrader
summary: One trader in full
description: Score breakdown, equity, open positions and PnL history for a single wallet.
parameters:
- name: address
in: path
required: true
description: EVM address of the Hyperliquid trader, lower-case hex.
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
responses:
'200':
description: Trader detail.
content:
application/json:
schema:
$ref: '#/components/schemas/TraderDetail'
'422':
description: The address is not a valid EVM address.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/{address}/backtest:
get:
tags:
- Traders
operationId: backtestTrader
summary: Replay capital through a trader's observed returns
description: Replays `capital` through the trader's own cash-flow-adjusted return series over 30, 60 and 90 days. Windows with fewer than two real observations return nulls; figures are never extrapolated. A window is also null when it reaches a span where the trader's capital sat outside the perp account and the replay would be implausible; `capital_basis` is then `unavailable`. This is a historical replay, not a projection.
parameters:
- name: address
in: path
required: true
description: EVM address of the Hyperliquid trader, lower-case hex.
schema:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
- name: capital
in: query
required: true
description: Hypothetical starting capital in USD.
schema:
type: number
exclusiveMinimum: 0
responses:
'200':
description: Replay result per window.
content:
application/json:
schema:
type: object
additionalProperties: true
'422':
description: Invalid address or capital.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/positioning:
get:
tags:
- Traders
operationId: getPositioning
summary: Top-trader long/short split for one asset
parameters:
- name: coin
in: query
required: true
description: Asset name as Hyperliquid reports it, e.g. `BTC` or `xyz:NVDA`.
schema:
type: string
minLength: 1
maxLength: 64
responses:
'200':
description: Aggregate positioning for the asset.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
description: '`coin` is missing.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/positioning/all:
get:
tags:
- Traders
operationId: getPositioningAll
summary: Top-trader long/short split across every tracked asset
responses:
'200':
description: Fresh confirmed positioning, keyed by exact market; coverage reports missing trader books.
content:
application/json:
schema:
type: object
additionalProperties: true
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/api/traders/positions:
get:
tags:
- Traders
operationId: getTraderPositions
summary: Individual open positions across one or more assets
description: All positive positions from fresh confirmed books in the public-feed cohort. Coverage distinguishes complete, partial and unavailable data.
parameters:
- name: coins
in: query
required: true
description: Comma-separated asset names, e.g. `BTC,xyz:NVDA,GOLD`.
schema:
type: string
minLength: 1
maxLength: 3249
- name: exact_market
in: query
required: false
description: Match exact venue-qualified or native market names; prevents mixing same-ticker markets.
schema:
type: boolean
default: false
responses:
'200':
description: Open positions per trader.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
description: '`coins` is missing.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Per-IP rate limit exceeded. Honour the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: The trading engine did not answer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TraderFeed:
type: object
required:
- items
- total
- limit
- offset
properties:
items:
type: array
items:
$ref: '#/components/schemas/TraderFeedItem'
total:
type: integer
description: Traders matching the filter, not just this page.
limit:
type: integer
offset:
type: integer
additionalProperties: true
TraderDetail:
type: object
description: Everything in TraderFeedItem plus equity, open positions and PnL history.
required:
- address
properties:
address:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
additionalProperties: true
TraderFeedItem:
type: object
description: One row of the feed. A null field means 'not observed', not zero.
required:
- address
properties:
address:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
display_name:
type:
- string
- 'null'
trader_score:
type:
- number
- 'null'
description: Mirror Score, 0-10. Nine signals; maximum observed drawdown carries the largest weight.
breakdown:
type: object
description: Per-signal sub-scores behind trader_score.
additionalProperties:
type: number
total_pnl:
type:
- number
- 'null'
description: Perpetuals all-time PnL, USD.
combined_total_pnl:
type:
- number
- 'null'
description: Perps plus spot plus staking, USD.
pnl_30d:
type:
- number
- 'null'
annualised_roi_pct:
type:
- number
- 'null'
description: Cash-flow-adjusted annualised return, percent.
max_drawdown_pct:
type:
- number
- 'null'
description: Deepest observed drawdown, percent. 60 or more disqualifies a wallet.
sharpe:
type:
- number
- 'null'
sortino:
type:
- number
- 'null'
efficiency_pct:
type:
- number
- 'null'
description: PnL as a percentage of lifetime volume.
account_value:
type:
- number
- 'null'
description: Perpetuals account value, USD.
open_positions:
type:
- integer
- 'null'
open_notional_usd:
type:
- number
- 'null'
history_days:
type:
- integer
- 'null'
up_weeks:
type:
- integer
- 'null'
down_weeks:
type:
- integer
- 'null'
trading_since:
type:
- string
- 'null'
format: date
analyzed_at:
type:
- string
- 'null'
format: date-time
description: Last successful rescore.
staleness_hours:
type:
- number
- 'null'
current_assets:
type: array
items:
type: string
current_asset_tags:
type: array
items:
type: string
copier_count:
type: integer
description: Active copy strategies pointed at this trader.
additionalProperties: true
TraderMeta:
type: object
properties:
last_updated:
type:
- string
- 'null'
format: date-time
total_tracked:
type: integer
tier_counts:
type: object
additionalProperties:
type: integer
feed_health_score_floor:
type:
- number
- 'null'
additionalProperties: true
Error:
type: object
required:
- error
- code
- message
- hint
- status
properties:
error:
type: string
description: Human-readable summary.
code:
type: string
description: Stable machine-readable error identifier.
enum:
- authentication_required
- engine_error
- engine_unavailable
- invalid_json
- invalid_request
- method_not_allowed
- not_found
- rate_limited
message:
type: string
hint:
type: string
description: What the caller should do next.
status:
type: integer
detail:
description: Upstream payload or exception text. Shape varies.
documentation_url:
type: string
format: uri
additionalProperties: true
securitySchemes:
privyAccessToken:
type: http
scheme: bearer
bearerFormat: JWT
description: Privy access token for the signed-in wallet. Required only by the account, strategy, basket-start and vault-start endpoints, which are not described in this document.
externalDocs:
description: Site summary for language models
url: https://app.alphayou.net/llms.txt