Lunidex 公共 API v1

集成需要 API 密钥、保存在服务器上的密钥值，以及发送到 API 基础 URL 的 HTTPS 请求。

1. 1

   创建密钥

   打开 Lunidex 控制面板中的 API 密钥卡片，为密钥命名并选择只读或读写权限。完整密钥只显示一次；关闭提示前请先复制。

2. 2

   在服务器上保存密钥

   在托管服务的密钥管理器中将密钥保存为 LUNIDEX_API_KEY。不要将其提交到仓库，也不要发送给浏览器。

3. 3

   发送第一个请求

   从服务器调用 GET /me。私有端点要求在 Authorization: Bearer 后附上密钥。

curl --fail-with-body \
  -H "Authorization: Bearer $LUNIDEX_API_KEY" \
  https://lunidex.app/api/v1/me

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

const response = await fetch(API_BASE_URL + "/me", {
  headers: { Authorization: "Bearer " + apiKey },
});
const result = await response.json();

if (!response.ok) {
  throw new Error(result.error?.code ?? "REQUEST_FAILED");
}

console.log(result.data);

每个私有 /api/v1 请求都要在 HTTP Authorization 请求头中发送密钥。API 使用 data 封套返回 JSON；私有响应使用 Cache-Control: private, no-store。

API 只能读取 Neon 中已同步到 Lunidex 账户的数据。仅保存在设备上的数据不可用。账户身份信息不包含电子邮件地址。

列表返回 data 和 meta.nextCursor。请求下一页时原样传递游标；游标为 null 时结束。

• 默认每页 25 条，最多 100 条。目录搜索固定为每页最多 24 条。
• 卡牌支持 language 和 set 筛选。未开封商品持仓支持 language 和 productId；交易支持 language、productId、type、includeVoided 和 voided。目录搜索支持 q 和 cursor。
• 收藏、流水账、价格或筛选条件变化后，游标可能过期。此时 API 返回 409；请使用最新状态并移除游标重新开始。

const API_BASE_URL = "https://lunidex.app/api/v1";
const apiKey = process.env.LUNIDEX_API_KEY;
let cursor = null;

if (!apiKey) throw new Error("Missing LUNIDEX_API_KEY");

do {
  const query = new URLSearchParams({ limit: "100" });
  if (cursor) query.set("cursor", cursor);

  const response = await fetch(API_BASE_URL + "/cards?" + query, {
    headers: { Authorization: "Bearer " + apiKey },
  });
  const result = await response.json();
  if (!response.ok) throw new Error(result.error?.code ?? "REQUEST_FAILED");

  console.log(result.data);
  cursor = result.meta?.nextCursor ?? null;
} while (cursor);

以下路径均相对于 API 基础 URL。每一行都会显示所需权限以及 OpenAPI 契约中列出的参数。机器可读规范包含完整架构、请求和响应示例以及各操作的错误；以下章节说明主要使用流程。

GET /cards 列出持有的卡牌变体，不会加载完整的 TCGdex 目录。每项包含 cardId、setId、language、variant 和 quantity；可选筛选项为 language 和 set。

GET /cards/{cardId} 返回有用的 TCGdex 元数据和账户内该卡牌的持有信息。可使用 language 查询参数筛选持有记录。

{
  "language": "en",
  "variant": "reverse",
  "quantity": 2
}

没有语言信息的旧持有记录仍可见；language 可能为 null，也可能标记为 legacy。

此 API 不会返回卡牌估值。

未开封商品持仓包含按语言划分的数量、成本，以及基于 Lunidex 已存储价格计算的当前价值。金额为整数欧分。缺少价格时 valueCents 为 null，并由 missingPrice 标记；summary 还会返回 missingPrices。

在 GET /summary 中，只要任一持有商品缺少价格，未开封商品总价值就为 null；missingPrices 提供缺价数量。

成功响应格式为 { "data": ..., "meta": ... }（meta 可选）。错误格式为 { "error": { "code": ..., "message": ..., "details": ... } }（details 可选）。

常见响应：400 交易数据无效；401 密钥无效；403 权限不足；404 资源不存在或不属于此账户；409 游标或修订号过期；410 账户正在删除；422 查询参数或请求正文无效；429 超出配额；500 意外的服务器错误；502 卡片数据不可用；503 API 不可用。

所有私有 API 响应均使用 Cache-Control: private, no-store。公开 OpenAPI 文档单独发布于 /api/v1/openapi.json。

限制按 Lunidex 账户计算，同一账户的所有 API 密钥共享配额。

卡牌详情与未开封商品计算各自拥有独立的全局上限，每类每天 5,000 次。429 响应包含 Retry-After。