# Agent 与公开 API

无需登录读取 20 个卡片和账户版本、10 篇指南。提供 OpenAPI、JSON、Markdown、稳定引用地址与明确核对日期。

- Canonical: https://card.genedai.me/agents/
- Editor: Gene Dai (https://card.genedai.me/about/)
- Last verified: 2026-09-28
- Language: zh-CN

## 从这里开始

这是一组**无需 API key、只读、无需 JavaScript** 的资料接口。覆盖 20 个卡片与账户版本、10 篇指南。内容为中文；字段名、状态码和 API 文档使用英文，便于工具调用。公共接口不要求 Cookie。

- [OpenAPI 3.1 文档](https://card.genedai.me/openapi.json)：工具可以据此发现参数、返回字段和错误格式。
- [API 发现入口](https://card.genedai.me/.well-known/api-catalog)：RFC 9727 Linkset，列出机器文档和人工说明。
- [llms.txt](https://card.genedai.me/llms.txt)：简要阅读导航。[llms-full.txt](https://card.genedai.me/llms-full.txt)提供完整目录、问答和指南文本。
- [完整卡片数据](https://card.genedai.me/data/cards.json)、[指南索引](https://card.genedai.me/data/guides.json)、[问答数据](https://card.genedai.me/data/answers.json)：按构建版本导出，与网页使用相同来源。
- [内容索引](https://card.genedai.me/content-index.json)、[站点地图](https://card.genedai.me/sitemap.xml)和[RSS](https://card.genedai.me/feed.xml)：发现页面与已发布指南。

## 一个可执行的读取流程

先搜索或筛选，用返回的稳定 `id` 读取具体版本，再依据 `canonicalUrl`、`lastVerifiedAt` 和 `sources` 生成引用。跨币种费用保留原始单位；未知费用不能推导为零。

```bash
curl 'https://card.genedai.me/api/v1/cards?type=bank&limit=5'
curl 'https://card.genedai.me/api/v1/search?q=HSBC'
curl 'https://card.genedai.me/api/v1/cards/hsbc-one'
curl 'https://card.genedai.me/api/v1/compare?ids=hsbc-one,mox'
```

结果包含申请资格、地区、费用原文、材料、步骤、支付支持与官方来源。搜索返回卡片和指南的标题、摘要、网页地址及 Markdown 地址；不会调用私有账户数据。

## 在同一个地址读取 Markdown

公开目录、产品、攻略、专题、对比、问答和本站说明页提供完整 Markdown。可读取页面中的 `rel="alternate"` 链接，或发送 `Accept: text/markdown`。响应设置 `Vary: Accept`，浏览器访问保持 HTML。

```bash
curl -H 'Accept: text/markdown' 'https://card.genedai.me/cards/hsbc-one/'
curl 'https://card.genedai.me/cards/hsbc-one/index.md'
```

Markdown 的内容与公开网页对应，不是隐藏给机器的另一套结论。互动费用计算、私人清单与账户操作仍使用网站界面。

## 参数、分页和错误

`GET /api/v1/cards` 支持 `type=bank|crypto`、`status`、`q`、`limit` 和 `offset`。`GET /api/v1/search` 要求非空 `q`，检索产品及指南标题、摘要和分类。两者默认每页 20 条，最多 50 条，最大 offset 为 10000。使用响应中的 `next` 获取下一页；`null` 表示结束。

`GET /api/v1/compare` 要求 `ids` 包含 2 至 5 个不同版本 ID，保留请求顺序。它返回资料，不自动给出推荐分或汇率换算。

支持 GET、HEAD、OPTIONS 和跨域读取。ETag 与 `If-None-Match` 支持 304 缓存复核。参数有误返回 400，未知 ID 或接口返回 404，写请求返回 405，暂时不可用返回 503；错误正文采用 `application/problem+json`。详情见 OpenAPI。请缓存响应，不要密集重复抓取。

## 申请状态的含义

- `visitor`：存在官方列明的访港或内地客户路径，仍需满足个人条件并接受审核。
- `limited`：有地区、资格或版本限制，必须阅读 `eligibility.details`。
- `paused`：所述申请路径暂停，不能当作当前开放申请。
- `unavailable`：所述申请路径不可用或版本停止新发行。
- `verify`：公开证据不足，需要向机构核实，不等于支持。

## 如何准确引用

建议引用“产品 / 文章名 — Gene Dai Card Atlas，核对日期：YYYY-MM-DD”，链接到返回的 `canonicalUrl`，同时保留支撑具体结论的官方 `sources`。引用时保留真实居住地、具体版本、币种、期限与未知项。本站不是发行方；不得把资料当作实时费用报价、审批结果或个性化金融建议。

`lastVerifiedAt` 是编辑核验日期。`datePublished` 与首次发布相关，日期不会因 Agent 读取或站点重新部署而自动更新。[编辑原则](https://card.genedai.me/methodology/)解释完整口径；[关于 Gene Dai](https://card.genedai.me/about/)说明编辑身份。

## 公开范围

公共接口只输出人工编辑的产品资料与攻略。账户、私人收藏、未公开投稿、会话、后台接口和金融操作均不属于这个 API。无需向本站发送证件、钱包私钥、卡号或账户凭据。