Skip to main content
需要 Silver 或更高等级的会员 — 申请时需要,之后每一次已认证的调用同样需要。若密钥所有者的会员到期,项目会被冻结,直到其重新订阅。
一套 REST API,让你的应用在 Discord 内直接操作用户的 Vito 余额:读取、扣款、充值,或在用户之间转移。所有端点都返回 JSON,并在 /v1 下进行版本管理。
Vito 永远不会与真实货币互相兑换。 它只在 Vetox 余额之间流动。

获取访问权限

访问权限按项目授予。以下四项缺一不可:
1

有效的 Silver 或更高等级会员

每次调用都会检查,而不只是在审批时检查。
2

已获批准的开发者申请

在控制面板的 Vito API 页面提交,由 Vetox 团队人工审核。
3

已接受的 API 开发者条款

在提交申请时确认。
4

项目所需的 scope

由 Vetox 团队根据你的描述授予。
请具体说明你要做什么、以及会如何保存密钥。被拒绝的往往正是描述含糊的申请。

Scope

身份验证

将密钥作为 Bearer 令牌发送:
两个可选层级可进一步加固项目:
  • IP 白名单 — 将调用限制在特定的服务器 IP
  • 速率限制 — 按项目设定的上限,随所有者的会员等级提升

密钥、轮换与保管

密钥和签名密钥只会显示一次。 获批后你有 7 天的窗口期可在 API 密钥标签页中查看它们。Vetox 只保存哈希,无法再次显示 — 错过窗口期就只能轮换以获取新的。
  • 只将其保存在服务端 — 任何持有它的人都能向你的用户扣款
  • 在 API 密钥标签页中轮换。旧密钥会继续生效 24 小时作为宽限期,让你不停机完成部署
  • webhook 签名密钥单独轮换,拥有各自的 24 小时重叠期
  • 一旦泄露,请立即轮换

向用户扣款

仅凭密钥无法转移用户的 Vito。 每一笔扣款都需要用户在 vetox.io 上用钱包 PIN 批准 — 绝不会在你的应用内,也不会在 Discord 内进行。
1

你的应用调用 POST /v1/deduct

附带用户、金额、发起的 guildId 以及商品详情。
2

Vito 返回 confirmUrl

一条待确认记录,有效期 10 分钟。用户同时会收到私信。
3

用户用 PIN 批准

vetox.io 上完成。
4

Vito 结算并通知

余额被扣除,交易被记录;若你配置了 webhook,会发送一条带签名的通知。
5

你的应用验证并完成

校验签名,然后解锁内容或发放商品。
只在收到 confirmation.completed 时才完成你的操作 — 绝不要依据 /deduct 的响应。在那一刻扣款尚未最终确定。

请求参数 — /v1/deduct

为用户充值

POST /v1/add 从你自己的余额为用户充值 Vito,用于奖励或退款。除 guildIdproduct 外,字段与 /deduct 相同。
与扣款不同,充值没有确认步骤 — 会立即结算。需要 credit:create scope 和足够余额,否则调用返回 402 VITO_INSUFFICIENT_OWNER_FUNDS

费用

每笔扣款在扣除平台手续费后结算给你 — 采用与应用内 Vito 转账相同的费率,依据你的会员等级:
5 Vito 及以下的金额免手续费,通过 /v1/add 的充值则始终免手续费。

Webhook

在设置标签页中添加一个或多个 https 回调地址。每当一条确认记录进入终态,Vito 就会发送一条带签名的 POST
只有当项目同时具备回调地址签名密钥时,webhook 才会发送。请在 API 密钥标签页中一次性查看密钥(whsec_…)。

校验签名

每次投递都带有 X-Vito-Signature 请求头:
每次投递还会附带另外两个请求头 — 请用 X-Vito-Event-Id 作为去重键,因为重试会发送相同的 id:
在签名密钥轮换期间,该请求头会携带不止一个签名,最新的在前:
只要任意一个 h1 匹配就应接受这次投递。只读取第一个的校验代码会拒绝所有 webhook,直到它部署了新密钥 — 而这恰恰让 24 小时重叠期失去了意义。
用你的签名密钥对 <ts>:<rawBody> 重新计算 HMAC,并以常数时间比较。
请针对原始请求体进行校验,要在任何 JSON 解析或中间件改写之前完成。

事件

共五种事件类型,全部共用同一种载荷结构。结果由 data.status 承载。
webhook 会以退避策略重试 5 次。请尽快返回 2xx,并异步执行你的发货逻辑。

错误码

每个响应都包在一层信封里。成功携带 data,失败携带 error,两者绝不会同时出现:
每个错误码都带有 VITO_ 前缀。 请以完整字符串进行判断 — 裸的 RATE_LIMITEDFORBIDDEN 绝不会出现在响应中。

速率限制

此外还有按 IP 的限制,为你每分钟配额的一半,最低不少于 30。
在高负载下,写入端点会「失败即拒绝」 — 宁可拒绝这笔扣款,也不冒重复扣款的风险;读取端点则「失败即放行」。请把被拒绝的写入视为「没有发生过」并重试。
发送 Idempotency-Key 请求头,即可安全地对重试去重。

端点

限制

  • 确认记录会在 10 分钟后过期 — 请把未确认的请求当作已放弃
  • amount 必须是正整数
  • metadata 最多 10 个键
  • 单笔与每日上限由 Vetox 团队设定,在设置标签页中以只读方式展示

安全检查清单

API 密钥与签名密钥绝不属于客户端代码。任何一个泄露都要立即轮换。
对照原始请求体校验签名,并拒绝早于约 5 分钟的投递。
切勿依据 /deduct 的响应发货 — 扣款要到 confirmation.completed 才算最终确定。
只申请你真正使用的 scope,并启用 IP 白名单。

疑难排查

所有者的会员已到期。它在每次调用时都会重新检查。
无法找回 — 系统只保存哈希。请轮换以获取新的密钥。
在 24 小时重叠期内请同时接受新旧两个密钥。
用户没有批准。确认记录会在 10 分钟后过期。
项目需要同时具备回调地址和签名密钥。只有其中之一时,什么都不会发送。
这是结算手续费。使用 5 Vito 及以下的金额可以避免,或把它计入你的定价。
/v1/add 由你自己的余额出资,并非凭空产生。请先充值。

Vito

余额、PIN 与费用。

付款请求

你向用户扣款时,他们看到的界面。