余额与事件

GET /api/v1/balance

权限 billing:read。充值在个人控制台中进行。

{
  "balance": "124.30",
  "currency": "USD"
}

GET /api/v1/transactions

权限 billing:read。参数：offset、limit、type。

排序固定且不可配置：最新的在前，按 created_at 排序，相同时按 id。 没有排序参数。

type：deposit、purchase、refund、commission、bonus - 各自的含义见 充值与赠金。

external_reference - 产生该笔变动的外部事件，而不是交易标识（交易标识是 id）。

bonus 类型的记录会填写 promo_code - 即发放赠金所用的优惠码。其他类型为 null。

事件

GET /api/v1/events，权限 events:read。从 ?after=<id> 向后读取，最早的在前。 参数：after、limit、type。

{
  "events": [
    {
      "id": 881,
      "type": "order.completed",
      "occurred_at": "2026-08-28T12:00:04+00:00",
      "order_id": 128,
      "package_id": 42,
      "data": {
        "family": "traffic_gateway",
        "client_reference": "deal-8891"
      }
    },
    {
      "id": 882,
      "type": "package.traffic_low",
      "occurred_at": "2026-08-28T18:31:00+00:00",
      "order_id": 128,
      "package_id": 42,
      "data": {
        "purchased_gb": "35.000",
        "left_gb": "3.410"
      }
    }
  ],
  "next_after": 882
}

类型	何时	data
order.provisioning	订单进入交付	family, client_reference
order.completed	交付完成；地址续期时也会发送	family, client_reference
order.failed	订单未完成	+ refunded
order.refunded	资金已退回	+ refunded
package.traffic_low	剩余流量低于 10%	purchased_gb, left_gb
package.traffic_exhausted	流量已用尽	purchased_gb, left_gb
package.expired	固定地址套餐已到期，地址不响应	expired_at、cut_off（true - 密码已停用，续期时会签发新密码）
topup.credited	充值已到账	amount, external_reference
api_key.revoked	密钥已吊销	api_key_id, name

package.* 事件中的 order_id 字段是购买该套餐的订单。

• 投递方式为 at-least-once：按 id 去重。
• next_after - 下一次请求的位置；null 表示没有新事件。
• events 为空表示你已读到日志末尾。
• 事件保存 30 天。

after = load_position()

while True:
    params = {"limit": 200} | ({"after": after} if after else {})
    body = session.get(f"{BASE}/api/v1/events", params=params, headers=AUTH).json()

    for event in body["events"]:
        if not already_handled(event["id"]):
            handle(event)
            mark_handled(event["id"])

    if body["next_after"] is not None:
        after = body["next_after"]
        save_position(after)

    if not body["events"]:
        sleep(15)

事件只能通过轮询日志获取。