Docs

Full API reference for the Alphio open platform.

Getting started

Quick start

1.Create an API key in API Key. Copy it once — we hash it before storage.
2.Onboard your end users: UpsertVirtualUser → CreateChatSession → /openchat-steam/completions
3.Wire your SSE reader to handle submitted → delta* → done events.

curl https://api.alphio.ai/v1/openapi/users \
  -H "Authorization: Bearer pk_live_••••••••••••••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{"partner_user_ref": "u_998877"}'

Base URL & envelope

Base URL: https://api.alphio.ai
Response envelope: { ret, msg, data }
HTTP status: Always 200 (for non-SSE). Inspect ret for the business result.
SSE: Chat completions stream as text/event-stream.

Authentication

Every request carries a Bearer API key. End-user-scoped endpoints additionally need an X-Partner-User header.

Header	Value	When
Authorization	Bearer pk_live_…	Every request
Content-Type	application/json	Every request
X-Partner-User	your_user_id	Only for end-user-scoped endpoints: /openchat-steam/completions + whales/following/ranking
Accept	text/event-stream	SSE chat only

The value of X-Partner-User is your own user ID. The platform maps it to a stable internal_user_id like op_{partner_code}_{nanoid}. The user must first be registered via UpsertVirtualUser or chat returns ret=10404.

Errors & limits

Error codes

HTTP is always 200; check ret

ret	Meaning	Typical cause
0	OK	Success
10400	Bad request	Missing required field / type mismatch / empty message
10401	Unauthenticated	Missing / wrong / expired / revoked Bearer
10403	Forbidden	User disabled / cross-user access
10404	Not found	User not registered (call UpsertVirtualUser) / bad session_id
10429	Rate limited	RPM quota exceeded
10500	Server error	Contact support with occurred_at / chat_id
10501	Insufficient balance	Top up to resume chat

Rate limits & billing

Default ceilings: 600 partner RPM · 60 per-user RPM · 8 concurrent chat streams. Negotiated on a per-plan basis.

Billing: one chat round (submit → done) deducts one billable unit. Interrupted / disconnected sessions still bill (anti-spam). failed events do not bill. Analysis, Whales, and Data endpoints are free of charge.

Virtual users

Manage end-user identities under your partner account. Virtual users are created lazily; the same partner_user_ref always maps to the same internal_user_id.

POST/v1/openapi/users

UpsertVirtualUser

Request parameters

Field	Type	Required	Description
partner_user_ref	string	yes	Your own user ID for this end user.
display_name	string	no	Optional, for audit/debugging.
metadata	string	no	Opaque JSON string, not parsed by the platform.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	VirtualUser	Response payload.
└internal_user_id	string	Platform-assigned ID. Format: "op_{partner_code}_{nanoid12}".
└partner_user_ref	string	Echoed back.
└display_name	string	Echoed back.
└metadata	string	Echoed back (JSON string).
└status	string	"active" / "disabled".
└is_new	bool	true only on first creation.
└created_at	string	ISO8601 UTC.
└last_active_at	string	ISO8601 UTC. Empty if never used.

Example request

curl -X POST https://api.alphio.ai/v1/openapi/users \
  -H "Authorization: Bearer pk_live_••••••••••••••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_user_ref": "u_998877",
    "display_name": "Alice"
  }'

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "internal_user_id": "op_intellectia_qUk8CyDetjsK",
    "partner_user_ref": "u_998877",
    "display_name": "Alice",
    "metadata": "",
    "status": "active",
    "is_new": true,
    "created_at": "2026-06-09T08:02:14Z",
    "last_active_at": ""
  }
}

POST/v1/openapi/users/get

GetVirtualUser

Look up a virtual user by partner_user_ref. Response shape matches UpsertVirtualUser except is_new is always false.

Request parameters

Field	Type	Required	Description
partner_user_ref	string	yes	—

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	VirtualUser	Response payload.
└internal_user_id	string	Platform-assigned ID. Format: "op_{partner_code}_{nanoid12}".
└partner_user_ref	string	Echoed back.
└display_name	string	Echoed back.
└metadata	string	Echoed back (JSON string).
└status	string	"active" / "disabled".
└is_new	bool	true only on first creation.
└created_at	string	ISO8601 UTC.
└last_active_at	string	ISO8601 UTC. Empty if never used.

POST/v1/openapi/users/disable

DisableVirtualUser

Disable a virtual user. Their chat requests will return ret=10403 until re-enabled via UpsertVirtualUser.

Request parameters

Field	Type	Required	Description
partner_user_ref	string	yes	—

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DisableVirtualUserData	Response payload.
└status	string	Always "disabled".

POST/v1/openapi/users/list

ListVirtualUsers

Paginated list of your virtual users.

Request parameters

Field	Type	Required	Description
filter	VirtualUserListFilter	no	Optional filters.
└status	string	no	"active" / "disabled" / "" (all).
└created_after	string	no	ISO8601 UTC.
└created_before	string	no	ISO8601 UTC.
page	int32	no	1-indexed. Default 1.
size	int32	no	Default 20, max 200.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ListVirtualUsersData	Response payload.
└items	VirtualUser[]	—
└internal_user_id	string	Platform-assigned ID. Format: "op_{partner_code}_{nanoid12}".
└partner_user_ref	string	Echoed back.
└display_name	string	Echoed back.
└metadata	string	Echoed back (JSON string).
└status	string	"active" / "disabled".
└is_new	bool	true only on first creation.
└created_at	string	ISO8601 UTC.
└last_active_at	string	ISO8601 UTC. Empty if never used.
└pagination	Pagination	—
└page	int32	1-indexed.
└size	int32	Items per page.
└total	int64	Total rows matching the filter.
└has_more	bool	Whether more pages exist.

Chat (SSE streaming)

Multi-turn AI chat with built-in skills (technical analysis, market data, news). Response is text/event-stream — every event is emitted as `event: NAME\ndata: JSON\n\n`. Unlike all other endpoints, the SSE stream is NOT wrapped in `{ret, msg, data}`.

POST/openchat-steam/completionsX-Partner-User required

ChatCompletions

Start a chat turn. Returns an SSE stream until done or failed.

Each delta.content is incremental — append to a client buffer. The final done event carries the full content as a sanity check.

Failed events do not bill. Submitted → done is one billable round.

Request parameters

Field	Type	Required	Description
chat_id	string	yes	Your generated unique ID for this turn, e.g. chat-{uuid}. Used for idempotency and tracing.
message	string	yes	The user's question.
metadata	ChatMetadata	yes	—
└session_id	string	yes	From CreateChatSession. Wrong/missing → ret=10404.
└timezone	string	no	IANA timezone, e.g. "Asia/Shanghai". Affects "today/yesterday" interpretation.
└language	string	no	"zh" / "en" / etc. Default: adaptive to user language.

Response fields

Field	Type	Description
event: submitted	SSE	Acknowledgement that the request was accepted.
└chat_id	string	Echoed back.
└status	string	"RUNNING".
└user_id	string	internal_user_id resolved from X-Partner-User.
└session_id	string	Echoed back.
└occurred_at	string	ISO8601 UTC.
event: status	SSE	Intermediate progress.
└stage	string	agent_round_start / tool_call_start / model_call_start / etc.
└message	string	Human-readable status.
└progress	float	0.0 – 1.0.
event: delta	SSE	Streaming answer chunk.
└content	string	Incremental fragment — append to a client buffer.
└status	string	"RUNNING".
event: done	SSE	Stream complete.
└content	string	Full final answer (sanity check against the joined deltas).
└status	string	"SUCCESS".
└progress	float	1.0.
└token_usage	object	Token counters for billing visibility.
event: failed	SSE	Terminal failure (insufficient balance, backend error, etc).
└message	string	Error description.
└status	string	"FAILED".

Example request

curl -N -X POST https://api.alphio.ai/openchat-steam/completions \
  -H "Authorization: Bearer pk_live_••••••••••••••••••••••••••••" \
  -H "X-Partner-User: u_998877" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "chat-998877-1719283400",
    "message": "What is AAPL'\''s current RSI?",
    "metadata": {
      "session_id": "sess_ifm92XaV7gqx",
      "timezone": "America/New_York",
      "language": "en"
    }
  }'

