商户能力与游戏列表

接入的第一步是读取商户能力。这两个接口只读，任何钱包模式都可以调用，也适合用来验证签名是否正确。

商户能力

GET {API_URL}/v1/capabilities

没有请求参数。

成功响应 200

字段	类型	说明
wallet_mode	string	TRANSFER（转账钱包）或 SEAMLESS（单一钱包）
currencies	array	已开通的币种，每项为 {code, decimal_scale}
operations	array	各功能是否可用，见下表
limits	object	调用限额，见下表

operations[]：

字段	说明
kind	players、transfers、launches、gift_tasks
supported	当前商户是否可用
reason	不可用的原因，可用时为 null。例如单一钱包商户的 transfers 为 WALLET_MODE_UNSUPPORTED，未开通现金奖励时 gift_tasks 为 CASH_REWARD_UNSUPPORTED
schema_version	该功能的接口版本

limits：

字段	说明
query_requests / query_seconds	普通查询：每 query_seconds 秒最多 query_requests 次
record_requests / record_seconds	注单查询（/v1/records、/v1/record-changes 共用）
max_page_size	分页 limit 的上限
max_body_bytes	请求 body 的最大字节数

{
  "data": {
    "wallet_mode": "TRANSFER",
    "currencies": [
      { "code": "USD", "decimal_scale": 2 },
      { "code": "USDT", "decimal_scale": 4 }
    ],
    "operations": [
      { "kind": "players", "supported": true, "reason": null, "schema_version": "1" },
      { "kind": "launches", "supported": true, "reason": null, "schema_version": "1" },
      { "kind": "transfers", "supported": true, "reason": null, "schema_version": "1" },
      { "kind": "gift_tasks", "supported": false, "reason": "CASH_REWARD_UNSUPPORTED", "schema_version": "1" }
    ],
    "limits": {
      "query_requests": 10, "query_seconds": 1,
      "record_requests": 2, "record_seconds": 1,
      "max_page_size": 1000, "max_body_bytes": 1048576
    }
  },
  "request_id": "0192f6a0-req-0001"
}

游戏列表

GET {API_URL}/v1/games

返回当前商户已授权的游戏。列表为空是正常结果，表示还没有授权游戏。

参数	必填	类型	说明
status	否	string	AVAILABLE、MAINTENANCE 或 DISABLED
limit	否	integer	每页条数，1–1000，默认 100
cursor	否	string	续页游标，24 小时内有效

成功响应 200

字段	类型	说明
game_id	string	游戏 ID（UUID），请求进入游戏时使用
name	string	默认名称
brand	string	品牌
category	string	分类编码，展示名见 category_detail
status	string	AVAILABLE、MAINTENANCE、DISABLED
launch_supported	boolean	当前是否可以启动。为 false 时请不要展示入口
languages	string[]	游戏支持的语言标签，例如 en、zh-Hans
client_version	string	游戏客户端版本
icon	object | null	默认图标，见游戏图标
localizations	array	多语言名称和图标，每项为 {language, name, icon}
provider	object	厂商：{code, name, icon, localizations}
category_detail	object	分类：{code, name, localizations}

{
  "data": {
    "items": [
      {
        "game_id": "0192f6a5-1111-7aaa-8bbb-000000000001",
        "name": "Hi-Lo",
        "brand": "Mingjue",
        "category": "CARD",
        "status": "AVAILABLE",
        "launch_supported": true,
        "languages": ["en", "zh-Hans"],
        "client_version": "15",
        "icon": {
          "asset_id": "0192f6a5-2222-7ccc-8ddd-000000000001",
          "sha256": "9f2c…",
          "content_type": "image/png",
          "size": 20480,
          "url": "/v1/catalog-assets/0192f6a5-2222-7ccc-8ddd-000000000001"
        },
        "localizations": [{ "language": "zh-hans", "name": "猜大小", "icon": null }],
        "provider": { "code": "MJ", "name": "Mingjue", "icon": null, "localizations": [] },
        "category_detail": { "code": "CARD", "name": "Card", "localizations": [] }
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "request_id": "0192f6a0-req-0002"
}

多语言展示

按玩家语言选择名称和图标：

1. 在 localizations 中找语言标签完全相同的项（不区分大小写）。
2. 找不到就逐段去掉末尾子标签再找，例如 zh-Hant-TW → zh-Hant → zh。
3. 仍找不到时使用默认 name 和 icon。

名称和图标分别回退：匹配到的项 icon 为 null 时，使用默认图标。游戏、厂商和分类各自独立回退。

游戏图标

GET {API_URL}/v1/catalog-assets/{asset_id}

图标不是公开 CDN 地址，需要商户签名下载，然后由商户自己托管或缓存。

• 响应体是图片原始字节（image/png、image/jpeg 或 image/webp）。
• 同一个 asset_id 的内容永不变化，可以按 asset_id 长期缓存。下载后可用 sha256 校验内容。
• 支持 If-None-Match，命中时返回 304。
• 没有授权或不存在时返回 404 RESOURCE_NOT_FOUND。