> For the complete documentation index, see [llms.txt](https://docs.bsc.lista.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bsc.lista.org/zh-cn/kai-fa-zhe/services/subscription-module.md).

# 订阅模块

订阅模块允许用户将钱包绑定至 **Telegram** 并接收通知（清算预警、借款利率提醒）。它对客户端应用暴露一套 **REST API**，并通过 **Telegram Bot** 完成绑定与订阅管理。

**Base URL：** `/api/v2/subscription`

***

## 绑定流程

1. 客户端应用调用 **POST /api/v2/subscription/:user/otp**（带钱包签名）-> 服务返回一个 **6 位 OTP**，有效期 **5 分钟**。
2. 用户打开 Telegram Bot 并在聊天中发送该 OTP。
3. Bot 校验 OTP，并将钱包地址与用户的 Telegram ID 绑定。
4. 绑定完成后，用户即可接收**清算预警**与**借款利率提醒**。

***

## REST API

### 1. 查询订阅状态

**GET /api/v2/subscription/:user**

返回指定钱包是否已绑定 Telegram，以及相关的订阅状态。

| 路径参数   | 说明           |
| ------ | ------------ |
| `user` | 钱包地址（例如 0x…） |

### 2. 生成 OTP

**POST /api/v2/subscription/:user/otp**

生成一个一次性 6 位验证码，供用户在 Telegram Bot 中发送以完成绑定。需要**钱包签名**以证明所有权。

| 路径参数   | 说明   |
| ------ | ---- |
| `user` | 钱包地址 |

**请求体：** `signature`、`message`（或等效字段）。服务端从签名与消息中恢复地址；该地址必须与路径中的 `user` 一致。

**响应：** 例如 `{ "otp": "123456" }` 或类似结构（OTP 有效期 5 分钟）。

### 3. 取消订阅（解绑）

**PUT /api/v2/subscription/:user/unsubscribe**

解除钱包与 Telegram 的绑定并停止所有通知。会向用户的 Telegram 发送解绑确认。需要**钱包签名**。

| 路径参数   | 说明   |
| ------ | ---- |
| `user` | 钱包地址 |

**请求体：** `signature`、`message`（或等效字段）。

***

## Telegram Bot

Bot 通过 **Webhook**（内部端点）接收消息。支持的交互如下：

| 命令 / 操作               | 说明                                                                 |
| --------------------- | ------------------------------------------------------------------ |
| **OTP（纯文本）**          | 用户发送由 API 生成的 6 位 OTP → Bot 将钱包绑定至 Telegram。                       |
| **/unbind**           | 显示已绑定钱包列表（内联按钮）；用户选择其一进行解绑。                                        |
| **/subscribe**        | 列出用户持有借款仓位的市场；用户回复市场编号（例如 `1,4`）以订阅**借款利率提醒**。每日 **UTC 02:00** 推送。 |
| **/cancel**           | 列出已订阅的市场；用户回复编号以停止利率提醒。                                            |
| **静音（内联）**            | 预警消息上的内联按钮，可静音**清算预警**或**借款通知**（CDP 与 lending 可分别设置）。              |
| **/change\_language** | 在**中文**与**英文**之间切换 Bot 语言。                                         |

***

## 通知类型

| 类型     | 触发时机 / 内容                                   |
| ------ | ------------------------------------------- |
| 清算预警   | 仓位达到或超过清算阈值；可能附带静音按钮。                       |
| 借款利率提醒 | 针对通过 `/subscribe` 订阅的市场，每日推送（例如 UTC 02:00）。 |
| 解绑确认   | 解绑成功后发送至 Telegram。                          |

***

## 安全与隐私

* 对 OTP 与取消订阅请求校验钱包签名；在未经过 Bot OTP 流程的情况下，不要信任客户端提交的 Telegram ID。
* 消息中只包含该订阅用户本人的仓位/金库信息。
* 只存储最小必要数据（例如 Telegram ID、订阅状态、静音标记）；并考虑数据保留与删除策略。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bsc.lista.org/zh-cn/kai-fa-zhe/services/subscription-module.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.