Example response

event: submitted
data: {"chat_id":"chat-998877-1719283400","status":"RUNNING",
       "user_id":"op_intellectia_qUk8CyDetjsK","session_id":"sess_ifm92XaV7gqx",
       "occurred_at":"2026-06-09T08:18:24.77Z"}

event: status
data: {"chat_id":"...","stage":"agent_round_start",
       "status":"PROCESSING","progress":0.15,"message":"Understanding question"}

event: status
data: {"chat_id":"...","stage":"tool_call_start",
       "status":"PROCESSING","progress":0.50,"message":"Fetching technical indicators"}

event: delta
data: {"chat_id":"...","status":"RUNNING","content":"AAPL's current RSI(14) is 68,"}

event: delta
data: {"chat_id":"...","status":"RUNNING","content":" approaching the overbought zone (70)..."}

event: done
data: {"chat_id":"...","status":"SUCCESS","progress":1.0,
       "stage":"task_completed","content":"AAPL's current RSI(14) is 68, approaching..."}

Chat sessions & messages

A session groups related chat turns. History within a session is automatically injected as context.

POST/v1/openapi/chat/sessions/create

CreateChatSession

Request parameters

Field	Type	Required	Description
internal_user_id	string	yes	From UpsertVirtualUser.
title	string	no	Display title for your UI.
metadata	string	no	Opaque JSON string.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ChatSession	Response payload.
└session_id	string	Format: "sess_{nanoid}".
└internal_user_id	string	Owner.
└title	string	—
└metadata	string	JSON string.
└status	string	"active" / "deleted".
└last_message_at	string	ISO8601 UTC. Empty for a freshly created session.
└created_at	string	ISO8601 UTC.
└updated_at	string	ISO8601 UTC.

POST/v1/openapi/chat/sessions/list

ListChatSessions

Request parameters

Field	Type	Required	Description
internal_user_id	string	no	Empty = list across all your virtual users.
status	string	no	"active" / "deleted" / "" (all). Default "active".
page	int32	no	Default 1.
size	int32	no	Default 20, max 200.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ListChatSessionsData	Response payload.
└items	ChatSession[]	—
└session_id	string	Format: "sess_{nanoid}".
└internal_user_id	string	Owner.
└title	string	—
└metadata	string	JSON string.
└status	string	"active" / "deleted".
└last_message_at	string	ISO8601 UTC. Empty for a freshly created session.
└created_at	string	ISO8601 UTC.
└updated_at	string	ISO8601 UTC.
└page	int32	1-indexed.
└size	int32	Items per page.
└total	int64	Total rows matching the filter.
└has_more	bool	Whether more pages exist.

POST/v1/openapi/chat/sessions/get

GetChatSession

Request parameters

Field	Type	Required	Description
session_id	string	yes	—

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ChatSession	Response payload.
└session_id	string	Format: "sess_{nanoid}".
└internal_user_id	string	Owner.
└title	string	—
└metadata	string	JSON string.
└status	string	"active" / "deleted".
└last_message_at	string	ISO8601 UTC. Empty for a freshly created session.
└created_at	string	ISO8601 UTC.
└updated_at	string	ISO8601 UTC.

POST/v1/openapi/chat/sessions/update

UpdateChatSession

Edit the title or metadata of an existing session.

Request parameters

Field	Type	Required	Description
session_id	string	yes	—
title	string	no	Empty = unchanged.
metadata	string	no	Empty = unchanged.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ChatSession	Response payload.
└session_id	string	Format: "sess_{nanoid}".
└internal_user_id	string	Owner.
└title	string	—
└metadata	string	JSON string.
└status	string	"active" / "deleted".
└last_message_at	string	ISO8601 UTC. Empty for a freshly created session.
└created_at	string	ISO8601 UTC.
└updated_at	string	ISO8601 UTC.

POST/v1/openapi/chat/sessions/delete

DeleteChatSession

Soft-delete by default. Message history remains queryable.

Request parameters

Field	Type	Required	Description
session_id	string	yes	—
soft_delete	bool	no	Default true. Set false for permanent deletion.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DeleteChatSessionData	Response payload.
└status	string	"deleted" / "hard_deleted".

POST/v1/openapi/chat/sessions/messages

ListSessionMessages

Cursor-paginated history. Order is by created_at DESC.

Request parameters

Field	Type	Required	Description
session_id	string	yes	—
before_message_id	string	no	Cursor — pass the message_id of your current oldest message to fetch older ones.
size	int32	no	Default 50, max 200.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ListSessionMessagesData	Response payload.
└items	ChatMessage[]	—
└message_id	string	Format: "msg_{nanoid}".
└chat_id	string	Matches the SSE chat_id. One chat_id usually produces 2 messages (user + assistant).
└session_id	string	May be empty for session-less chat.
└internal_user_id	string	—
└role	string	"user" / "assistant".
└content	string	Raw Markdown stream. May contain ```json card fences.
└attachments	ChatAttachment[]	—
└url	string	Pre-signed URL. May expire.
└mime	string	—
└name	string	—
└tool_calls	ChatToolCall[]	—
└step_id	string	—
└kind	string	"round" / "tool_call".
└round	int32	—
└tool_name	string	—
└args_json	string	Stringified tool arguments.
└result_summary	string	—
└status	string	"ok" / "error" / "running".
└started_at_ms	int64	Unix milliseconds.
└ended_at_ms	int64	Unix milliseconds.
└sources	ChatSource[]	—
└title	string	—
└url	string	—
└snippet	string	—
└error_code	string	Non-empty on terminal failure.
└error_message	string	—
└doc_id	string	Chatbot's assistant doc_id.
└created_at	string	ISO8601 UTC.
└has_more	bool	—

POST/v1/openapi/chat/messages/get

GetChatMessage

Request parameters

Field	Type	Required	Description
message_id	string	yes	—

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ChatMessage	Response payload.
└message_id	string	Format: "msg_{nanoid}".
└chat_id	string	Matches the SSE chat_id. One chat_id usually produces 2 messages (user + assistant).
└session_id	string	May be empty for session-less chat.
└internal_user_id	string	—
└role	string	"user" / "assistant".
└content	string	Raw Markdown stream. May contain ```json card fences.
└attachments	ChatAttachment[]	—
└url	string	Pre-signed URL. May expire.
└mime	string	—
└name	string	—
└tool_calls	ChatToolCall[]	—
└step_id	string	—
└kind	string	"round" / "tool_call".
└round	int32	—
└tool_name	string	—
└args_json	string	Stringified tool arguments.
└result_summary	string	—
└status	string	"ok" / "error" / "running".
└started_at_ms	int64	Unix milliseconds.
└ended_at_ms	int64	Unix milliseconds.
└sources	ChatSource[]	—
└title	string	—
└url	string	—
└snippet	string	—
└error_code	string	Non-empty on terminal failure.
└error_message	string	—
└doc_id	string	Chatbot's assistant doc_id.
└created_at	string	ISO8601 UTC.

POST/v1/openapi/chat/messages/rate

RateChatMessage

Up/down vote an assistant reply. Only valid for role=assistant messages.

Request parameters

Field	Type	Required	Description
message_id	string	yes	—
rating	string	yes	"up" or "down".
note	string	no	Optional user note.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	RateChatMessageData	Response payload.
└message_id	string	Echoed back.
└rating	string	Echoed back.
└created_at	string	ISO8601 UTC.

POST/v1/openapi/chat/recommend-questions

ChatRecommendQuestions

Suggested starter questions for your chat entry screen, regenerated daily from a digest of recent market news. Served from cache — this endpoint never invokes an LLM and is not billed. Each call returns a fresh random subset, so repeated calls give your UI variety.

Not billed and no X-Partner-User required.

An empty questions array with ret=0 means the daily batch is not available yet (or expired) — hide the suggestions UI rather than treating it as an error.

Request parameters

