Cards Realm API

快速开始

一个只读的 JSON API，数据与网站本身相同：卡牌、套牌、赛事和选手战绩。

无需 API 密钥。 所有接口均为公开，无需认证、令牌或注册。

GET 或 POST 均可，参数可以放在查询字符串里，也可以放在请求体里。 参见下方的“发送参数”。

基础地址

https://cardsrealm.com/zh-hk/api/

语言段是路径的一部分，决定卡牌名称及其他译文的语言。网站支持的任何 locale 都可以使用。

选择游戏。 两种方式，效果相同：调用该游戏自己的子域名，或传入 game_id 参数。两者都不用时，返回你所调用域名对应的游戏。

请求示例

curl "https://cardsrealm.com/en-us/api/getRecentDecks?game_id=1&limit=2"

价格是以分为单位的整数。 price 为 77、currency_prefix 为 $ 表示 0.77。显示前请除以 100。

合理使用。 目前没有强制的请求频率限制，所以请自觉：能缓存就缓存，并优先使用一次分页请求而不是许多次小请求。滥用会让开放的 API 变成封闭的。

发送参数

每个端点都同时响应 GET 和 POST，并从下列任一种方式中读取参数，哪种方便就用哪种。响应完全相同。

发送方式	`Content-Type`
查询字符串（GET 或 POST）	—
简单表单	`application/x-www-form-urlencoded`
多部分表单	`multipart/form-data`
JSON	`application/json`

同一个调用，三种写法

curl "https://cardsrealm.com/zh-hk/api/getRecentDecks?game_id=1&limit=2"

curl -X POST "https://cardsrealm.com/zh-hk/api/getRecentDecks" \
     -d "game_id=1" -d "limit=2"

curl -X POST "https://cardsrealm.com/zh-hk/api/getRecentDecks" \
     -H "Content-Type: application/json" \
     -d '{"game_id": 1, "limit": 2}'

数字可以就是数字。 在表单里所有值都以文本到达；用 JSON 时可以直接发送 1 而不是 "1"。两种都能用。

不要手动设置 Content-Type 头 在 Postman、Insomnia 或 HTTP 库里都是如此。让工具自己生成：multipart 需要带上 boundary，而与请求体不匹配的 Content-Type 会让所有字段都变成空。这时返回的 400 说的是信封，不是你的字段：

响应

{
  "error": "无法读取请求体中的字段。请以 form-data、x-www-form-urlencoded 或 JSON 发送。",
  "hint": "如果你用 Postman 或 Insomnia，请删掉 Content-Type 头，让工具自己生成。"
}

可以从浏览器调用。 你自己域名下的页面可以直接从浏览器调用它。不读取任何 cookie 或凭据。

cardinfo

GET/zh-hk/api/cardinfo

按名称查找一张卡牌的全部信息：规则文本、法术力费用、稀有度、版本与当前价格。

参数	类型	图案	笔记
`cardname`	string	`Path to exile`	最多 50 个字符。
`currency`	string	该 locale 的货币	三个字母。
`game_id`	int	该域名对应的游戏	1 = Magic, 2 = Yu-Gi-Oh, 3 = Pokémon, 4 = Runeterra.
`language_code`	string	路径中的语言	返回的卡牌名称与文本所用的语言。

请求示例

curl "https://cardsrealm.com/zh-hk/api/cardinfo?cardname=Lightning%20Bolt&currency=USD"

响应示例

{
  "name_of_card": "Lightning Bolt",
  "name_ing": "Lightning Bolt",
  "type_of_card": "Instant",
  "text_of_card": "Lightning Bolt deals 3 damage to any target.",
  "price": 77,
  "currency_prefix": "$",
  "path_of_card": "oj7-lightning-bolt",
  "card_url": "https://mtg.cardsrealm.com/en-us/card/lightning-bolt"
}

getRecentDecks

GET/zh-hk/api/getRecentDecks

最近发布的套牌，最新在前。

参数	类型	图案	笔记
`page`	int	`1`	页码。
`limit`	int	`50`	每页套牌数。上限为 500，超过则返回错误。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getRecentDecks?page=1&limit=2"

响应示例

[
  {
    "deck_id": 374859,
    "deck_title": "Attack of the myrs",
    "deck_owner": "jarrod long",
    "deck_format_name": "Commander",
    "deck_colours": "B G R U W",
    "total_cards": 100,
    "deck_url": "https://cardsrealm.com/decks/en-us/l8dh-attack-of-the-myrs"
  }
]

