赛事排行榜 API 对接说明
Leaderboard API Handoff
技术及产品联调版 · 2026 年 11 月 10 日。文档中的端点、鉴权及正式收盘接口是供双方确认的方案。现有网站接口仍返回演示数据。
Engineering and product handoff · 10 November 2026. Endpoint paths, authentication and the official closing feed are proposals for joint approval. The website currently serves demo data.
01 / CONNECTION
连接方式与接口 / Connection and endpoints
AstralX 提供只读数据源。赛事网站服务端使用专用凭证取数、映射和校验，发布仅含已授权字段的快照。建议 AstralX 提供独立沙盒与生产 HTTPS 地址以及对应的赛事 ID。
下表的 /v1/… 路径和 Bearer Token 是拟定方案。AstralX 如已有私有 API，可提供等价字段及映射，双方再确认最终契约。凭证经双方约定的安全渠道交换，仅保存在服务端。
AstralX provides a read-only source. The competition server retrieves and validates it with dedicated credentials, then publishes a snapshot containing authorized fields. Provide separate HTTPS base URLs and competition IDs for sandbox and production.
The /v1/… paths and bearer token are proposed. An existing private AstralX API can be used if its fields map to the same semantics. Exchange credentials through an agreed secure channel and keep them server-side.
| 路径 / Path | 中文用途 | Purpose |
|---|---|---|
GET /v1/competitions/{competitionId}/rankings | AstralX 拟提供的当前排名。每次返回完整快照，至少包含前 20 名（如不足则返回全部符合资格者）。 | Proposed AstralX current feed. Return a full snapshot with the top 20, or all eligible entrants if fewer. |
GET /v1/competitions/{competitionId}/rankings/previous-24h | AstralX 拟提供的独立收盘数据。返回最近完整区间的权威收盘前 20 名及起止时间。 | Proposed independent AstralX closing feed. Return the authoritative top 20 at the latest closed period with its time boundaries. |
GET /api/rankings | 赛事官网供浏览器调用。现有响应为 20 个虚构账户，mode: "demo"、asOf: null。正式上线需要接入和配置后才返回 live。 | Website browser endpoint. It currently returns 20 fictional accounts with mode: "demo" and asOf: null. Provider integration and launch configuration are required before it serves live. |
GET /api/rankings/previous-24h | 赛事官网现有独立模拟收盘快照，固定 20 条。区间为已结束的 UTC 自然日。接入正式收盘源时须更新网站路由及预览专用解析逻辑。 | Existing website endpoint for a simulated UTC day close with exactly 20 rows. The route and demo-only client parser need live support for the official historical feed. |
GET /api/competition-status | 赛事官网开赛状态。包含 startDate、endDate、timeZone、startAt、endAt、started、serverTime。 | Website status endpoint with the date window, time zone, exact timestamps, start state and server clock. It is managed on the competition site. |
02 / SCHEMA
实时快照字段 / Live snapshot fields
正式成功响应使用 JSON。以下字段均为必填，未知信息按约定提供 null 或空数组。所有对象仅接受列出的键。OpenAPI 可导入 Postman 或 Swagger 工具。
The successful live response is JSON. All listed keys are required, with the specified null or empty-array forms for unknown metadata. Objects accept only the declared keys. Import the OpenAPI file into Postman or Swagger tooling.
| 字段 / Field | 中文约束 | Constraints |
|---|---|---|
mode | 正式快照固定 "live"。 | Official snapshots use "live". |
asOf | 来源数据截至时间，RFC 3339，必须含时区。建议 UTC Z，小数秒最多三位。重试时保留原值。 | Source observation time in RFC 3339 with an explicit zone. Prefer UTC Z, with at most three fractional digits. Preserve it on retry. |
sequence | 1 至 9,007,199,254,740,991 的安全整数。同一赛事递增，新内容用新序号；同序号的时间和内容保持一致。 | Safe integer from 1 to 9,007,199,254,740,991. Increase it for new content. Repeats preserve timestamp and payload. |
competitionId | 稳定的赛事 ID。1–80 个 ASCII 字母、数字、下划线或连字符，与路径及环境配置一致。 | Stable competition ID. Use 1–80 ASCII letters, digits, underscores or hyphens. Match the path and environment configuration. |
currency · initialEquity | 固定 "USD"。初始资金为正数，同一赛事保持一致。现有配置为 10000，正式值由双方确认。 | Currency is "USD". Starting equity is positive and fixed per competition. The current setup uses 10000, subject to joint confirmation. |
entries[] | 1–1000 条，按总收益率降序。rank 从 1 连续编号。无可显示记录时建议返回 HTTP 204。 | 1–1,000 rows in descending return order. rank is contiguous from 1. HTTP 204 is proposed when there are no displayable entries. |
entries[].id · rank · alias | 稳定、唯一的公开匿名 ID，字符规则同赛事 ID。名次按官方顺序编号。公开昵称 1–80 字符，拒绝控制字符、邮箱及尖括号。 | Stable, unique pseudonymous ID with the same format as the competition ID. Rank follows the official order. Display alias has 1–80 characters. Exclude control characters, emails and angle brackets. |
countryCode · lots | 可公开的 ISO 3166-1 alpha-2 大写码或 null，如 GB、HK。标准手数是非负 JSON 数字或 null。0 仅用于已知零手。 | Approved uppercase ISO 3166-1 alpha-2 code or null, e.g. GB or HK. Lots are a nonnegative JSON number or null. Use 0 only for known zero volume. |
totalReturnPct · equity | 有限 JSON 数字。收益率 12.5 表示 +12.5%。净值为 USD，允许负数收益及亏损。 | Finite JSON numbers. A return of 12.5 displays as +12.5%. Equity is in USD. Negative returns and P&L are valid. |
instruments[] | 当前接收端要求 1–6 项，symbol 不重复。每项包含 symbol、双语 label: {zh,en}（每种最多 80 字符）、USD pnl 和百分点 contributionPct。 | The current receiver accepts 1–6 unique symbol values. Each row has symbol, bilingual label: {zh,en} (up to 80 characters each), USD pnl and contributionPct in percentage points. |
avatar | {url, consented}。缺少展示许可时用 {"url":null,"consented":false}。 | {url, consented}. Use {"url":null,"consented":false} without display permission. |
strategy | {status, summary, basedOn, asOf}。pending 时后三项为 null；ready 时提供各不超过 1,200 字符的中英摘要、"trade_records" 和记录截至时间。 | {status, summary, basedOn, asOf}. In pending, the last three values are null. In ready, supply approved zh/en summaries up to 1,200 characters each, "trade_records", and the underlying record cutoff. |
socials[] | 0–4 项，每个平台只允许一次。每项为 {platform,url,consented}。支持 x、telegram、youtube、instagram。无授权时可传 []。 | 0–4 objects, at most one per platform, each {platform,url,consented}. Supports x, telegram, youtube and instagram. Use [] if none are authorized. |
当前品种代码仅接受 BTC、ETH、XAUUSD、WTI、NAS100、EURUSD。赛事支持比赛账户内的品种，因此上线前请 AstralX 提供完整代码表与双语名称，由赛事网站更新验证规则。超出清单的盈亏需一并对账。
The current receiver accepts BTC, ETH, XAUUSD, WTI, NAS100 and EURUSD. The competition allows instruments available on the competition account. AstralX should provide the full symbol registry and bilingual labels so the site can update validation and reconcile every instrument.
03 / PRODUCT RULES
收益、排名与收盘 / Returns, ranks and close
正式排名由 AstralX 提供。现有草案按截止时账户净值排名；同一起始资金且无资金流动时，这与总收益率降序等价。名次并列处理、有效交易门槛、取消资格和最终审核应由赛事双方确认。
每个品种贡献为净盈亏除以起始资金再乘 100，单位是百分点。请确认浮盈、已实现盈亏、佣金、点差、资金费及转换汇率，避免同一费用重复计算。若涉及入出金、奖励信用或不能归属品种的调整，请先确认计算与字段扩展。
AstralX supplies the authoritative rank. The published draft ranks by cutoff equity, equivalent to descending return with equal starting equity and no cash flows. The teams must agree tie breaks, qualifying volume, disqualifications and final review.
Instrument contribution is net P&L divided by initial equity and multiplied by 100. The unit is percentage points. Agree how open P&L, realized P&L, commission, spreads, funding and conversion rates are treated. Define handling of deposits, withdrawals, award credits and adjustments that cannot be attributed to an instrument before launch.
instrument.contributionPct = instrument.pnl / initialEquity × 100
totalReturnPct = Σ instrument.contributionPct
equity = initialEquity + Σ instrument.pnl当前接收端对上述每项等式的绝对差容忍度为 0.000001。请保留计算精度，页面再显示两位小数。快照里昵称和账户 ID 应保持稳定，收益相同也须由上游给出唯一的顺序。
独立收盘响应仅含 mode、periodStart、periodEnd 和四字段 entries[]（id、rank、alias、totalReturnPct）。建议采用 UTC 00:00 的完整 24 小时区间，起点含、终点不含。双方需确认首尾不完整交易日、收盘更正和最终奖项审核的数据发布规则。
The current receiver allows absolute error up to 0.000001 for each equation. Preserve computational precision and round only for display. Keep aliases and IDs stable. The provider should specify a unique order when returns tie.
The separate closing payload contains only mode, periodStart, periodEnd and rows with id, rank, alias and totalReturnPct. The suggested period is one completed UTC midnight-to-midnight day, inclusive start and exclusive end. Agree partial opening/closing days, corrections and release of verified final results.
04 / OPERATIONS
更新、异常与隐私 / Freshness, failures and privacy
更新与故障
- 当前排行榜页每 10 秒请求一次，前十名逐字显示，客户端请求超时为 4.5 秒。官网首页开赛后按 5 秒轮询，最多显示前 20 名，首页请求超时 8 秒。演示快照自身按 5 秒时间桶变化。
- 建议双方按每赛事单个服务端采集任务、约每 5 秒一份快照联调，约 12 请求/分钟，与浏览器刷新隔离。请 AstralX 确认实际限额、延迟、时钟同步和是否需要不同频率。
- 正式首页要求已开赛且
asOf ≥ startAt，数据最多旧 20 秒、最多领先服务器时钟 5 秒。榜单页已有 20 秒的过期判定。过期或请求失败时显示延迟并保留最近有效数据；无有效数据时显示等待状态。 - 服务端需拒绝倒序时间、重复 ID、同序号变更、无效结构和无法对账的数据。整份快照校验通过才替换，不拼接部分新旧数据。
Refresh and failure handling
- The rankings page polls every 10 seconds, types the top ten into fixed rows, and aborts requests after 4.5 seconds. The official home polls every 5 seconds and displays up to 20 after start, with an 8-second request timeout. The demo source uses separate five-second time buckets.
- Start sandbox integration with one server-side fetcher per competition, targeting one snapshot every 5 seconds or about 12 requests per minute. Keep it independent of browser traffic. Confirm provider limits, latency, clock synchronization and the agreed cadence.
- The official home requires competition start and
asOf ≥ startAt, with a maximum age of 20 seconds and up to 5 seconds of future clock skew. The ranking page already uses a 20-second stale threshold. Label failures or old data and retain the latest verified snapshot. Show a waiting state when none is valid. - Reject earlier timestamps, duplicate IDs, changed payloads with the same sequence, invalid structure and unreconciled data. Replace the snapshot as one unit after validation.
| 拟定状态 / Proposed | 处理方式 | Handling |
|---|---|---|
200 · 204 | 200 提供完整快照。204 无正文，表示没有可发布数据或尚无已结束区间。 | 200 returns a complete snapshot. 204 has no body and indicates no publishable entries or no closed period. |
401 · 403 · 404 | 检查凭证、权限或赛事 ID，通知值班负责人。错误体只提供 error、message。 | Check credentials, scope or competition ID and alert the owner. Error bodies expose only error and message. |
429 · 500 · 503 | 429 遵守 Retry-After。上游超时及暂时故障使用有上限的退避，记录时间、状态和序号，保护凭证及交易明细。 | Honor Retry-After for 429. Use bounded backoff for timeouts and transient errors. Log status, time and sequence while protecting secrets and trade details. |
可公开资料
- 报名编号或邮箱与平台 UID、比赛账户、匿名公开 ID 的映射仅在双方受限服务端核验。公开快照排除邮箱、手机号、真实账户号、凭证、订单和原始交易记录。
- 头像须经授权，使用受信任的公开 HTTPS 域名或站内
/assets/trader-avatars/图片。HTTPS URL 不带凭证、端口、查询参数、片段或内网/IP 主机。 - 社媒是选填，核验归属及展示授权后才能公开。链接使用白名单域名的 HTTPS 主页地址，且不带查询参数、片段或凭证。撤回授权后从下一份公开快照移除。
- 策略摘要须以授权交易记录为依据，注明观察范围并经人工核对。缺少材料或授权时保持
pending。
Public profile data
- Verify registration-to-platform UID, competition account and public ID mappings on restricted servers. Public snapshots exclude emails, phones, real account numbers, credentials, orders and raw trade records.
- Use consented public HTTPS avatar URLs on approved hosts or site-hosted images under
/assets/trader-avatars/. External URLs exclude credentials, ports, queries, fragments and internal/IP hosts. - Social links are optional. Verify ownership and permission before displaying an approved HTTPS profile link, with no queries, fragments or credentials. Remove revoked links from the next public snapshot.
- Strategy summaries need authorized trade records, a clear observation window and human review. Use
pendingwhen permission or evidence is unavailable.
04A / LINK RULES
公开链接校验 / Public link validation
社媒 URL 最长 512 字符，头像 URL 最长 2,048 字符。社媒 URL 仅接受下表域名，需使用可公开的本人资料页。两种链接的解码路径都不得包含邮箱。站内头像文件支持 PNG、JPEG、WebP、AVIF、GIF。
Social URLs are limited to 512 characters and avatar URLs to 2,048. Social URLs must be public profile pages on the exact allowlisted hosts below. Decoded paths for either kind of link must exclude email addresses. Local avatars support PNG, JPEG, WebP, AVIF and GIF.
| 平台 / Platform | 允许的域名 / Allowed HTTPS hosts | |
|---|---|---|
x | x.com, www.x.com, twitter.com, www.twitter.com | |
telegram | t.me, telegram.me | |
youtube | youtube.com, www.youtube.com, youtu.be | |
instagram | instagram.com, www.instagram.com | |
05 / SANDBOX
可复制样例 / Copyable examples
下面的 URL、赛事 ID 和时间均用于联调示例。请替换 ASTRALX_BASE_URL、ASTRALX_READ_TOKEN 及 COMPETITION_ID，凭证只在受限环境变量中配置。
URLs, IDs and timestamps below are for sandbox examples. Set ASTRALX_BASE_URL, ASTRALX_READ_TOKEN and COMPETITION_ID in a restricted environment.
curl --fail-with-body --max-time 8 \
--header "Authorization: Bearer ${ASTRALX_READ_TOKEN}" \
--header 'Accept: application/json' \
"${ASTRALX_BASE_URL}/v1/competitions/${COMPETITION_ID}/rankings"
curl --fail-with-body --max-time 8 \
--header "Authorization: Bearer ${ASTRALX_READ_TOKEN}" \
--header 'Accept: application/json' \
"${ASTRALX_BASE_URL}/v1/competitions/${COMPETITION_ID}/rankings/previous-24h"实时响应 / Live response · sample-live.json
{
"mode": "live",
"asOf": "2026-12-15T12:00:05Z",
"sequence": 42,
"competitionId": "wutc-sandbox",
"currency": "USD",
"initialEquity": 10000,
"entries": [
{
"id": "sample-01",
"rank": 1,
"alias": "Sample Atlas",
"countryCode": "GB",
"lots": 15.25,
"avatar": {
"url": null,
"consented": false
},
"strategy": {
"status": "pending",
"summary": null,
"basedOn": null,
"asOf": null
},
"totalReturnPct": 12.5,
"equity": 11250,
"instruments": [
{
"symbol": "BTC",
"label": {
"zh": "比特币",
"en": "Bitcoin"
},
"pnl": 800,
"contributionPct": 8.0
},
{
"symbol": "ETH",
"label": {
"zh": "以太坊",
"en": "Ethereum"
},
"pnl": 450,
"contributionPct": 4.5
}
],
"socials": []
},
{
"id": "sample-02",
"rank": 2,
"alias": "Sample Birch",
"countryCode": null,
"lots": 0,
"avatar": {
"url": null,
"consented": false
},
"strategy": {
"status": "pending",
"summary": null,
"basedOn": null,
"asOf": null
},
"totalReturnPct": 0.0,
"equity": 10000,
"instruments": [
{
"symbol": "XAUUSD",
"label": {
"zh": "黄金 CFD",
"en": "Gold CFD"
},
"pnl": 0,
"contributionPct": 0.0
}
],
"socials": []
},
{
"id": "sample-03",
"rank": 3,
"alias": "Sample Cedar",
"countryCode": "HK",
"lots": null,
"avatar": {
"url": null,
"consented": false
},
"strategy": {
"status": "pending",
"summary": null,
"basedOn": null,
"asOf": null
},
"totalReturnPct": -3.4,
"equity": 9660,
"instruments": [
{
"symbol": "ETH",
"label": {
"zh": "以太坊",
"en": "Ethereum"
},
"pnl": -340,
"contributionPct": -3.4
}
],
"socials": []
}
]
}收盘响应 / Closing response · sample-previous-24h.json
{
"mode": "live",
"periodStart": "2026-12-14T00:00:00.000Z",
"periodEnd": "2026-12-15T00:00:00.000Z",
"entries": [
{
"id": "sample-01",
"rank": 1,
"alias": "Sample Atlas",
"totalReturnPct": 9.8
},
{
"id": "sample-02",
"rank": 2,
"alias": "Sample Birch",
"totalReturnPct": 0
},
{
"id": "sample-03",
"rank": 3,
"alias": "Sample Cedar",
"totalReturnPct": -2.15
}
]
}06 / GO LIVE
双方验收与上线 / Joint acceptance and launch
- AstralX 产品确认。确定赛事 ID、2026 年 12 月 14–27 日（GMT）的精确开赛和截止时刻、账户范围、完整品种表、数据计算和最终排名发布口径。现有网站的
startAt和endAt仍为空。 - AstralX 技术交付。提供沙盒和生产端点、只读凭证交接方式、限额、维护窗口、错误约定和双方联络人，并给出至少两份连续快照与一份收盘快照。
- 赛事网站接入。开发服务端授权、账户映射、校验、缓存和监控。上线切换时，用正式赛事 ID 初始化榜单状态，或显式清除演示快照。现有客户端会阻止不同
competitionId或初始资金覆盖先前状态。赛事网站还需同步更新正式页面标题、收盘解析与结束后的展示状态。 - 共同验收。覆盖未开赛、开赛待首包、有效实时前十/前二十、空榜、并列、亏损、授权撤回、过期或顺序倒退、限流与恢复、收盘及赛后审核。核对中英文端一致及公开响应字段。最后发布经过确认的截止时间和正式状态。
- AstralX product approval.Confirm event ID, exact start and cutoff times within 14–27 December 2026 GMT, account scope, full symbol registry, scoring and publication policy. The current site's
startAtandendAtare null. - AstralX engineering handover.Provide sandbox and production endpoints, secure credential exchange, limits, maintenance windows, error conventions and an escalation contact. Supply at least two consecutive snapshots and one closing snapshot.
- Competition site integration.Implement provider authorization, account mapping, validation, caching and monitoring. Initialize the board with the official competition ID or explicitly clear the demo seed on cutover. The existing client rejects replacement across different
competitionIdor initial equity. Update the official title, closing parser and post-close display state. - Joint acceptance.Test pre-start, awaiting first update, live top ten/top twenty, no entries, ties, negative P&L, consent withdrawal, stale or out-of-order data, rate limiting and recovery, the cutoff and final review. Compare both language editions and the public field projection. Publish the confirmed cutoff and launch state.