积分 (Credits)
工作区可以给成员发放积分，成员用这些积分为自己发起的对话付费。 发放从工作区所有者的账户里扣除，并且用幂等键保证同一笔发放无论重试多少次都只记一次。
先确认你需不需要发积分：默认情况下，和 Agent 对话的费用记在 Agent 所有者头上，成员余额为 0 也能正常聊天——网站客服、小程序助手这类场景通常一分都不用发。只有当 Agent 所有者把计费方设成「由使用者付费」时，成员才需要余额。
发放积分
const ws = new OpenhexClient({ apiKey: process.env.OPENHEX_WORKSPACE_KEY! })
.workspace(process.env.OPENHEX_WORKSPACE_SLUG!);
const grant = await ws.grantCredits(member.member_id, {
amount: 500,
idempotency_key: `signup-bonus:${member.member_id}`,
});
// → { balance: 500, purchase_id: '…', idempotent: false }
| 参数 | 类型 | 说明 |
|---|---|---|
amount | number | 发放数量，必须大于 0，最大 1e9 |
idempotency_key | string | 你生成的幂等键，同一笔业务用同一个键 |
| 返回字段 | 说明 |
|---|---|
balance | 发放后该成员的余额 |
purchase_id | 这笔发放的记录 id |
idempotent | true 表示这是一次重放，没有重复入账 |
幂等键怎么取
用同一个 idempotency_key 再调一次，平台不会重复发放，而是原样返回第一次的结果（同一个 purchase_id），并把 idempotent 置为 true。所以网络超时后直接重试就是安全的。
把幂等键和你的业务事件绑定，而不是每次随机生成：
// ✅ 一个订单只发一次
idempotency_key: `order:${orderId}`
// ✅ 每个成员只有一次注册奖励
idempotency_key: `signup-bonus:${memberId}`
// ❌ 每次都不一样，重试会重复发放
idempotency_key: crypto.randomUUID()
常见错误
| 状态码 | message | 原因 |
|---|---|---|
400 | body/amount Number must be greater than 0 | amount 不是正数 |
402 | insufficient owner wallet balance | 工作区所有者账户余额不足以支付这笔发放 |
403 | API key does not match workspace | Key 和 slug 不属于同一个工作区 |
404 | member not found | 成员 id 不属于这个工作区 |
工作区 API Key 和工作区所有者的登录态都可以调用这个方法。
查余额
余额在成员列表里：
const { members } = await ws.listMembers();
const balance = members.find(m => m.user_id === memberId)?.balance;