getDeckByID

GET/zh-hk/api/getDeckByID

完整的套牌列表。卡牌清单位于 cards 字段，包含数量、board（main 或 side）以及每张卡的价格。

参数	类型	图案	笔记
`deck_id`	int	`0`	套牌的数字 id。
`currency`	string	`BRL`	三个字母。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getDeckByID?deck_id=374859&currency=USD"

响应示例

{
  "deck_title": "Attack of the myrs",
  "user_name": "jarrod long",
  "tour_type_name": "Commander",
  "deck_quantity_main": 99,
  "deck_quantity_side": 1,
  "cards": [
    {
      "name_ing": "Command Tower",
      "deck_quantity": 1,
      "deck_sideboard": 0,
      "card_price_total": 18
    }
  ]
}

不存在的 deck_id 会返回 200 和一个近乎空的对象，而不是错误。使用其余字段前请先确认 deck_title 是否存在。

getDeckResults

GET/zh-hk/api/getDeckResults

某个套牌原型的表现：总体战绩，并按 by_meta 细分它对阵其他每个原型的结果。

参数	类型	图案	笔记
`deck_name`	string	空	套牌原型名称，最多 40 个字符。
`week`	int	`4`	回溯多少周。上限为 52。
`format`	string	`Standard`	最多 20 个字符。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getDeckResults?deck_name=Grixis%20Affinity&format=Pauper&week=8"

getPlayerResults

GET/zh-hk/api/getPlayerResults

某位玩家的战绩，并按 by_meta 细分他在每个套牌原型下的表现。

参数	类型	图案	笔记
`player_name`	string	空	最多 40 个字符。
`week`	int	`52`	回溯多少周。
`player_platform`	string	`cardsrealm_nickname`	按哪个名称检索。取 cardsrealm_nickname、mtgo、arena、riot 或 display 之一。其他取值将返回错误。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getPlayerResults?player_name=Carrubs&player_platform=mtgo"

getPastTournaments

GET/zh-hk/api/getPastTournaments

已经举办过的赛事，最新在前。

参数	类型	图案	笔记
`page`	int	`1`	页码。
`format`	string	空	最多 20 个字符。留空表示所有赛制。
`game_id`	int	`1`	与 cardinfo 相同。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getPastTournaments?format=Pauper&page=1"

响应示例

[
  {
    "tournament_id": 810845,
    "tournament_name": "Domingooouuu Pauper 86",
    "tournament_path": "https://cardsrealm.com/tournament/en-us/1k3c9-domingooouuu-pauper-86",
    "format_name": "Pauper",
    "game_name": "Magic: the Gathering",
    "datetime_utc": "Sun, 16 Aug 2026 16:30:00 GMT"
  }
]

getTournamentInfo

GET/zh-hk/api/getTournamentInfo

一场赛事的完整信息：赛事本身、位于 round_info 的各轮次，以及位于 standings 的最终排名。不存在的 id 返回空列表，而非错误。

参数	类型	图案	笔记
`tournament_id`	int	`1`	赛事的数字 id。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getTournamentInfo?tournament_id=810845"

getUserTournaments

GET/zh-hk/api/getUserTournaments

由某个账号举办的赛事。

参数	类型	图案	笔记
`nickname`	string	`Cards Realm`	最多 30 个字符。

请求示例

curl "https://cardsrealm.com/zh-hk/api/getUserTournaments?nickname=leon-diniz"

错误与支持

代码	意义
`200`	成功。响应体始终为 JSON。
`400`	调用被拒绝：名称太长、数字不是数字、取值不在允许的列表内，或请求体无法读取。
`500`	是我们这边出了问题。欢迎告诉我们。

被拒绝的调用返回 400 和一个对象。invalid_fields 指出值得检查的参数；当问题不在某个具体字段时，它不会出现。

响应

{
  "error": "周必须是数字",
  "invalid_fields": ["week"]
}

这一点在 2026 年 9 月 8 日发生了变化。 以前被拒绝的调用返回 404 和一个裸字符串。消息内容不变，变的是状态码和外层结构。变更日志

有疑问，或者需要这里没有的字段？来 Discord 找我们。 Discord