Field	Type	Required	Description
lang	string	no	Language tag: "en" / "en-us", "zh" / "zh-cn" / "zh-hans", "zh-tw" / "zh-hant" / "zh-hk". Case-insensitive. Empty or unrecognized falls back to "en".
count	int32	no	Max questions to return. Default 10, max 50.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	ChatRecommendQuestionsData	Response payload.
└questions	string[]	Randomly ordered subset of the day's batch.
└lang	string	Language actually served after normalization/fallback: "en" / "zh-cn" / "zh-tw".
└generated_at	int64	Unix seconds when the batch was generated.

Example request

curl -X POST https://api.alphio.ai/v1/openapi/chat/recommend-questions \
  -H "Authorization: Bearer pk_live_••••••••••••••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "lang": "en",
    "count": 3
  }'

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "questions": [
      "How could the latest Fed commentary affect rate-cut expectations this summer?",
      "Is NVDA's pullback after earnings a buying opportunity?",
      "What is driving the rally in gold prices this week?"
    ],
    "lang": "en",
    "generated_at": 1781136000
  }
}

Pivot point

Pivot point / support-resistance signals.

POST/v1/openapi/analysis/pivot-point/info

PivotPointInfo

Returns every 神奇九转 + RSI(6) pivot signal (DIP / ALERT) the algorithm fired within the look-back window (default: trailing 1 year of daily bars; override with from/to). Computed server-side from datafabric kline (US / HK / crypto all supported); cached for 5 minutes. Empty `data.list` with `ret=0` means no signal in the window — distinct from a real error.

Request parameters

Field	Type	Required	Description
code	string	yes	Ticker, e.g. "AAPL", "00700", "BTC". Case-insensitive; uppercased server-side.
asset_type	int32	yes	0=stock, 1=etf, 2=crypto.
locale	string	no	Market the ticker belongs to: "US", "HK", "FOREX", "METAL". Case-insensitive; uppercased server-side. Empty defaults to "US". Crypto (asset_type=2) keeps the field for shape consistency but it's inert.
from	string	no	Window start, YYYY-MM-DD (UTC, inclusive). Must be set together with to. The algorithm runs on exactly the [from, to] bars with no warmup preload — the signal math is window-sensitive (RSI warmup, TD-9 counts, FILTER suppression), so to reproduce the App chart's markers pass exactly the bar range the chart has loaded. Both empty = trailing 1 year.
to	string	no	Window end, YYYY-MM-DD (UTC, inclusive). Must be set together with from. Max span 5 years. Windows shorter than 30 bars return "insufficient kline history".

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	AnalysisPivotPointInfoData	Response payload.
└list	AnalysisPivotAlertInfo[]	Filtered signals in CHRONOLOGICAL ASCENDING order. Empty when no signal fired in the look-back window. For the latest signal, take list[list.length-1].
└date	string	Signal date, YYYY-MM-DD (UTC).
└code	string	Echoed ticker, uppercased.
└sign	string	"DIP" (bullish reversal) or "ALERT" (bearish reversal).
└mark	string	"Buy Signal" / "Sell Signal" — human-readable label.
└price	string	Display price with 4-decimal precision. DIP = low × 0.98 (paint below the bar); ALERT = high × 1.03 (paint above).
└ts	int64	Signal timestamp, unix seconds.

Example request

POST https://api.alphio.ai/v1/openapi/analysis/pivot-point/info
{ "code": "AAPL", "asset_type": 0, "locale": "US", "from": "2026-01-01", "to": "2026-07-28" }

Example response

{
  "ret": 0, "msg": "ok",
  "data": {
    "list": [
      {
        "date": "2026-02-09", "code": "AAPL",
        "sign": "ALERT", "mark": "Sell Signal",
        "price": "286.5460", "ts": 1770613200
      },
      {
        "date": "2026-06-09", "code": "AAPL",
        "sign": "DIP", "mark": "Buy Signal",
        "price": "291.7340", "ts": 1781007137
      }
    ]
  }
}

POST/v1/openapi/analysis/pivot-point/signals

PivotPointSignals

Bulk scan / signal screener.

Request parameters

Field	Type	Required	Description
signal_type	int32	yes	0=all, 1=bottom (dip / bottom-reversal), 2=alert (top warning).
page	int32	no	1-indexed.
page_size	int32	no	Items per page.
asset_type	string	no	Numeric string: "0"=stock, "1"=etf, "2"=crypto. Empty = all.
period	int32	no	0=all, 1=15min, 2=30min, 3=1h, 4=2h, 5=4h.
sort_field	int32	no	0=timestamp, 2=volume (1=market_cap is deprecated).
order	string	no	"asc" (default) / "desc".
first_id	string	no	Forward cursor.
last_id	string	no	Backward cursor.
refresh	bool	no	Force-bust cache.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	AnalysisPivotPointSignalsData	Response payload.
└signals	AnalysisDayTradingSignal[]	—
└symbol	string	—
└code	string	—
└name	string	Company name.
└logo	string	—
└price	string	—
└change_ratio	string	—
└timestamp	int64	Unix seconds.
└signal_types	int32[]	Active signal labels.
└period	int32	—
└klines	AnalysisKlinePoint[]	OHLCV + technicals.
└open	double	—
└high	double	—
└low	double	—
└close	double	—
└volume	double	—
└timestamp	int64	Unix seconds.
└ma5	double	—
└ma20	double	—
└rsi6	double	—
└macd	double	—
└macd_signal	double	—
└macd_hist	double	—
└asset_type	int32	—
└volume	string	—
└id	string	Stable row ID for cursor pagination.
└prev_close	string	—
└total	int64	Total rows matching the filter.
└new_add	int64	Rows newly added since last query.

Swingmax

Swing-trade signals.

POST/v1/openapi/analysis/swingmax/signals

SwingmaxSignals

Query open swingmax signals for the given tickers. Returns the SAME rich item shape as /swingmax/stocks (AnalysisSwingmaxStock — with kline, company name/logo, the r1/r2/r3 target ladder, stop loss). Ladder field names match the App swing-max/list payload one-to-one.

The status field is localized. A "lang" BODY PARAM takes priority when set; otherwise the "lang" REQUEST HEADER is used: omit both for English, "zh" / "zh-cn" for Simplified Chinese, "zh-tw" for Traditional Chinese. Every other field (prices, timestamps) is language-independent.

Request parameters

Field	Type	Required	Description
tickers	AnalysisAsset[]	yes	Tickers to query.
└asset_type	int32	no	0=stock, 1=etf, 2=crypto.
└symbol	string	no	Legacy field.
└ticker	string	no	Preferred field.
└locale	string	no	"US" / "HK".
lang	string	no	Localizes the status text. When set it takes PRIORITY over the "lang" request header: "zh" / "zh-cn" = Simplified Chinese, "zh-tw" = Traditional Chinese. Omit/empty to fall back to the header (English by default).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	AnalysisSwingmaxSignalsData	Response payload.
└signals	AnalysisSwingmaxStock[]	Same item shape as /swingmax/stocks — one entry per matched open ticker.
└symbol	string	—
└code	string	—
└company_name	string	—
└logo	string	—
└return	double	Realized return since entry, percent. Weighted over the ladder: 40% sold at Target 2 + 30% sold at Target 3 + the remaining 30% at final exit (unsold parts marked to the latest close).
└entry_price	double	—
└exit_price	double	Final-exit fill price for the remaining position. 0 while the position is open.
└entry_time	string	Entry date string from upstream, e.g. "2026-06-02".
└exit_time	string	Exit date string; empty while the position is open.
└change_ratio	double	—
└kline	AnalysisKlinePointV2[]	Snapshot bars with full OHLC + volume — enough to draw candlesticks.
└close	double	—
└timestamp	int64	Unix seconds.
└open	double	—
└high	double	—
└low	double	—
└volume	double	—
└entry_time_ts	int64	Unix seconds.
└exit_time_ts	int64	Unix seconds; 0 while open.
└target_price	string	Legacy alias of r2_price (Target 2), kept for backward compatibility — prefer the r1/r2/r3_price ladder.
└stop_loss	string	Stop-loss price. The whole remaining position exits if it is hit.
└interval	int32	Signal timeframe: 0=1d, 1=15min, 2=30min, 3=1h, 4=2h, 5=4h.
└side	int32	0=long, 1=short.
└market_cap	string	—
└current_price	string	—
└r1_price	string	Target 1 price — the first (lowest) pivot level above entry. A price milestone only: no partial sell is executed at R1.
└r1_signal_ts	int64	Reserved for shape parity with the App swing-max/list; always 0 on this stock feed (only the crypto pipeline fills R1 triggers).
└r2_price	string	Target 2 price. When first reached, the strategy sells 40% of the position. Same value as the legacy target_price.
└r2_signal_ts	int64	Unix seconds when the price first reached Target 2 (40% partial exit executed); 0 if not reached yet.
└r2_sell_price	string	Fill price of the 40% partial exit at Target 2; empty if not reached yet.
└r3_price	string	Target 3 price — the highest ladder level. When first reached, the strategy sells another 30% of the position.
└r3_signal_ts	int64	Unix seconds when the price first reached Target 3 (30% partial exit executed); 0 if not reached yet.
└r3_sell_price	string	Fill price of the 30% partial exit at Target 3; empty if not reached yet.
└status	string	Server-rendered progress narrative (entry → 40% partial exit at Target 2 → 30% at Target 3 → final close) — same text the App shows on swing-max/list. Localized by the "lang" body param (priority) or "lang" request header: omit both for English, "zh" / "zh-cn" = Simplified Chinese, "zh-tw" = Traditional Chinese. Empty on the closed list (stype≠1).

