市場數據 API
公開、只讀嘅 JSON 數據：HiMarket 匯總卡價 — 香港市場魔法風雲會同符文戰場嘅最低售價、最高買取價同每日歷史。
這是什麼
HiMarket 以兩個公開 JSON 端點發佈匯總市場價格，供價格追蹤網站、研究者同任何想知道香港卡價嘅人使用。唔需要帳戶或 API key。呢度所有數據都係市場頁面已經顯示嘅匯總 — 冇買家、賣家、帳戶或訂單資料。
使用條款提到「只可經由我們明確提供嘅介面作自動化存取」— 指嘅就係呢個介面。整合之前請先閱讀下面嘅使用條件。抓取卡牌頁面或其他路徑係唔容許嘅。
市場快照
GET https://www.himarket.hk/api/public/v1/market?game=riftbound
每個「印刷版本 × 語言 × 表面 × 品相」組合，只要而家有在售價或買取價，就會有一行。game 係必填：riftbound 或 mtg。
| 欄位 | 意思 |
|---|---|
printingId | HiMarket 印刷版本 id：系列代號 + 收藏編號（ogn-039），符文戰場加 rb- 前綴（rb-ogn-039）。 |
cardName | 標準英文卡名。 |
set、collectorNumber | 同一身份，分開兩欄。 |
language | 語言代號：en、zht（繁體中文）、zhs（簡體中文）、ja、ko、fr、de、es、pt、it、ru 等。 |
finish | nonfoil、foil 或 etched。 |
condition | NM（Near Mint）、SP（Slightly Played）或 MP（Moderately Played）。 |
lowestAskHkd | 呢個組合目前最低在售價（港幣）；冇貨在售就係 null。 |
highestBidHkd | 目前最高買取價（港幣）；冇人買取就係 null。 |
updatedAt | 呢個印刷版本嘅匯總最後重新計算嘅時間（ISO 8601）。 |
url | 呢個印刷版本嘅 HiMarket 卡牌頁面 — 請用嚟做回連。 |
preorder | 該系列仍係有效預購系列時為 true（售價係預售貨品）。 |
外層帶有 version、game、currency（HKD）、snapshotAt（背後快照最後更新時間）同 generatedAt。回應會快取 15 分鐘。
價格歷史
GET https://www.himarket.hk/api/public/v1/history?printingId=rb-ogn-039
單一印刷版本嘅每日歷史。可選 finish=nonfoil|foil|etched 收窄至一種表面（預設：該版本存在嘅所有表面）；days 設定回溯期（預設 365，最長 5 年）。未知嘅印刷版本回傳 404。
| 序列 | 數據點 |
|---|---|
reference | { date, usd, hkd } — 英文市場參考價（MTG 經 Scryfall 取自 TCGplayer；符文戰場取自 TCGplayer）。港幣按美元掛鈎換算。 |
market | { date, lowestAskHkd, highestBidHkd } — HiMarket 自身嘅最低售價同最高買取價，Near-Mint 等值。 |
trades | { date, priceHkd, nmEquivalentHkd, condition, language, finish } — HiMarket 上匿名化嘅成交紀錄。只有價格同日期，永遠唔會有買賣雙方身份。 |
所有序列都係差分編碼：只有數值有變嗰日先有數據點。請以階梯方式讀取，唔要插值，亦唔要將空白當成缺數據。basis 係 nmEquivalent — 市場價同成交價已除以品相係數，令有損卡可以同全新卡比較。回應會快取 30 分鐘。
識別碼
printingId係穩定嘅，亦係兩個端點之間 join 嘅 key。卡牌頁面網址嘅 slug 都係同一個 id。- 語言代號跟 Scryfall 嘅方案（
zht= 繁體中文，zhs= 簡體中文）。 - 符文戰場參考價係英文市場價；HiMarket 上嘅中文符文戰場卡通常成交價低好多。
使用條件
免費使用，條件如下
- 頻率：每款遊戲嘅市場快照最多每 15 分鐘取一次；每個印刷版本嘅歷史最多每日取一次。兩個端點都有快取，更頻密都冇用。唔要抓取卡牌頁面或任何其他路徑。
- 標明來源：顯示數據嘅地方請標示為 HiMarket (Hong Kong)，並用
url欄位回連至卡牌頁面。可以自行加上utm_source參數。 - 只限顯示同匯總：可以喺您嘅產品內顯示、繪圖同匯總數據。唔要重新分發原始數據或當作數據集提供。
- 如實呈現：香港係細市場，好多價格只來自單一賣家。請以「HiMarket 數據」呈現，而唔係「香港市場價」。
- 不包括：在售數量、庫存數量同成交量唔會發佈。圖片網址唔屬於呢個介面。
- 可撤回：我們可能會以電郵通知後更改限制或終止存取。
同一版本內只會作增量改動：可能新增欄位，現有欄位意思不變。破壞性改動會以新版本路徑（/api/public/v2/…）推出，舊版本會保留一段過渡期。
有問題、整合備註，或者想要呢度未涵蓋嘅數據：hello@himarket.hk。如果您跑嘅係 AI 代理而唔係排程任務，Agent MCP 可能更適合。