alphayou-net Alpha You API

openapi: 3.2.0
info:
  title: Alpha You API
  version: 1.0.0
  description: 'Read-only access to AlphaYou''s smart-money record: what insiders, funds and politicians disclosed, what AlphaYou published on the back of it, and how those calls turned out against the S&P 500.


    The thing no comparable API sells is the last part. Others will tell you what was filed. This tells you which sources have historically been worth following, with the evidence attached.


    Plans:

    - Free: 6 tools, 100 requests a day, free.

    - Pro: 11 tools, 50,000 requests a day, $49 a month.


    Create a free key at https://alphayou.net/developers. Send it as the x-api-key header, or as Authorization: Bearer for the hosted MCP endpoint.


    Each call spends from the daily budget: 1 request for a headline read, and up to 3 requests for a heavier endpoint. The X-RateLimit-Cost header on every response says how many, and X-RateLimit-Remaining says what is left. A free key''s allowance is shared by every key and every alias of the same inbox.


    Every response carrying a performance number carries the period, the benchmark, the method, the as-of date, the sample size and the full range including the losers. Numbers without those six are not published.


    Use of the API is governed by the API terms at https://alphayou.net/legal/api-terms.'
  termsOfService: https://alphayou.net/legal/api-terms
  contact:
    name: AlphaYou
    url: https://alphayou.net/developers
    email: info@alphayou.net