Example request

POST https://api.alphio.ai/v1/openapi/analysis/swingmax/signals
Authorization: Bearer pk_live_••••••••••••••••••••••••••••
{
  "tickers":[
    {"asset_type":0,"ticker":"AAPL","locale":"US"},
    {"asset_type":0,"ticker":"NVDA","locale":"US"}
  ],
  "lang":"zh-tw"
}

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "signals":[
      {"symbol":"AAPL","code":"AAPL.O","company_name":"Apple Inc","logo":"https://...",
       "return":3.21,"entry_price":187.2,"exit_price":0,"entry_time":"2026-06-02","exit_time":"",
       "change_ratio":3.21,
       "kline":[{"close":190.5,"timestamp":1717286400,"open":188.9,"high":191.2,"low":188.1,"volume":51234567}],
       "entry_time_ts":1717286400,"exit_time_ts":0,"target_price":"210.5","stop_loss":"177.84",
       "interval":0,"side":0,"market_cap":"2.9T","current_price":"193.1",
       "r1_price":"198.6","r1_signal_ts":0,
       "r2_price":"210.5","r2_signal_ts":1719878400,"r2_sell_price":"211.02",
       "r3_price":"224.9","r3_signal_ts":0,"r3_sell_price":"",
       "status":"Booked partial profits @211.02 on 2026-07-01 09:35 ET and riding runners"}
    ]
  }
}

POST/v1/openapi/analysis/swingmax/stocks

SwingmaxStocks

Browse the supported universe. NOTE: only stype=1 returns the OPEN positions pool; any other value returns the removed/closed list. The r1/r2/r3 ladder fields are only filled for stype=1 — the closed list comes from an older store without ladder data, so they are empty/0 there.

Request parameters

Field	Type	Required	Description
stype	int32	yes	GetSwingMaxStocksType. 1=open pool, 2=removed(closed), 3=today, 4=today-open, 5=today-update. Only stype=1 = open pool.
sort_type	int32	no	1=latest, 2=oldest, 3=highest return, 4=lowest return, 5=latest exit, 6=oldest exit, 7=latest entry, 8=oldest entry, 9=highest market cap, 10=lowest market cap, 11=highest potential.
page	int64	no	1-indexed.
size	int32	no	Items per page.
keyword	string	no	Keyword search.
side	int32	no	0=long, 1=short.
trade_status	int32	no	0=not traded, 1=traded, 2=all.
lang	string	no	Localizes the status text. When set it takes PRIORITY over the "lang" request header: "zh" / "zh-cn" = Simplified Chinese, "zh-tw" = Traditional Chinese. Omit/empty to fall back to the header (English by default).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	AnalysisSwingmaxStocksData	Response payload.
└stocks	AnalysisSwingmaxStock[]	—
└symbol	string	—
└code	string	—
└company_name	string	—
└logo	string	—
└return	double	Realized return since entry, percent. Weighted over the ladder: 40% sold at Target 2 + 30% sold at Target 3 + the remaining 30% at final exit (unsold parts marked to the latest close).
└entry_price	double	—
└exit_price	double	Final-exit fill price for the remaining position. 0 while the position is open.
└entry_time	string	Entry date string from upstream, e.g. "2026-06-02".
└exit_time	string	Exit date string; empty while the position is open.
└change_ratio	double	—
└kline	AnalysisKlinePointV2[]	Snapshot bars with full OHLC + volume — enough to draw candlesticks.
└close	double	—
└timestamp	int64	Unix seconds.
└open	double	—
└high	double	—
└low	double	—
└volume	double	—
└entry_time_ts	int64	Unix seconds.
└exit_time_ts	int64	Unix seconds; 0 while open.
└target_price	string	Legacy alias of r2_price (Target 2), kept for backward compatibility — prefer the r1/r2/r3_price ladder.
└stop_loss	string	Stop-loss price. The whole remaining position exits if it is hit.
└interval	int32	Signal timeframe: 0=1d, 1=15min, 2=30min, 3=1h, 4=2h, 5=4h.
└side	int32	0=long, 1=short.
└market_cap	string	—
└current_price	string	—
└r1_price	string	Target 1 price — the first (lowest) pivot level above entry. A price milestone only: no partial sell is executed at R1.
└r1_signal_ts	int64	Reserved for shape parity with the App swing-max/list; always 0 on this stock feed (only the crypto pipeline fills R1 triggers).
└r2_price	string	Target 2 price. When first reached, the strategy sells 40% of the position. Same value as the legacy target_price.
└r2_signal_ts	int64	Unix seconds when the price first reached Target 2 (40% partial exit executed); 0 if not reached yet.
└r2_sell_price	string	Fill price of the 40% partial exit at Target 2; empty if not reached yet.
└r3_price	string	Target 3 price — the highest ladder level. When first reached, the strategy sells another 30% of the position.
└r3_signal_ts	int64	Unix seconds when the price first reached Target 3 (30% partial exit executed); 0 if not reached yet.
└r3_sell_price	string	Fill price of the 30% partial exit at Target 3; empty if not reached yet.
└status	string	Server-rendered progress narrative (entry → 40% partial exit at Target 2 → 30% at Target 3 → final close) — same text the App shows on swing-max/list. Localized by the "lang" body param (priority) or "lang" request header: omit both for English, "zh" / "zh-cn" = Simplified Chinese, "zh-tw" = Traditional Chinese. Empty on the closed list (stype≠1).
└total	int32	—

POST/v1/openapi/analysis/swingmax/open

SwingmaxOpen

Return ALL currently-open positions in a single call (no pagination). Static signals only — no kline, no realtime return, no company name/logo. Cheap, cached ~1 minute.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	AnalysisSwingmaxOpenData	Response payload.
└positions	AnalysisSwingmaxOpenPosition[]	Every currently-open position.
└symbol	string	—
└code	string	—
└buy_price	string	Entry / Buy Target.
└stop_loss	string	—
└target1	string	Sell Target 1 (r2).
└target2	string	Sell Target 2 (r3).
└potential_gain	double	Static: (r3/buy - 1) * 100, percent.
└signal_time	int64	Entry time, unix seconds.
└last_exit_ts	int64	Exit time, unix seconds; 0 when open.
└total	int32	—

Example request

POST https://api.alphio.ai/v1/openapi/analysis/swingmax/open
{}

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "positions":[
      {"symbol":"GME","code":"GME.N","buy_price":"21.715","stop_loss":"20.629",
       "target1":"24.252","target2":"28.152","potential_gain":29.6,
       "signal_time":1647388800,"last_exit_ts":0}
    ],
    "total": 1
  }
}

Whales tracker

