查询余额变动记录 · List Credit History

分页查询当前账户的钻石 / 签到金币变动流水（充值、消费、签到、退款等）。常用于「余额明细」「账单」页面。

仅返回最近 7 天的记录，且每条流水都属于 Token 所属账户本人。

接口地址

POST https://xiangcao.ai/api/list-credit-history

该接口为普通接口，使用 POST 方法。

鉴权

需要在请求头携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

只能查询 Token 所属账户自己的流水。缺少或无效的 Token 会返回 401。

请求体（JSON）

游标值为上一页最后一条记录的 createdAt 毫秒时间戳（字符串）。

类型定义（TypeScript）

interface GetCreditHistoryRequest {
  /** 分页游标；首次不传，翻页传上一页的 nextCursor */
  cursor?: string;
}

响应（JSON）

返回标准分页结构：items 为本页流水（按 createdAt 倒序，每页最多 50 条），nextCursor 为下一页游标（为 null 表示已到末页 / 超出 7 天窗口）。

interface ListCreditHistoryResponse {
  /** 本页流水列表（createdAt 倒序） */
  items: CreditHistoryRecord[];
  /** 下一页游标；为 null 表示没有更多数据 */
  nextCursor: string | null;
}

interface CreditHistoryRecord {
  /** 用户 ID */
  userId: string;
  /** 变动类型，见下方「变动类型」 */
  changeType: CreditChangeType;
  /** 变动数量：正数表示增加，负数表示减少 */
  amount: number;
  /** 来源钱包：checkin=签到金币，account=钻石账户 */
  source: CreditSource;
  /** 消费用途（消费类流水必有；部分入账场景也会标注），见下方「消费用途」 */
  usageType?: CreditUsageType;
  /** 该来源在本次变动后的剩余余额（仅部分消费场景记录，非总余额） */
  remainingInSource?: number;
  /** 变动描述（如任务 ID），用于区分同类型的不同来源 */
  description?: string;
  /** 变动时间（毫秒时间戳） */
  createdAt: number;
}

type CreditSource = 'checkin' | 'account';

变动类型 changeType

消费用途 usageType

分页用法

1. 首次请求不传 cursor，拿到第一页 items 与 nextCursor。
2. 若 nextCursor 不为 null，把它作为下次请求的 cursor 继续拉取。
3. 直到某次响应的 nextCursor 为 null，说明已到末页（或已超出 7 天窗口）。

示例

请求第一页：

curl -X POST "https://xiangcao.ai/api/list-credit-history" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

响应：

{
  "items": [
    {
      "userId": "user_001",
      "changeType": "consume",
      "amount": -310,
      "source": "account",
      "usageType": "text_chat",
      "createdAt": 1733900000000
    },
    {
      "userId": "user_001",
      "changeType": "checkin",
      "amount": 20,
      "source": "checkin",
      "createdAt": 1733890000000
    }
  ],
  "nextCursor": "1733890000000"
}

翻页（回传上一页的 nextCursor）：

curl -X POST "https://xiangcao.ai/api/list-credit-history" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "cursor": "1733890000000"
  }'

错误处理

出错时返回相应 HTTP 状态码及 JSON。