Docs / Partner Regrant · 运营
Partner Regrant 接口 —— 运营篇
面向 0G 运营人员：Partner 转赠的两条路径、如何接入一个 Partner，以及本文档的来源。Partner 对接用的接口契约在 Partner 标签页。
1. 两条路径 —— 先搞清楚要的是哪条
合作方分发额度有两条完全不同的路。它们的身份模型、入口和我们的参与程度都不一样，产品决策主要就是选这个。
| A. Portal 中继 | B. 直连 API | |
|---|---|---|
| 合作方怎么操作 | 登录 Portal，点「Share credit」表单 | 自己的后端签名调用我们的接口 |
| 一次能发几个 | 一个收款方 | 最多 500 行 |
| 身份 | Privy 登录拿到 DID，按 DID 落座 | 用自己的钱包签名，按钱包地址落座，全程不登录 |
| 需要合作方有研发吗 | 不需要 | 需要 |
| 我们的前端要做什么 | 已经做好了 | 调用本身不需要；campaign 页的 Partner kit 负责把对方需要的信息交给他 |
| 实现状态 | 已上线 | 后端已就绪，前端不涉及 |
路径 B 不需要我们排期。 合作方直接调 POST /v1/regrants，我们既不代理也不在链路里。接一个合作方只是一次 admin 落座操作，没有配置变更、没有发版。
路径 A 的界面操作步骤在 「操作手册」第 5 节。
路径 A 的界面操作步骤在 「操作手册」第 5 节。
2. 接一个 Partner 要做什么
1
拿到对方的钱包地址
一个他们已经拥有、并且能用来签名的地址。私钥留在他们手里，我们只看到地址。
2
Admin 把这个地址落座为 partner
POST /admin/roles，subject 填钱包地址、role 填 partner。落座就是白名单，取消落座立即失效，不需要动对方的密钥。
3
BD 把额度发放到同一个地址
这笔 Grant 产生的 lot_id 就是对方后续转赠时要填的 source_lot_id。发放成功后 Grant 表单会显示它，campaign 页的 Grants issued 表的 Lot 列里也一直能查到。
4
把 Partner kit 发给对方
在 campaign 页该钱包那一行点 Partner kit，会汇总对方需要的全部信息（API host、source_lot_id、Lot 的额度、到期日和服务范围、external_ref 前缀），并检查落座状态。复制后直接发给对方 —— 里面有未公开的 host，不要发到公开场合。
落座不等于开户。 落座只记录「这个主体被允许做什么」。 Partner 的钱包必须先被发放过额度，才有东西可以再分配 —— 落座了但没账户会收到一个 403。
注意 partner 的 subject 填的是钱包地址，不是 DID。 其它三种角色（distributor / finance_approver / admin）走 Portal，用 Privy 登录后拿 DID 落座； partner 可以从不登录，他签名用的钱包就是他的身份。
上线之后
发错地址的行只能由我们撤销。finance approver（或出资这个 campaign 的 distributor） 在 campaign 页撤销那一个 Lot。撤回的只是收款方还没花掉的部分，连同他再转出去的；钱回到 campaign 预算，不回到 partner 的 Lot，如有需要要重新发给 partner。
我们不对 partner 限流。500 行一次，每行都可能创建一个账户；对方出错就重试的循环， 我们这边不会拦。请提醒对方出错时做退避。
我们不对 partner 限流。500 行一次，每行都可能创建一个账户；对方出错就重试的循环， 我们这边不会拦。请提醒对方出错时做退避。
3. 来源与时效
本页描述的是 Pay 后端的接口，不在本仓库内，因此它不会随本仓库的代码改动自动更新。 对接前请以真源为准核对。
| 真源 | 0gfoundation/0g-pay-v2 → backend/deploy/PARTNER-REDISTRIBUTION.md（面向合作方）与 FRONTEND-INTEGRATION.md §3.5 / §“Re-granting at scale” |
| 整理自 | commit 51706ce（2026-09-18） |
| 本页成文 | 2026-09-21；签名串与失败码 2026-09-24 据 Pay 团队答复修订；2026-10-01 增补 partner 接入信息包、完整示例与单 Lot 撤销（撤销依据 backend/internal/ops/reclaim_lot.go）；2026-10-03 增补 Privy 私钥导出 |
| 本仓库涉及部分 | 无 —— Portal 不调用 /v1/regrants，「Share credit」走的是 /v1/grants + source_lot_id |