Endpoints tracking institutional (13F) and Congressional holdings. entity_type: 1=institution, 2=congress member. seo_name is the stable partner-facing identifier. All return/chart values are decimal fractions (0.012 = +1.2%). Rankings are cached ~10s server-side.

POST/v1/openapi/whales/top-returns

TopReturns

Institutions ranked by the chosen period's return, descending. Institutions only — for congress members use Ranking with entity_type=2.

Request parameters

Field	Type	Required	Description
period	string	yes	"1d" / "1w" / "1m" / "3m" / "1y".
limit	int32	yes	1 – 50.
include	string	no	Comma-separated: "chart" (equity curve) / "holdings" (top_holdings ≤2 tickers + holding_count) / "performance" (sharpe_ratio + mdd) / "returns" (return_1d / return_1w / return_1m / return_1y). Empty = base fields only.
keyword	string	no	Fuzzy entity-name filter (matches names containing the keyword). Empty = no filtering.
sort	string	no	"<field>:<asc\|desc>", one field at a time. Fields: total_return (the requested period's return), sharpe_ratio, return_1d, return_1w, return_1m, return_1y, mdd. Empty = period return, descending. Sorting works regardless of include — include only controls which fields are returned.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesTopReturnsData	Response payload.
└entities	WhalesEntity[]	Ranked by return_value descending by default; sort overrides the order.
└name	string	Entity display name.
└action	string	Currently always "Holding" on ranking endpoints; empty on FollowingRanking.
└return_value	double	Return for the requested period, decimal fraction (0.618 = +61.8%). TopReturnsByAsset always uses the 3m return.
└top_holdings	WhalesHolding[]	Largest positions, tickers only. Only populated when include contains holdings (capped at 2-3 tickers).
└ticker	string	Ticker symbol.
└holding_count	int32	Number of positions in the latest filing. 0 unless include contains holdings.
└chart	WhalesChartPoint[]	Equity-curve points. Only populated when include contains chart.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└avatar	string	CDN avatar URL.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Stable slug — the partner-facing identifier, feed it to DetailsBySeoName.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio. Only populated when include contains performance.
└mdd	double	Maximum drawdown, computed from the equity curve. Positive decimal fraction (0.2 = 20% drawdown). Only populated when include contains performance.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%). Only populated when include contains returns.
└return_1w	double	1-week return, decimal fraction. Only populated when include contains returns.
└return_1m	double	1-month return, decimal fraction. Only populated when include contains returns.
└return_1y	double	1-year return, decimal fraction. Only populated when include contains returns.

POST/v1/openapi/whales/ranking

Ranking

Ranking filtered by entity_type. Query one period (period → data.entities) or up to 4 at once (periods → data.period_groups).

top_holdings is always empty on this endpoint for partner API calls.

Sending both period and periods returns an InvalidArgument error.

Request parameters

Field	Type	Required	Description
period	string	no	Single-period query: "1d" / "1w" / "1m" / "3m" / "1y". Exactly one of period / periods must be set.
periods	string[]	no	Multi-period query: up to 4 unique values from the same set. Response returns one period_groups entry per requested period, in request order.
limit	int32	yes	1 – 50 (applies to each period's list).
include	string	no	Comma-separated: "chart" (mini equity curve per entity) / "performance" (sharpe_ratio + mdd) / "returns" (return_1d / return_1w / return_1m / return_1y).
entity_type	WhalesEntityType	yes	INSTITUTION (1) / CONGRESS (2).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesRankingData	Response payload.
└entities	WhalesEntity[]	Populated for single-period requests.
└name	string	Entity display name.
└action	string	Currently always "Holding" on ranking endpoints; empty on FollowingRanking.
└return_value	double	Return for the requested period, decimal fraction (0.618 = +61.8%). TopReturnsByAsset always uses the 3m return.
└top_holdings	WhalesHolding[]	Largest positions, tickers only. Only populated when include contains holdings (capped at 2-3 tickers).
└ticker	string	Ticker symbol.
└holding_count	int32	Number of positions in the latest filing. 0 unless include contains holdings.
└chart	WhalesChartPoint[]	Equity-curve points. Only populated when include contains chart.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└avatar	string	CDN avatar URL.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Stable slug — the partner-facing identifier, feed it to DetailsBySeoName.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio. Only populated when include contains performance.
└mdd	double	Maximum drawdown, computed from the equity curve. Positive decimal fraction (0.2 = 20% drawdown). Only populated when include contains performance.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%). Only populated when include contains returns.
└return_1w	double	1-week return, decimal fraction. Only populated when include contains returns.
└return_1m	double	1-month return, decimal fraction. Only populated when include contains returns.
└return_1y	double	1-year return, decimal fraction. Only populated when include contains returns.
└period_groups	WhalesRankingPeriodGroup[]	Populated for multi-period requests, in the same order as req.periods.
└period	string	The requested period this group belongs to.
└entities	WhalesEntity[]	Ranking list for this period.
└name	string	Entity display name.
└action	string	Currently always "Holding" on ranking endpoints; empty on FollowingRanking.
└return_value	double	Return for the requested period, decimal fraction (0.618 = +61.8%). TopReturnsByAsset always uses the 3m return.
└top_holdings	WhalesHolding[]	Largest positions, tickers only. Only populated when include contains holdings (capped at 2-3 tickers).
└ticker	string	Ticker symbol.
└holding_count	int32	Number of positions in the latest filing. 0 unless include contains holdings.
└chart	WhalesChartPoint[]	Equity-curve points. Only populated when include contains chart.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└avatar	string	CDN avatar URL.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Stable slug — the partner-facing identifier, feed it to DetailsBySeoName.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio. Only populated when include contains performance.
└mdd	double	Maximum drawdown, computed from the equity curve. Positive decimal fraction (0.2 = 20% drawdown). Only populated when include contains performance.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%). Only populated when include contains returns.
└return_1w	double	1-week return, decimal fraction. Only populated when include contains returns.
└return_1m	double	1-month return, decimal fraction. Only populated when include contains returns.
└return_1y	double	1-year return, decimal fraction. Only populated when include contains returns.

POST/v1/openapi/whales/top-returns-by-asset

TopReturnsByAsset

Reverse-lookup: institutions currently holding a specific ticker, ranked by their 3-month return (descending). return_value is always the 3m return.

Request parameters

Field	Type	Required	Description
asset	WhalesAsset	yes	The ticker to look up.
└asset_type	int32	no	0=stock, 1=etf.
└ticker	string	yes	Ticker symbol, e.g. "AAPL".
└locale	string	no	"US" (default) / "HK".
include	string	no	Comma-separated: "chart" / "holdings" / "performance" / "returns". With holdings, the queried ticker is guaranteed to appear in top_holdings.
limit	int32	no	Defaults to 6 when omitted.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesTopReturnsData	Response payload.
└entities	WhalesEntity[]	Ranked by 3m return, descending.
└name	string	Entity display name.
└action	string	Currently always "Holding" on ranking endpoints; empty on FollowingRanking.
└return_value	double	Return for the requested period, decimal fraction (0.618 = +61.8%). TopReturnsByAsset always uses the 3m return.
└top_holdings	WhalesHolding[]	Largest positions, tickers only. Only populated when include contains holdings (capped at 2-3 tickers).
└ticker	string	Ticker symbol.
└holding_count	int32	Number of positions in the latest filing. 0 unless include contains holdings.
└chart	WhalesChartPoint[]	Equity-curve points. Only populated when include contains chart.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└avatar	string	CDN avatar URL.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Stable slug — the partner-facing identifier, feed it to DetailsBySeoName.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio. Only populated when include contains performance.
└mdd	double	Maximum drawdown, computed from the equity curve. Positive decimal fraction (0.2 = 20% drawdown). Only populated when include contains performance.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%). Only populated when include contains returns.
└return_1w	double	1-week return, decimal fraction. Only populated when include contains returns.
└return_1m	double	1-month return, decimal fraction. Only populated when include contains returns.
└return_1y	double	1-year return, decimal fraction. Only populated when include contains returns.

POST/v1/openapi/whales/following/rankingX-Partner-User required