servers:
- url: https://api.alphayou.net
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: AlphaYou
paths:
  /api/mcp/whoami:
    get:
      operationId: whoami
      summary: What this key can do
      description: 'Returns the tier a key resolves to and the tools it may call. The published MCP package calls this at startup to decide which tools to register, so it answers on the lowest tier.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/mcp:
    post:
      operationId: mcp_endpoint
      summary: Hosted MCP server
      description: 'The same tools as the alphayou-mcp package, hosted, so an MCP client connects with a URL and a key and installs nothing. Send the key as Authorization: Bearer ay_... or as x-api-key. Streamable HTTP, stateless: one JSON-RPC operation per request, no batches, no sessions. initialize, ping and tools/list cost nothing. Each tools/call is metered exactly like the matching REST endpoint, in that tool''s own request cost, against the same daily budget and limits.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: One JSON-RPC 2.0 request object, for example {"jsonrpc":"2.0","id":1,"method":"tools/list"}.
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/signals/alpha:
    get:
      operationId: alphayou_track_record
      summary: Headline track record
      description: 'The complete published record of AlphaYou buy calls (`record`, the same record as /calls/proof): how many there are, how they performed against the S&P 500 over 60 days, the best and the worst, and how many finished negative. Paid keys also get `research`, a breakdown by confidence tier across all public calls from the published price, labelled as research rather than the track record.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/signals/recent:
    get:
      operationId: alphayou_calls
      summary: Recent buy calls
      description: 'Published buy calls, newest first. A free key gets the same live calls a signed-out visitor sees on alphayou.net/calls, plus a count of the calls withheld; a paid key sees every recent call as published.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/datasets:
    get:
      operationId: alphayou_search_datasets
      summary: What data exists
      description: 'The catalog of datasets and the tool that returns each one, with its plan and cost. Costs no requests, so an agent can call it first to decide what to call next. Optional q filters by a word.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: q
        in: query
        required: false
        description: Filter the list by a word (up to 60 characters).
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/funds:
    get:
      operationId: alphayou_funds
      summary: Tracked funds
      description: 'The institutional investment managers whose Form 13F filings AlphaYou tracks: latest reporting period, filing date, position count, the total value the filer reported on the cover page, and the SEC filing link. Raw filing data, biggest reported value first, the same for every key. Pages with nextCursor.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: Rows per page, 1 to 200 (default 50).
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: The nextCursor from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/tickers/{symbol}/disclosures:
    get:
      operationId: alphayou_company_disclosures
      summary: Company 8-K disclosures
      description: 'Recent SEC 8-K filings for one US-listed company, read from SEC EDGAR: the items filed (with their titles), the filing date and the original SEC link. The complete list for the window, metadata only, not article text, news or sentiment. A symbol with no SEC-registered company is a 404. Free keys look back 90 days, Pro keys 365.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: symbol
        in: path
        required: true
        description: US ticker such as NVDA or BRK.B.
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Look-back in days, up to your plan's window.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Rows, 1 to 20 (default 10).
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/insiders/trades:
    get:
      operationId: alphayou_insider_trades
      summary: Insider trades
      description: 'Insider open-market buys and sells from SEC Form 4 filings, newest first: the insider, their role, each trade with date, shares and price, the 10b5-1 plan label and the SEC link. Free keys get the 5 newest filings from the last 90 days; Pro keys page through 365 days with nextCursor. None found means no open-market trade is on file, not that nobody filed.


        Plans: Free, Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: ticker
        in: query
        required: false
        description: US ticker such as NVDA. Leave out for all companies.
        schema:
          type: string
      - name: side
        in: query
        required: false
        description: buy, sell or both (default both).
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Look-back in days, up to your plan's window (90 Free, 365 Pro).
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: 'Pro only: rows per page, 1 to 100 (default 25). Free keys always get 5.'
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: 'Pro only: the nextCursor from the previous page.'
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/insiders/clusters:
    get:
      operationId: alphayou_insider_clusters
      summary: Insider clusters
      description: 'Companies where several different insiders filed an open-market buy (or sale) on SEC Form 4 inside a short window: how many insiders, how many filings, how many under a 10b5-1 plan, and who. A plain count with its parameters shown, not a score or a prediction.


        Plans: Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: side
        in: query
        required: false
        description: buy (default) or sell.
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Window in days, 1 to 90 (default 14 for buys, 7 for sells).
        schema:
          type: string
      - name: min
        in: query
        required: false
        description: Minimum different insiders, 2 to 20 (default 3).
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Companies, 1 to 50 (default 25).
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/funds/{cik}/holdings:
    get:
      operationId: alphayou_fund_holdings
      summary: Fund holdings
      description: 'One tracked fund''s newest Form 13F book, biggest position first: issuer, CUSIP, ticker where mapped, value, shares and the share change against the fund''s previous filing. Long US-listed positions only, as of a quarter end and filed up to 45 days later, so not the fund''s book today. Use a cik from the funds list. Pages with nextCursor.


        Plans: Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: cik
        in: path
        required: true
        description: The fund's SEC CIK, taken from the funds list.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Rows per page, 1 to 250 (default 50).
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: The nextCursor from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/funds/{cik}/changes:
    get:
      operationId: alphayou_fund_changes
      summary: Fund changes
      description: 'What one tracked fund changed between its newest Form 13F and the one before: new positions, adds, trims and exits, largest estimated trade first, with the share counts in both filings. The trade size is an estimate from quarter-end prices, not a fill price, and nothing inside the quarter is visible. Pages with nextCursor.


        Plans: Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: cik
        in: path
        required: true
        description: The fund's SEC CIK, taken from the funds list.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Rows per page, 1 to 100 (default 50).
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: The nextCursor from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/v1/tickers/{symbol}/holders:
    get:
      operationId: alphayou_ticker_holders
      summary: Funds holding a stock
      description: 'Which tracked funds list one stock in their newest Form 13F, biggest position first, with the share change against each fund''s previous filing. Only the funds in the funds list, not every institution, and none found does not prove nobody holds it. Pages with nextCursor.


        Plans: Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      parameters:
      - name: symbol
        in: path
        required: true
        description: US ticker such as NVDA or BRK.B.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Rows per page, 1 to 100 (default 25).
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        description: The nextCursor from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
  /api/top-traders:
    get:
      operationId: alphayou_top_traders
      summary: Top traders' Hyperliquid positions
      description: 'Positions the top tracked traders currently hold in Hyperliquid perpetual contracts linked to US stocks, not shares: side, size, entry price and unrealized profit. Only stocks confirmed against the US ticker registry are returned. An annualised ROI at the 10000% ceiling is returned as null with roiCapped true.


        Plans: Pro.'
      tags:
      - AlphaYou
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The requested records.
        '401':
          description: Missing, unrecognised or revoked API key (error key_revoked).
        '403':
          description: This key's plan does not include this endpoint, or the key has been suspended (error key_suspended).
        '404':
          description: Not an endpoint an API key may call.
        '429':
          description: 'Rate limited. The scope field says which budget ran out: minute, day, account (shared by all of an account''s keys), or concurrency (too many calls running at once). Retry-After says when to come back, and X-RateLimit-Remaining reports what is left of today''s budget. A call refused for going too fast (the per-minute limit) does not use up the day, so wait for Retry-After and try again.'
        '503':
          description: The request budget could not be checked right now. Retry after the number of seconds in Retry-After.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      description: Your AlphaYou API key (ay_...).