OG开发者中心v1
下载 OpenAPI

AI 接入

自包含钱包接入交付包

公开协议、参考实现与固定离线验收。

下载完整 AI 接入包 ZIP ↗ · 机器可读能力说明

第三方 AI 钱包接入交付包

从本文件开始。此包包含公开 API 规范、接入说明、三语言 Webhook 接收器、Python 标准库与 SQLite 参考工程，以及独立固定验收。默认离线，不包含真实环境配置、密钥或部署记录。

第一步：在空目录验证交付包

解压后进入包含 docs/、scripts/ 的包根目录，运行：

SH
python3 docs/integration-kit/acceptance.py
python3 docs/integration-kit/reference/server.py --port 63924

第一条命令运行固定验收并直接检查临时 SQLite 持久结果，预期全部 OK。第二条启动受限回环演示，访问 http://127.0.0.1:63924/live，预期 businessEnabled=false；未配置身份适配时业务入口返回 503，也不会连接平台。Ctrl+C 退出。失败先看测试名及数据库断言；启动失败检查 Python 3.10+、完整目录布局和端口。无需安装 Python 第三方库。

第二步：将这些资料交给 AI

读取 AI-START.md，填齐技术栈和业务输入后，再让 AI 实现你们的适配层。资料职责如下：

文件用途
profile.json当前普通人工提现/每日上限能力、入口、验收命令、明确不支持的旧额度模式
CONTRACT.md公共签名与持久账务处理约束；不含内部服务签名
OpenAPI公开接口、字段、枚举和请求/响应结构
接入接口、接入实战调用步骤、原单补查和充值/提现流程
config.example.json必须由平台和接入方提供的 REPLACE 配置
ADAPTER.md身份、客户端、账务、任务接口以及生产替换责任
ACCEPTANCE.md测试矩阵、观测结果、运行命令及边界
reference/可执行参考：client、ledger、worker、受限 HTTP、SQLite schema
fixtures/events.json仅离线 TEST_ONLY 事件；不是链上事实
三语言示例Go/Java/Python 接收边界与完整事件协议向量

公开契约与 OpenAPI 若冲突应停止相关自动改账并报告，不通过修改固定验收或猜测生产行为来消除冲突。参考实现是可以替换的工程样本；Python/SQLite 通过本包离线验收，不表示你们的身份、既有账本、真实网络或部署已经验收。未逐一测试的 AI 产品、语言和框架不承诺一次生成成功。

第三步：接入真实环境前准备

复制配置模板到源码库外，由平台提供真实 API 与 Webhook 独立凭据、环境、accessNamespace、登记链/合约/精度；由接入方提供身份映射、余额迁移和资金政策。只允许显式选择 query_before_credit_manual_review_on_shortfall 后启用本参考账本。它先查单再入账，冲正可用余额不足时持久人工核查并阻止该资产账户新增预扣，不自动负余额、不挪用其他订单 held。

配置中仍有 REPLACE_ 时启动失败，不发真实请求。完成适配并通过固定验收后，才在有权限的环境中填写真实配置、接入 TLS/身份/告警并安排现场验证。网络请求还要求 --allow-network；本包交付过程不做部署或真实付款。失败先查配置材料与 ADAPTER.md 的待决项，勿用夹具值补真实环境。

AI 接入入口

目标：只使用公开包与接入方提供的真实配置，产出可构建、可运行、可独立验证的接入工程。先执行 python3 docs/integration-kit/acceptance.py 确认交付包完整，再读取本文件、profile、公共 CONTRACT、OpenAPI 和 ADAPTER。完整工程以固定验收与持久数据证明完成。

接入方必须提供的输入

输入必须明确的内容
技术栈语言/运行时版本、框架、构建/测试命令、数据库版本与部署方式
身份已有登录校验、session/token验证接口、主体到 playerId 的可信映射、环境与租户隔离
余额账户键、基础单位余额、已有冻结/消费/释放接口、事务边界、余额迁移和审计责任
充值资金政策首次入账新鲜度、冲正不足处理、冻结范围、人工处理权限与解除条件
平台配置真实API地址、独立API/Webhook凭据、environment、accessNamespace、链ID/规范合约/精度/链类型
运维公网HTTPS通知入口、代理原始路径、数据库备份、worker运行方式、报警与人工核查负责人

缺少这些输入时，列出具体缺项并继续完成离线适配与固定验收；业务写入口保持关闭。不得从浏览器 body.playerId 推导身份，不得替接入方选择欠款/负余额政策。参考政策只在显式配置后生效，其他政策必须另行设计与验证。

交给 AI 的任务模板

TEXT
请依据本公开包实现我们的钱包接入。技术栈：REPLACE_LANGUAGE_FRAMEWORK_DATABASE。
可信身份接口：REPLACE_AUTHENTICATED_PRINCIPAL_MAPPING。
已有余额/事务接口：REPLACE_BALANCE_AND_TRANSACTION_ADAPTER。
选择的充值及冲正政策：REPLACE_EXPLICIT_FUNDS_POLICY。
环境配置从库外路径读取：REPLACE_PRIVATE_CONFIG_PATH。
读取本包 CONTRACT、OpenAPI、ADAPTER 和 ACCEPTANCE；保存订单身份/资产/精度快照，
支持稳定 clientRequestId、原子预扣、原始字节验签、持久收件箱、查询/通知同一幂等结算，
实现持久补查worker和人工核查责任。沿用普通人工提现/每日上限profile，不启用旧额度v2。
给出迁移、配置模板、启动命令与固定验收结果。不得改测试以迁就实现、不得进行真实付款。

必须交付的成果

  1. API client：五段公共 HMAC、精确路径/query/body、超时、TLS验证、禁止跨源重定向；地址、充值/提现单查、玩家历史、提现提交/取消、Webhook配置读取。
  2. 可信身份适配：服务端认证并映射 playerId；跨主体访问拒绝；未配置身份禁止业务写入。
  3. 持久账务与迁移：稳定申请键、每单冻结快照、账户级原子预扣、eventId/业务键防重、严格拒绝绑定、充值版本检查、人工核查记录。
  4. worker：原申请提交恢复、同原单补查、到期租约恢复、有限退避、失败转人工；终态不重提，已入账充值继续复核失效。
  5. HTTP接收：保留重复头和原始字节，提交后回签；事务失败不ACK，持久隔离后ACK不等于入账。
  6. 固定验收：使用包内不变的 acceptance.py，通过 --adapter 调用你的实现；提供兼容SQL观测表或测试投影，记录每项结果与未执行原因。

参考启动命令和默认入口见 README。完成后核对 ACCEPTANCE 中每个场景，失败先查看对应持久数据，不将收到200、生成文件或组件回调成功算作账务通过。人工修复后通过应记录为修复后的结果；不得宣称首次生成成功。

当前上限展示使用公共 GET /v1/withdrawal-quota，读取后台同一规则；响应 quota 显式 null 是不限额，503 是未知。查询不受理提现、不释放预扣，接入与验收细节见 CONTRACT。

输入关键词搜索指南、接口和字段。