FollowingRanking

Ranks the entities the calling user follows (their watchlist) by the chosen period's return, descending. Requires X-Partner-User, like the watchlist endpoints.

A user's first-ever call auto-seeds their watchlist with the featured entities from Home.

Request parameters

Field	Type	Required	Description
period	string	yes	"1d" / "1w" / "1m" / "3m" / "1y".
limit	int32	yes	1 – 50. Truncates the sorted list.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesFollowingRankingData	Response payload.
└entities	WhalesEntity[]	Only name, return_value, avatar, entity_type and seo_name are populated here — no action / top_holdings / holding_count / chart / performance metrics.
└name	string	Entity display name.
└action	string	Currently always "Holding" on ranking endpoints; empty on FollowingRanking.
└return_value	double	Return for the requested period, decimal fraction (0.618 = +61.8%). TopReturnsByAsset always uses the 3m return.
└top_holdings	WhalesHolding[]	Largest positions, tickers only. Only populated when include contains holdings (capped at 2-3 tickers).
└ticker	string	Ticker symbol.
└holding_count	int32	Number of positions in the latest filing. 0 unless include contains holdings.
└chart	WhalesChartPoint[]	Equity-curve points. Only populated when include contains chart.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└avatar	string	CDN avatar URL.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Stable slug — the partner-facing identifier, feed it to DetailsBySeoName.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio. Only populated when include contains performance.
└mdd	double	Maximum drawdown, computed from the equity curve. Positive decimal fraction (0.2 = 20% drawdown). Only populated when include contains performance.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%). Only populated when include contains returns.
└return_1w	double	1-week return, decimal fraction. Only populated when include contains returns.
└return_1m	double	1-month return, decimal fraction. Only populated when include contains returns.
└return_1y	double	1-year return, decimal fraction. Only populated when include contains returns.

POST/v1/openapi/whales/institutions/popular-trades

InstitutionsPopularTrades

Most net-bought / net-sold tickers, aggregated across all tracked institutions' latest quarterly (13F) filings and ranked by aggregate share change.

Request parameters

Field	Type	Required	Description
locale	string	yes	"us" = US stocks + ETFs / "hk" = HK stocks.
tab	string	yes	"increase" = largest aggregate share increases (net buying) / "decrease" = largest aggregate decreases (net selling).
limit	int32	yes	1 – 50.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesInstitutionsPopularTradesData	Response payload.
└trades	WhalesPopularTrade[]	One row per ticker, ordered by \|share_change\| (largest net buys first on increase, largest net sells first on decrease).
└ticker	string	Ticker symbol, e.g. "NVDA".
└code	string	Exchange-qualified code, e.g. "NVDA.O".
└name	string	Security display name.
└asset_type	int32	0=stock, 1=etf.
└locale	string	"US" / "HK".
└share_change	double	Net change in shares held vs the previous quarter, summed across all tracked institutions. Positive = net buying, negative = net selling. This is the ranking key.
└holding_mv	double	Total market value (USD) of the position summed across all tracked institutions, per the latest filings.

POST/v1/openapi/whales/details

Details

Full entity detail by id (from any ranking response).

Request parameters

Field	Type	Required	Description
id	int32	yes	≥ 1.
include	string	no	Comma-separated: "chart" (equity curves), "trade_update" (recent trades + last_updated), "current_holdings" (sector distribution). Base fields and positions are always returned.
entity_type	WhalesEntityType	yes	INSTITUTION (1) / CONGRESS (2).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesEntityDetails	Response payload.
└name	string	Entity display name.
└is_watched	bool	Whether the requesting user watches this entity. Always false on partner API calls — no user context is forwarded on this endpoint.
└top20_holding_mv	int64	Aggregate market value (USD) of the entity's 20 largest positions, per the latest filing.
└last_updated	string	Date (YYYY-MM-DD) of the most recent reported portfolio change. Only populated when include contains trade_update.
└holding_count	int32	Number of positions currently held.
└description	string	Short text description of the entity.
└performance	WhalesPerformance	Tracked-portfolio performance stats. Returns are decimal fractions (0.012 = +1.2%).
└return_1d	double	Latest 1-day return, decimal fraction.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio.
└total_return	double	Cumulative return since tracking began, decimal fraction.
└annualized_return	double	Annualized return, decimal fraction.
└charts	WhalesCharts	Equity curves. Only populated when include contains chart.
└strategy	WhalesChartPoint[]	Entity portfolio equity curve.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└sp500	WhalesChartPoint[]	S&P 500 benchmark over the same window.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└trade_updates	WhalesTradeUpdate[]	Portfolio changes from the most recent rebalance/filing. Only populated when include contains trade_update.
└date	string	Rebalance date, YYYY-MM-DD.
└action	string	"buy" / "sell" / "hold" — derived from the weight change (rounded to 2 decimals).
└ticker	string	Ticker symbol, e.g. "NVDA".
└code	string	Exchange-qualified code, e.g. "NVDA.O".
└name	string	Security display name.
└asset_type	int32	0=stock, 1=etf.
└locale	string	"US" / "HK".
└old_percent	double	Portfolio weight (%) before the change.
└new_percent	double	Portfolio weight (%) after the change.
└fill_price	double	Price at the rebalance date.
└current_holdings	WhalesCurrentHoldings	Current portfolio. positions is always returned; sector_distribution requires include=current_holdings.
└sector_distribution	WhalesSectorWeight[]	Sector weights of the current portfolio. Only populated when include contains current_holdings.
└sector	string	Sector name; "other" when unclassified.
└weight	double	Weight of the sector, in %.
└positions	WhalesPosition[]	All current positions.
└ticker	string	Ticker symbol, e.g. "NVDA".
└code	string	Exchange-qualified code, e.g. "NVDA.O".
└name	string	Security display name.
└asset_type	int32	0=stock, 1=etf.
└locale	string	"US" / "HK".
└cost_price	double	Average cost per share.
└current_percent	double	Current portfolio weight (%).
└total_return	double	Cumulative return of the position since entry.
└sector_distribution_desc	string	Server-generated text summary of the sector mix.
└entity_type	int32	1=institution, 2=congress.
└institution_profile	WhalesInstitutionProfile	Only set for institutions (entity_type=1).
└person_name	string	Fund manager / key person name.
└avatar	string	CDN avatar URL.
└profile	string	Manager / institution bio.
└investing_philosophy	string	Investing-philosophy blurb.
└congress_member_info	WhalesCongressMemberInfo	Only set for congress members (entity_type=2).
└avatar	string	Avatar URL.
└party	string	Political party, e.g. "Republican" / "Democrat".
└organization	string	Chamber, e.g. "Senate" / "House".
└faq	WhalesFAQInfo[]	Server-generated FAQ entries derived from the stats above (holding count, returns, AUM).
└question	string	—
└answer	string	—

POST/v1/openapi/whales/details-by-seo-name

DetailsBySeoName

Same as Details but keyed by stable seo_name (from any ranking / search / home response). Preferred when you cached an entity earlier.

Request parameters

Field	Type	Required	Description
seo_name	string	yes	Stable entity slug, min_len 1.
include	string	no	Comma-separated: "chart" (equity curves), "trade_update" (recent trades + last_updated), "current_holdings" (sector distribution). Base fields and positions are always returned.
entity_type	WhalesEntityType	yes	INSTITUTION (1) / CONGRESS (2).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesEntityDetails	Response payload.
└name	string	Entity display name.
└is_watched	bool	Whether the requesting user watches this entity. Always false on partner API calls — no user context is forwarded on this endpoint.
└top20_holding_mv	int64	Aggregate market value (USD) of the entity's 20 largest positions, per the latest filing.
└last_updated	string	Date (YYYY-MM-DD) of the most recent reported portfolio change. Only populated when include contains trade_update.
└holding_count	int32	Number of positions currently held.
└description	string	Short text description of the entity.
└performance	WhalesPerformance	Tracked-portfolio performance stats. Returns are decimal fractions (0.012 = +1.2%).
└return_1d	double	Latest 1-day return, decimal fraction.
└sharpe_ratio	double	Sharpe ratio of the tracked portfolio.
└total_return	double	Cumulative return since tracking began, decimal fraction.
└annualized_return	double	Annualized return, decimal fraction.
└charts	WhalesCharts	Equity curves. Only populated when include contains chart.
└strategy	WhalesChartPoint[]	Entity portfolio equity curve.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└sp500	WhalesChartPoint[]	S&P 500 benchmark over the same window.
└date	string	YYYY-MM-DD.
└value	double	Cumulative return since tracking began, decimal fraction (0.618 = +61.8%).
└trade_updates	WhalesTradeUpdate[]	Portfolio changes from the most recent rebalance/filing. Only populated when include contains trade_update.
└date	string	Rebalance date, YYYY-MM-DD.
└action	string	"buy" / "sell" / "hold" — derived from the weight change (rounded to 2 decimals).
└ticker	string	Ticker symbol, e.g. "NVDA".
└code	string	Exchange-qualified code, e.g. "NVDA.O".
└name	string	Security display name.
└asset_type	int32	0=stock, 1=etf.
└locale	string	"US" / "HK".
└old_percent	double	Portfolio weight (%) before the change.
└new_percent	double	Portfolio weight (%) after the change.
└fill_price	double	Price at the rebalance date.
└current_holdings	WhalesCurrentHoldings	Current portfolio. positions is always returned; sector_distribution requires include=current_holdings.
└sector_distribution	WhalesSectorWeight[]	Sector weights of the current portfolio. Only populated when include contains current_holdings.
└sector	string	Sector name; "other" when unclassified.
└weight	double	Weight of the sector, in %.
└positions	WhalesPosition[]	All current positions.
└ticker	string	Ticker symbol, e.g. "NVDA".
└code	string	Exchange-qualified code, e.g. "NVDA.O".
└name	string	Security display name.
└asset_type	int32	0=stock, 1=etf.
└locale	string	"US" / "HK".
└cost_price	double	Average cost per share.
└current_percent	double	Current portfolio weight (%).
└total_return	double	Cumulative return of the position since entry.
└sector_distribution_desc	string	Server-generated text summary of the sector mix.
└entity_type	int32	1=institution, 2=congress.
└institution_profile	WhalesInstitutionProfile	Only set for institutions (entity_type=1).
└person_name	string	Fund manager / key person name.
└avatar	string	CDN avatar URL.
└profile	string	Manager / institution bio.
└investing_philosophy	string	Investing-philosophy blurb.
└congress_member_info	WhalesCongressMemberInfo	Only set for congress members (entity_type=2).
└avatar	string	Avatar URL.
└party	string	Political party, e.g. "Republican" / "Democrat".
└organization	string	Chamber, e.g. "Senate" / "House".
└faq	WhalesFAQInfo[]	Server-generated FAQ entries derived from the stats above (holding count, returns, AUM).
└question	string	—
└answer	string	—

POST/v1/openapi/whales/home

Home

Static editorial list of featured entities (ARK, Nancy Pelosi, Berkshire Hathaway, Soros, Renaissance, Pershing Square). Empty body.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesHomeData	Response payload.
└items	WhalesHomeInfo[]	Curated, fixed order — not a ranking.
└name	string	Entity display name.
└cover	string	CDN cover-image URL for the home card.
└label	string	Editorial tag; currently always "Featured".
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Feed to DetailsBySeoName.

POST/v1/openapi/whales/search

Case-insensitive substring match over all institution and congress-member names.

Request parameters

Field	Type	Required	Description
keyword	string	yes	min_len 1. Must contain a non-whitespace character.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesSearchData	Response payload.
└items	WhalesSearchInfo[]	Capped at 50 results (institutions prioritized up to 25, remainder congress members).
└name	string	Entity display name.
└entity_type	int32	1=institution, 2=congress.
└seo_name	string	Feed to DetailsBySeoName.

POST/v1/openapi/whales/faq

FAQ

Static product-level FAQ about the Whales tracker, localized via Accept-Language (English default, Chinese supported). Not entity-specific — per-entity FAQ comes in Details.faq. Empty body.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesFAQData	Response payload.
└items	WhalesFAQInfo[]	Fixed question/answer list.
└question	string	—
└answer	string	—

POST/v1/openapi/whales/watchlist/listX-Partner-User required

WatchlistList

List entities the user follows, with their returns across all periods. Requires X-Partner-User.

A user's first-ever call auto-seeds their watchlist with the featured entities from Home. If they later unfollow everything, the list stays empty.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	WhalesWatchlistListData	Response payload.
└items	WhalesWatchlistItem[]	One row per followed entity.
└name	string	Entity display name.
└entity_type	int32	1=institution, 2=congress.
└return_1d	double	1-day return, decimal fraction (0.012 = +1.2%).
└return_7d	double	7-day return, decimal fraction.
└return_1m	double	1-month return, decimal fraction.
└return_3m	double	3-month return, decimal fraction.
└return_1y	double	1-year return, decimal fraction.
└avatar	string	CDN avatar URL.
└seo_name	string	Stable slug for DetailsBySeoName.

POST/v1/openapi/whales/watchlist/createX-Partner-User required

WatchlistCreate

Add an entity to the calling user's watchlist. Requires X-Partner-User.

Request parameters

Field	Type	Required	Description
id	int32	yes	Internal numeric entity id, ≥ 1.
entity_type	WhalesEntityType	yes	INSTITUTION (1) / CONGRESS (2).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success.
msg	string	Status / error message.

POST/v1/openapi/whales/watchlist/deleteX-Partner-User required

WatchlistDelete

Remove an entity from the calling user's watchlist. Requires X-Partner-User.

Request parameters

Field	Type	Required	Description
id	int32	yes	Internal numeric entity id, ≥ 1.
entity_type	WhalesEntityType	yes	INSTITUTION (1) / CONGRESS (2).

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success.
msg	string	Status / error message.

Market data

Raw market data endpoints powering Chat card details. Keyed by symbol; partner UIs typically fetch these on-demand when expanding a card.

POST/v1/openapi/data/valuation

DataValuation

Historical valuation time-series.

Request parameters

Field	Type	Required	Description
ticker	string	yes	e.g. "AAPL".
valuation_type	int32	yes	EValuationType. 0=PE / 1=PB / 2=PS / 3=Price-to-FCF / 4=EV-EBITDA / 5=Price-to-OCF / 6=FCF-Yield / 7=EV-EBIT.
is_forward	bool	no	true=forward, false=trailing (default).
from	string	no	YYYY-MM-DD. Default last 1Y.
to	string	no	YYYY-MM-DD. Default today.
locale	string	no	"US" / "HK".

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DataValuationData	Response payload.
└valuation	DataValuationItem[]	Time series.
└t	string	Date (YYYY-MM-DD).
└v	string	Valuation value.
└variance_info	DataVarianceInfo	Five reference bands.
└mean	string	—
└variance	string	—
└overvalued	string	mean + 1σ.
└undervalued	string	mean − 1σ.
└strongly_overvalued	string	mean + 2σ.
└strongly_undervalued	string	mean − 2σ.

Example request

POST https://api.alphio.ai/v1/openapi/data/valuation
{ "ticker":"AAPL", "valuation_type":0, "from":"2025-06-01", "to":"2026-06-01", "locale":"US" }

Example response

{
  "ret": 0, "msg": "ok",
  "data": {
    "valuation":[{"t":"2025-06-01","v":"28.5"},{"t":"2025-06-02","v":"28.7"}, ...],
    "variance_info":{
      "mean":"30.2","variance":"3.1",
      "overvalued":"33.3","undervalued":"27.1",
      "strongly_overvalued":"36.4","strongly_undervalued":"24.0"
    }
  }
}

POST/v1/openapi/data/rating

DataRating

Analyst ratings.

Request parameters

Field	Type	Required	Description
ticker	string	yes	e.g. "AAPL".
from	string	no	YYYY-MM-DD.
to	string	no	YYYY-MM-DD.
page	int32	no	1-indexed.
size	int32	no	1 – 100, default 20.
locale	string	no	"US" / "HK".

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DataRatingData	Response payload.
└results	DataStockAnalysis	—
└ticker	string	—
└code	string	—
└analyses	DataAnalysisItem[]	—
└rating_analyst	string	—
└rating_date	string	—
└rating_action	string	"upgrade" / "downgrade" / "maintain" / "initiate".
└rating_analyst_stars	double	—
└rating_analyst_firm	string	—
└rating_price_target	string	—
└rating	string	e.g. "buy" / "hold".
└rating_upside	double	—
└analysis_summary	DataAnalysisSummary	Aggregate snapshot.
└code	string	—
└symbol	string	—
└average_price_target	string	—
└buy	int32	Count of buy ratings.
└content	string[]	Highlight bullets.
└highest_price_target	string	—
└hold	int32	Count of hold ratings.
└lowest_price_target	string	—
└pagination	DataPagination	—
└current_page	int32	—
└total_pages	int32	—
└total_items	int32	—

POST/v1/openapi/data/snapshot

DataSnapshot

Financial-metric snapshot (per-quarter or annual).

Request parameters

Field	Type	Required	Description
code	string	yes	—
type	int32	yes	EFinancialIndicatorsType. 1=EPS / 2=Revenue / 3=ROE / 4=Gross Margin / 5=Net Margin / 6=Current Ratio / 7=Debt to Equity / 8=Operating Margin.
report_type	int32	yes	FinanceReportType. 1=annual / 2=quarterly.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DataSnapshotData	Response payload.
└columns	DataSnapshotColumn[]	Each column = one metric series.
└name	string	—
└values	DataSnapshotValue[]	One cell per period.
└title	string	e.g. "Q1 2026".
└value	double	—
└cur_type	string	Currency / unit.
└valid	bool	false → missing data; render as "—".

POST/v1/openapi/data/kline

DataKline

OHLCV bars.

Request parameters

Field	Type	Required	Description
tickers	WhalesAsset[]	yes	Max 20 per request.
└asset_type	int32	no	SymbolType: 0=stock, 1=etf, 2=crypto, 3=commodity, 4=forex, 5=perp.
└ticker	string	no	e.g. "TSLA".
└locale	string	no	"US" / "HK".
from	string	no	YYYY-MM-DD (US-Eastern) or unix seconds.
to	string	no	YYYY-MM-DD (US-Eastern) or unix seconds.
multiplier	int32	no	e.g. 1, 5, 15.
timespan	int32	no	TimespanOpt. 2=minute, 3=hour, 4=day, 5=week, 6=month, 7=quarter, 8=year. Values outside 2–8 are rejected.
limit	int32	no	Max 1000. Default 500.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DataKlineData	Response payload.
└series	DataKlineSeries[]	One series per requested ticker.
└ticker	string	—
└asset_type	int32	—
└points	DataKlinePoint[]	OHLCV bars. Numbers are strings to avoid precision loss.
└open	string	—
└high	string	—
└low	string	—
└close	string	—
└volume	string	Traded value (turnover) for the bar — per proto this is 成交额, not share count.
└timestamp	int64	Unix seconds.

Example request

POST https://api.alphio.ai/v1/openapi/data/kline
{
  "tickers":[ { "asset_type":0, "ticker":"TSLA", "locale":"US" } ],
  "from":"2026-06-09", "to":"2026-07-09",
  "multiplier":1, "timespan":4, "limit":30
}

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "series": [
      {
        "ticker": "TSLA",
        "asset_type": 0,
        "points": [
          {"open":"391.09","high":"396.14","low":"388.42","close":"394.26",
           "volume":"58231290","timestamp":"1783486800"}
        ]
      }
    ]
  }
}

POST/v1/openapi/data/price-prediction

DataPricePrediction

Historical OHLC bars backing the price-prediction card — no forecast fields in the payload itself. Request is a discriminated union by ticker_type; response has matching stock_data / crypto_data.

Request parameters

Field	Type	Required	Description
ticker_type	string	yes	"stock" / "etf" / "" → stock branch; "crypto" → crypto branch.
stock	DataPricePredictionStockReq	no	Required when ticker_type is stock / etf / empty.
└code	string	no	Ticker, e.g. "AAPL".
└multiplier	int32	no	Time multiplier.
└timespan	int32	no	TimespanOpt. 2=minute, 3=hour, 4=day, 5=week, 6=month, 7=quarter, 8=year.
└timestamp	int64	no	Anchor end-time (unix seconds). Empty = now.
└count	int32	no	Bars to return. Max 5000, recommended 800.
└locale	string	no	"US" / "HK".
crypto	DataPricePredictionCryptoReq	no	Required when ticker_type = "crypto".
└type	int32	no	QueryType. 1=crypto spot, 2=etf, 3=crypto derivative (HL perps).
└symbol	string	no	—
└multiplier	int32	no	—
└timespan	int32	no	TimespanOpt. 2=minute, 3=hour, 4=day, 5=week, 6=month, 7=quarter, 8=year.
└limit	int32	no	—
└start_time	int64	no	Unix seconds.
└end_time	int64	no	Unix seconds.
└symbol_list	string[]	no	Batch query — per-symbol series come back in crypto_data.infos.
└locale	string	no	Source platform for multi-source assets, e.g. "HYPERLIQUID". Empty = default source.

Response fields

Field	Type	Description
ret	int32	Business return code. 0 = success, non-zero = error code (see Errors).
msg	string	Human-readable status / error message. "ok" on success.
data	DataPricePredictionData	Response payload.
└ticker_type	string	Echoed back.
└stock_data	DataPricePredictionStockData	Present on the stock branch.
└points	DataPricePredictionStockPoint[]	Historical bars, oldest first.
└code	string	—
└close	double	—
└high	double	—
└low	double	—
└transactions	int64	Share volume (per proto: 交易量).
└open	double	—
└timestamp	int64	Unix seconds.
└volume	double	Traded value / turnover (per proto: 成交额), not share count.
└vwap	double	Volume-weighted average price.
└otc	bool	—
└pre_close	double	Previous-period values (pre_* mirror the base fields).
└pre_high	double	—
└pre_low	double	—
└pre_transactions	int64	—
└pre_open	double	—
└pre_timestamp	int64	—
└pre_volume	double	—
└pre_vwap	double	—
└symbol	string	—
└last_time	int64	Unix seconds.
└crypto_data	DataPricePredictionCryptoData	Present on the crypto branch.
└points	DataPricePredictionCryptoPoint[]	Bars for the primary symbol.
└high	double	—
└open	double	—
└low	double	—
└close	double	—
└timestamp	int64	Unix seconds.
└volume	int64	Legacy integer volume — kept for old clients only.
└volume_decimal	double	Preferred: float volume (needed for fractional assets like HL perps).
└infos	map<string, DataPricePredictionCryptoSeries>	Per-symbol series when symbol_list was provided.

Example request

POST https://api.alphio.ai/v1/openapi/data/price-prediction
{
  "ticker_type":"stock",
  "stock":{ "code":"AAPL", "multiplier":1, "timespan":4, "count":800, "locale":"US" }
}

Example response

{
  "ret": 0,
  "msg": "ok",
  "data": {
    "ticker_type": "stock",
    "stock_data": {
      "points": [
        {"code":"AAPL","close":195.5,"open":194.2,"high":196.1,"low":193.8,
         "timestamp":1717286400,"volume":48230000.0,"vwap":195.1,"otc":false}
      ],
      "last_time": 1717286400
    }
  }
}

POST/v1/openapi/data/screener/stock

DataScreenerStock

Stock screener. Request / response follow the upstream datafabric schema (chatfinbot.datafabric.v1.SelectStocksReq / SelectStocksRsp). Contact us for the full schema, or reuse a screenId returned by a Chat card.

POST/v1/openapi/data/screener/etf

DataScreenerETF

ETF screener. Uses chatfinbot.datafabric.v1.SelectEtfsReq / SelectEtfsRsp upstream.

POST/v1/openapi/data/screener/crypto

DataScreenerCrypto

Crypto screener. Uses chatfinbot.datafabric.v1.SelectCryptosReq / SelectCryptosRsp upstream.