Frontend API

前端接口文档

这里整理当前项目前端会直接调用的接口，包括登录注册、个人中心、多语言、公开资源、影院、资源、彩票、协议、Web Push 和充值。后台管理接口和三方回调接口暂时不放在这个页面。

基础地址：https://admin.bin9k.top 鉴权：Authorization: Bearer token 语言：Header lang
进入演示 Demo 通用配置演示 首页演示 个人中心演示 充值演示 文章演示 Web Push 演示 协议演示 影院演示 资源演示 彩票演示

演示 Demo

这些页面可以直接调用当前项目的前端接口，登录成功后会保存 token，其他演示页会自动读取。

通用配置 Demo平台货币符号和兑换美元汇率读取测试。 登录/注册 Demo当前平台账号、验证码和 token 测试。 首页 Demo首页聚合、轮播图和滚动通知接口测试。 个人中心 Demo基本资料、密码和银行卡资料维护测试。 充值 Demo银行卡、加密货币下单和凭证上传流程测试。 文章 DemoAPP 起源故事文章详情、排序第一条和封面完整地址测试。 Web Push Demo获取配置、注册浏览器订阅、解除订阅和 service worker 接收测试。 协议 Demo用户协议、隐私协议 PDF 链接获取和打开测试。 影院 Demo影院分类、列表、详情和推荐接口测试。 资源 Demo资源地区、列表和详情接口测试。 彩票 Demo分类、列表、当前期、开奖历史、赔率、下注和投注记录测试。

首页

首页接口用于 H5 首页首屏展示，当前包含首页轮播图和滚动通知。接口只返回后台已启用、未删除的数据；滚动通知会按请求头 lang 优先读取多语言文案。

演示页面
/frontend/home-demo 可直接测试首页聚合、轮播图和滚动通知接口。
通用参数
limit 控制每组最多返回条数，默认 10，最大 50。
GET/api/frontend/home公开

接口名：首页聚合

作用：一次返回首页首屏需要的轮播图和滚动通知。适合 H5 首页初始化时调用。

参数必填说明
limit否每组最多返回条数，默认 10，最大 50。

请求示例

https://admin.bin9k.top/api/frontend/home?limit=10

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "carousels": [
      {
        "id": 1,
        "title": "banner1",
        "image_url": "/api/materials/preview?id=6",
        "image_full_url": "https://admin.bin9k.top/api/materials/preview?id=6",
        "jump_type": "none",
        "jump_type_label": "不跳转",
        "link_url": "",
        "sort": 10,
        "created_at": 1778650407,
        "updated_at": 1778650417
      }
    ],
    "scroll_notices": [
      {
        "id": 1,
        "content": "滚动通知",
        "sort": 10,
        "created_at": 1778650135,
        "updated_at": 1778650148
      }
    ]
  }
}
返回字段说明
carousels首页轮播图列表，按后台排序升序返回。
scroll_notices首页滚动通知列表，按后台排序升序返回。
carousels[].image_url站内图片地址，后台素材预览地址会转换为前端公开预览地址。
carousels[].image_full_url带当前域名的完整图片地址，App 或跨域 H5 推荐使用。
carousels[].jump_type跳转类型：none 不跳转，external 外链。
carousels[].link_url外链地址；不跳转时为空字符串。
scroll_notices[].content滚动通知文案，按请求头 lang 返回对应多语言内容。
GET/api/frontend/home/carousels公开

接口名：首页轮播图

作用：只获取后台内容管理中启用的首页轮播图。图片同时返回站内地址和完整地址。

参数必填说明
limit否最多返回条数，默认 10，最大 50。

请求示例

https://admin.bin9k.top/api/frontend/home/carousels?limit=10

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "can_update_bank_card": 1,
    "list": [
      {
        "id": 1,
        "title": "banner1",
        "image_url": "/api/materials/preview?id=6",
        "image_full_url": "https://admin.bin9k.top/api/materials/preview?id=6",
        "jump_type": "external",
        "jump_type_label": "外链",
        "link_url": "https://example.com",
        "sort": 10,
        "created_at": 1778650407,
        "updated_at": 1778650417
      }
    ],
    "limit": 10
  }
}
返回字段说明
list轮播图列表。
limit本次接口实际使用的返回条数上限。
list[].title后台配置的轮播标题。
list[].image_url站内图片地址。
list[].image_full_url完整图片地址。
list[].jump_typenone 不跳转，external 外链。
list[].jump_type_label跳转类型展示文案。
list[].link_url外链地址，仅 jump_type=external 时有值。
list[].sort后台排序值。
GET/api/frontend/home/scroll-notices公开

接口名：首页滚动通知

作用：只获取后台内容管理中启用的滚动通知。文案会根据请求头 lang 优先读取多语言内容，没有对应翻译时回退后台默认文案。

参数必填说明
limit否最多返回条数，默认 10，最大 50。

请求示例

https://admin.bin9k.top/api/frontend/home/scroll-notices?limit=10
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "can_update_bank_card": 1,
    "can_add_bank_card": 1,
    "bank_card_count": 1,
    "bank_card_max_count": 3,
    "bank_card_duplicate_bind_enabled": 0,
    "list": [
      {
        "id": 1,
        "content": "滚动通知",
        "sort": 10,
        "created_at": 1778650135,
        "updated_at": 1778650148
      }
    ],
    "texts": ["滚动通知"],
    "limit": 10
  }
}
返回字段说明
list通知完整列表。
texts纯文案数组，方便 H5 直接拼接滚动条。
limit本次接口实际使用的返回条数上限。
list[].content按请求头 lang 返回多语言文案。
list[].sort后台排序值。
list[].created_at / updated_at创建和更新时间戳。

通用约定

请求格式
POST 接口推荐使用 application/json，GET 接口使用 query 参数。
语言 Header
lang: zh-CN、lang: en、lang: ja 等 Google 翻译语言码。
Token Header
Authorization: Bearer <access_token>，只在标记“需登录”的接口必填。
分页参数
列表统一使用 page 和 page_size，默认值一般为 1 和 20。

通用成功响应

{
  "code": 0,
  "msg": "成功",
  "data": {}
}

通用失败响应

{
  "code": 400,
  "msg": "错误提示"
          }
GET/api/frontend/common/config公开

接口名：获取通用配置

作用：前端按 option 聚合读取通用配置，当前支持 website、currency；多个值用英文逗号分隔。

请求参数

参数必填说明
option是配置模块，当前支持 website、currency，例如 website,currency。

请求示例

https://admin.bin9k.top/api/frontend/common/config?option=website,currency

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "website": {
      "site_name": "THKTG",
      "logo_url": "/api/materials/preview?id=1",
      "logo_full_url": "https://admin.bin9k.top/api/materials/preview?id=1"
    },
    "currency": {
      "currency_symbol": "JPY",
      "currency_usd_rate": "0.00670000",
      "usd_rate": "0.00670000",
      "base_currency": "USD"
    }
  }
}
返回字段说明
website.site_name站点名称。
website.logo_url后台保存的站点 LOGO 地址。
website.logo_full_url站点 LOGO 完整访问地址，未配置时为空字符串。
currency.currency_symbol平台货币符号。
currency.currency_usd_rate兑换美元汇率，表示 1 平台货币可兑换多少美元。
currency.usd_ratecurrency_usd_rate 的短字段。
currency.base_currency目标兑换货币，当前固定为 USD。
GET/api/frontend/common/platform-currency公开

接口名：获取平台货币配置

作用：读取后台「平台配置 / 平台货币」维护的平台货币符号和兑换美元汇率，用于 H5 金额展示和美元换算。

请求参数

无请求参数。

请求示例

https://admin.bin9k.top/api/frontend/common/platform-currency

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "currency_symbol": "$",
    "currency_usd_rate": "1.00000000",
    "usd_rate": "1.00000000",
    "base_currency": "USD"
  }
}
返回字段说明
currency_symbol平台货币符号，例如 $、¥、Rp。
currency_usd_rate兑换美元汇率，表示 1 平台货币可兑换多少美元，保留 8 位小数。
usd_ratecurrency_usd_rate 的兼容短字段，便于前端换算读取。
base_currency目标兑换货币，当前固定为 USD。
GET/api/frontend/common/platform-customer-services公开

接口名：获取平台客服

作用：读取后台「客服管理 / 平台客服」启用的客服列表，并按后台配置的展示类型顺序返回；请求携带用户 Token 时，如果配置了代理客服，会追加当前用户上级代理绑定的客服。

请求参数

无请求参数，Authorization 可选，携带后用于匹配代理客服。

请求示例

https://admin.bin9k.top/api/frontend/common/platform-customer-services

返回示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "customer_service_types": [
      {
        "type": "platform",
        "label": "平台客服",
        "available_count": 2
      },
      {
        "type": "agent",
        "label": "代理客服",
        "available_count": 1
      }
    ],
    "list": [
      {
        "id": 1,
        "source_type": "platform",
        "source_text": "平台客服",
        "name": "在线客服",
        "url": "https://example.com/support",
        "status": 1,
        "sort": 10
      },
      {
        "id": 88,
        "source_type": "agent",
        "source_text": "代理客服",
        "name": "agent001",
        "url": "https://example.com/agent-support",
        "status": 1,
        "sort": 0
      }
    ],
    "count": 2
  }
}
返回字段说明
customer_service_types后台配置的客服展示类型顺序。
customer_service_types[].type客服来源：platform 平台客服，agent 代理客服。
customer_service_types[].label客服来源展示文案，会根据请求语言返回。
customer_service_types[].available_count当前来源下可返回的客服数量。
list按展示类型顺序合并后的客服列表。
list[].id客服 ID；代理客服为代理会员 ID。
list[].source_type客服来源：platform、agent。
list[].source_text客服来源展示文案，会根据请求语言返回。
list[].name客服名称。
list[].url客服跳转地址。
list[].status状态，1 可用。
list[].sort来源内部排序值。
count本次返回客服数量。

登录注册

登录注册配置由后台「平台配置 / 登录注册配置」控制。图片验证码关闭后，登录和注册不需要传验证码；邀请码开启必填后，注册必须传入有效的邀请码。

演示页面
/frontend/login-demo 会自动读取登录注册配置，并按配置展示验证码和邀请码提示。
层级关系
注册传入邀请码后会绑定直接上级，系统同时保存上三级快照和无限层级闭包关系。

接入流程

步骤说明
1先调用 /api/frontend/auth/config，读取验证码、邀请码和 IP 注册限制配置。
2captcha_enabled=1 时调用验证码接口，并在登录/注册时传 captcha_id、captcha_code。
3invite_required=1 时注册必须传 invite_code 或 agent_code。
4登录、注册、刷新 token 成功后，前端都要保存新的 access_token 和 refresh_token。
GET/api/frontend/auth/config公开

接口名：获取登录注册配置

作用：返回登录注册页初始化需要的公开配置。前端应根据这些字段决定是否展示验证码、邀请码必填提示。

请求示例

https://admin.bin9k.top/api/frontend/auth/config

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "configured": true,
    "token_configured": true,
    "issuer": "jplander-frontend",
    "access_ttl": 7200,
    "refresh_ttl": 2592000,
    "captcha_ttl": 300,
    "password_login_enabled": true,
    "captcha_enabled": 1,
    "invite_required": 0,
    "ip_limit_enabled": 1,
    "max_accounts_per_ip": 2
  }
}
返回字段说明
captcha_enabled是否开启图片验证码，1 开启，0 关闭。
invite_required注册是否必须填写邀请码。
ip_limit_enabled是否限制同 IP 注册账号数量。
max_accounts_per_ip同 IP 最多可注册账号数。
GET/api/frontend/auth/captcha公开

接口名：获取图片验证码

作用：生成一次性图片验证码。仅当登录配置 captcha_enabled=1 时需要调用。

请求示例

https://admin.bin9k.top/api/frontend/auth/captcha

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "captcha_id": "cap_xxxxx",
    "image": "data:image/svg+xml;base64,xxxxx",
    "expires_in": 300
  }
}
返回字段说明
captcha_id验证码 ID，登录或注册时原样传回。
imagebase64 SVG 图片，可直接赋值给 img.src。
expires_in验证码有效秒数。
POST/api/frontend/auth/register公开

接口名：会员注册

作用：注册平台会员账号，注册成功后直接返回登录 token。邀请码填写后会绑定直接上级，并写入上三级快照和无限层级关系。

参数必填说明
account是会员账号，对应会员表用户名。
password是密码。
password_confirm否确认密码，传入时必须与 password 一致。
invite_code配置决定邀请码；后台配置为必填时必须传，填写后会校验有效性。
agent_code否邀请码别名；同时传时优先使用 invite_code。
phone否手机号。
captcha_id / captcha_code配置决定后台开启图片验证码时必填。
device_name否设备名称，例如 h5。

请求示例

{
  "account": "member001",
  "password": "123456",
  "password_confirm": "123456",
  "invite_code": "M000001",
  "captcha_id": "cap_xxxxx",
  "captcha_code": "ABCD",
  "device_name": "h5"
}

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "access_token": "access_token_xxxxx",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "refresh_token_xxxxx",
    "refresh_expires_in": 2592000,
    "user": {
      "id": 1,
      "source_type": "member",
      "source_text": "会员账号",
      "username": "member001",
      "account": "member001",
      "agent_code": "M000002",
      "parent_id": 1,
      "ancestor_1_id": 1,
      "ancestor_2_id": 0,
      "ancestor_3_id": 0,
      "level_depth": 1,
      "language": "zh-CN",
      "balance": "0.00",
      "status": 1,
      "created_at": 1774411200,
      "created_time": "2026-03-25 12:00:00"
    }
  }
}
返回字段说明
access_token后续接口鉴权 token，请放到 Authorization: Bearer <access_token>。
refresh_token刷新 token，用于换取新的访问 token。
user.agent_code当前会员自己的邀请码，可用于邀请下级注册。
user.parent_id直接上级会员 ID，没有上级时为 0。
user.ancestor_1_id / ancestor_2_id / ancestor_3_id上三级快照，方便快速查找。
user.level_depth当前会员所在层级深度。
POST/api/frontend/auth/login公开

接口名：会员账号密码登录

图片验证码是否必填同样由 /api/frontend/auth/config 的 captcha_enabled 控制。

参数必填说明
account是会员账号。
password是密码。
captcha_id / captcha_code配置决定后台开启图片验证码时必填。
device_name否设备名称。

请求示例

{
  "account": "member001",
  "password": "123456",
  "captcha_id": "cap_xxxxx",
  "captcha_code": "ABCD",
  "device_name": "h5"
}

返回说明

返回字段与注册成功一致。登录成功会更新 last_login_at、last_login_time。

POST/api/frontend/auth/refresh公开

接口名：刷新 Token

作用：使用 refresh_token 换取新的 token。刷新成功后会轮换刷新令牌，旧的 refresh_token 不应继续使用。

参数必填说明
refresh_token是登录、注册或上次刷新返回的刷新令牌。
device_name否设备名称。

请求示例

{
  "refresh_token": "refresh_token_xxxxx",
  "device_name": "h5"
}

返回说明

返回新的 access_token、refresh_token 和当前用户信息。

GET/api/frontend/auth/me需登录

接口名：获取当前登录用户

请求示例

https://admin.bin9k.top/api/frontend/auth/me
Authorization: Bearer <access_token>

返回字段

字段说明
id会员用户 ID。
account / username会员账号。
avatar用户头像完整访问地址，没有头像时为空字符串。
balance用户余额，字符串金额。
agent_code当前会员邀请码。
registered_time / last_login_time注册和最后登录时间。
POST/api/frontend/auth/language需登录

接口名：更新当前用户语言

参数必填说明
language是语言码，例如 zh-CN、en，必须是后台启用语言。
POST/api/frontend/auth/logout需登录

接口名：退出登录

作用：吊销当前登录会话。退出后当前 access_token 和对应刷新令牌都会失效。

请求示例

https://admin.bin9k.top/api/frontend/auth/logout
Authorization: Bearer <access_token>

返回示例

{
  "code": 0,
  "msg": "成功"
}

常见错误

场景HTTP 状态提示示例
账号或密码错误400账号或密码错误
验证码错误或过期400验证码错误 / 验证码已过期
邀请码必填但未传400请填写邀请码
邀请码无效400邀请码无效
同 IP 注册达到上限400当前 IP 注册数量已达上限
token 无效或过期401访问令牌无效 / 登录会话已过期

个人中心

个人中心接口都需要登录，前端请求头携带 Authorization: Bearer <access_token>。银行卡资料用于提款资料维护，添加和修改时必须校验支付密码，持卡人姓名必须与真实姓名一致。

演示页面
/frontend/profile-demo 可直接测试基本资料、登录密码、支付密码、银行卡和资金明细接口。
支付密码
首次设置支付密码可不传旧密码；已设置后修改和银行卡维护都需要校验支付密码。
GET/api/frontend/user/info需登录

接口名：获取个人中心资料

参数必填说明
无请求参数。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 1,
    "account": "member001",
    "real_name": "张三",
    "gender": "male",
    "gender_text": "男",
    "balance": "1000.00",
    "has_payment_password": 1,
    "status": 1
  }
}
返回字段类型说明
idint当前会员 ID。
accountstring会员账号。
real_namestring真实姓名。
genderstring性别枚举：male、female、unknown。
gender_textstring性别展示文案。
balancestring当前余额。
has_payment_passwordint是否已设置支付密码。
statusint账号状态。
POST/api/frontend/user/real-name需登录

接口名：设置真实姓名

参数必填说明
real_name是真实姓名，兼容 name。
{
  "real_name": "张三"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "real_name": "张三",
    "user": {
      "id": 1,
      "account": "member001",
      "real_name": "张三"
    }
  }
}
返回字段类型说明
real_namestring保存后的真实姓名。
userobject保存后的当前用户信息。
user.real_namestring当前用户真实姓名。
POST/api/frontend/user/gender需登录

接口名：设置性别

参数必填说明
gender是male、female、unknown，兼容 sex。
{
  "gender": "male"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "gender": "male",
    "gender_text": "男",
    "user": {
      "id": 1,
      "gender": "male",
      "gender_text": "男"
    }
  }
}
返回字段类型说明
genderstring保存后的性别枚举。
gender_textstring保存后的性别文案。
user.genderstring当前用户性别枚举。
POST/api/frontend/user/login-password需登录

接口名：修改登录密码

参数必填说明
old_password是旧登录密码。
new_password是新登录密码，6 到 64 位。
new_password_confirm是确认新登录密码。
{
  "old_password": "123456",
  "new_password": "654321",
  "new_password_confirm": "654321"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "changed": 1,
    "user": {
      "id": 1,
      "account": "member001",
      "updated_at": 1774415000
    }
  }
}
返回字段类型说明
changedint是否修改成功。
userobject修改后的当前用户信息。
POST/api/frontend/user/payment-password需登录

接口名：设置或修改支付密码

参数必填说明
old_payment_password条件必填已设置过支付密码时必填。
new_payment_password是新支付密码，6 到 64 位。
new_payment_password_confirm是确认新支付密码。
{
  "old_payment_password": "123456",
  "new_payment_password": "654321",
  "new_payment_password_confirm": "654321"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "changed": 1,
    "has_payment_password": 1,
    "user": {
      "id": 1,
      "has_payment_password": 1
    }
  }
}
返回字段类型说明
changedint是否设置或修改成功。
has_payment_passwordint设置后固定为 1。
user.has_payment_passwordint当前用户是否已设置支付密码。
GET/api/frontend/user/bank-cards需登录

接口名：获取银行卡列表

参数必填说明
无请求参数。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "account_name": "张三",
        "bank_name": "中国银行",
        "branch_name": "深圳南山支行",
        "branch_no": "104584000001",
        "card_no": "6222020202020202020",
        "card_no_masked": "6222 **** **** 2020",
        "status": 1
      }
    ]
  }
}
返回字段类型说明
can_update_bank_cardint是否允许用户修改已绑定银行卡，由后台提现配置控制。
can_add_bank_cardint是否还能继续添加银行卡，1 可以，0 已达到绑定数量上限。
bank_card_countint当前用户已绑定银行卡数量。
bank_card_max_countint每用户可绑定银行卡数量，0 表示不限制。
bank_card_duplicate_bind_enabledint是否允许同一张卡号重复绑定。
listarray当前会员银行卡列表。
list[].idint银行卡 ID。
list[].account_namestring持卡人姓名。
list[].bank_namestring银行名称。
list[].branch_namestring分行名称。
list[].branch_nostring分行编号。
list[].card_nostring完整银行卡号。
list[].card_no_maskedstring脱敏银行卡号。
POST/api/frontend/user/bank-cards/create需登录

接口名：添加银行卡

达到后台配置的每用户绑卡数量时会返回错误；后台关闭“允许重复绑定卡号”时，同一张卡号不能被任何用户重复绑定。

参数必填说明
account_name是持卡人姓名，必须与真实姓名一致。
bank_name是银行名称。
branch_name是分行名称。
branch_no是分行编号。
card_no是银行卡号。
payment_password是支付密码。
{
  "account_name": "张三",
  "bank_name": "中国银行",
  "branch_name": "深圳南山支行",
  "branch_no": "104584000001",
  "card_no": "6222020202020202020",
  "payment_password": "654321"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "item": {
      "id": 1,
      "account_name": "张三",
      "bank_name": "中国银行",
      "card_no_masked": "6222 **** **** 2020",
      "status": 1
    },
    "can_update_bank_card": 1,
    "can_add_bank_card": 1,
    "bank_card_count": 1,
    "bank_card_max_count": 3,
    "bank_card_duplicate_bind_enabled": 0,
    "list": []
  }
}
返回字段类型说明
itemobject本次新增的银行卡。
item.idint银行卡 ID。
item.account_namestring持卡人姓名。
item.bank_namestring银行名称。
item.branch_namestring分行名称。
item.branch_nostring分行编号。
item.card_nostring完整银行卡号。
item.card_no_maskedstring脱敏银行卡号。
item.statusint状态，1 启用。
item.created_at / updated_atint创建和更新时间戳。
can_update_bank_cardint是否允许用户修改已绑定银行卡。
can_add_bank_cardint是否还能继续添加银行卡。
bank_card_countint添加后当前用户已绑定银行卡数量。
bank_card_max_countint每用户可绑定银行卡数量，0 表示不限制。
bank_card_duplicate_bind_enabledint是否允许同一张卡号重复绑定。
listarray添加后的银行卡列表。
POST/api/frontend/user/bank-cards/update需登录

接口名：修改银行卡

后台“提现配置 - 银行卡 - 允许用户修改银行卡”关闭时，本接口会返回错误，不允许修改；后台关闭“允许重复绑定卡号”时，同一张卡号不能被任何用户重复绑定。

参数必填说明
id是银行卡 ID，只能修改当前会员自己的银行卡。
account_name是持卡人姓名，必须与真实姓名一致。
bank_name是银行名称。
branch_name是分行名称。
branch_no是分行编号。
card_no是银行卡号。
payment_password是支付密码。
{
  "id": 1,
  "account_name": "张三",
  "bank_name": "中国银行",
  "branch_name": "深圳科技园支行",
  "branch_no": "104584000002",
  "card_no": "6222020202020202020",
  "payment_password": "654321"
}
{
  "code": 0,
  "msg": "成功",
  "data": {
    "item": {
      "id": 1,
      "account_name": "张三",
      "bank_name": "中国银行",
      "branch_name": "深圳科技园支行",
      "updated_at": 1774415000
    },
    "can_update_bank_card": 1,
    "can_add_bank_card": 1,
    "bank_card_count": 1,
    "bank_card_max_count": 3,
    "bank_card_duplicate_bind_enabled": 0,
    "list": []
  }
}
返回字段类型说明
itemobject修改后的银行卡。
item.idint银行卡 ID。
item.account_namestring持卡人姓名。
item.bank_namestring银行名称。
item.branch_namestring分行名称。
item.branch_nostring分行编号。
item.card_nostring完整银行卡号。
item.card_no_maskedstring脱敏银行卡号。
item.statusint状态，1 启用。
item.updated_atint更新时间戳。
can_update_bank_cardint是否允许用户继续修改已绑定银行卡。
can_add_bank_cardint是否还能继续添加银行卡。
bank_card_countint修改后当前用户已绑定银行卡数量。
bank_card_max_countint每用户可绑定银行卡数量，0 表示不限制。
bank_card_duplicate_bind_enabledint是否允许同一张卡号重复绑定。
listarray修改后的银行卡列表。
GET/api/frontend/user/balance-logs需登录

接口名：用户资金变动明细

返回当前登录会员自己的资金明细，H5 可根据 direction 区分入账和出账颜色。

参数必填说明
page否页码，默认 1。
page_size否每页数量，默认 20，最大 50。
type否按账变类型筛选，例如 奖金、任务。
direction否income 入账，expense 出账。
GET https://admin.bin9k.top/api/frontend/user/balance-logs?page=1&page_size=20
Authorization: Bearer <access_token>
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "type_text": "奖金",
        "direction": "income",
        "amount_text": "+19.80",
        "remark": "活动二202605131579鸡",
        "created_time": "2026-05-13 14:55:01"
      }
    ],
    "total": 152,
    "page": 1,
    "page_size": 20
  }
}
返回字段类型说明
listarray资金变动记录列表。
list[].type_textstring账变类型展示文案，会根据请求头 lang 返回对应语言。
list[].directionstringincome 入账、expense 出账，用于控制金额颜色。
list[].direction_textstring收支方向文案，会根据请求头 lang 返回对应语言。
list[].amount_textstring带正负号的展示金额。
list[].remarkstring备注文案，会根据请求头 lang 返回对应语言。
list[].created_timestring格式化创建时间。
total / page / page_sizeint分页信息。

公开资源

GET/api/materials/preview公开

预览后台素材库中的图片等可公开预览资源。该接口直接返回文件流，不返回通用 JSON。

参数必填说明
id是素材 ID。
https://admin.bin9k.top/api/materials/preview?id=1
GET/api/frontend/articles/app-origin-story公开

接口名：APP起源故事文章详情

作用：查询后台文章管理中分类为“APP起源故事”、状态为已发布且排序第一的文章详情；没有配置时 data 返回空对象。

请求示例

https://admin.bin9k.top/api/frontend/articles/app-origin-story

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 1,
    "title": "APP起源故事",
    "category": "origin_story",
    "category_text": "APP起源故事",
    "summary": "文章摘要",
    "content": "<p>文章正文</p>",
    "cover_preview_url": "/api/materials/preview?id=1",
    "cover_full_url": "https://admin.bin9k.top/api/materials/preview?id=1",
    "sort": 1,
    "created_at": 1774411200,
    "updated_at": 1774411300
  }
}
返回字段说明
id文章 ID；没有配置时 data 为空对象。
title文章标题，支持后台多语言配置。
summary文章摘要，支持后台多语言配置。
content文章正文 HTML，支持后台多语言配置。
cover_preview_url站内封面预览地址。
cover_full_url可直接访问的完整封面地址。
created_at / updated_at创建和更新时间戳。

协议

前端可通过公开接口获取后台配置的用户协议和隐私协议 PDF 链接。后台支持上传 PDF 或填写远程 PDF 地址。

GET/api/frontend/agreements公开

接口名：获取协议链接

作用：返回启用的协议列表；可传 type 只获取某一种协议。

参数必填说明
type否协议类型：user_agreement 用户协议，privacy_policy 隐私协议。不传返回全部。

请求示例

https://admin.bin9k.top/api/frontend/agreements?type=user_agreement

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "key": "user_agreement",
        "title": "用户协议",
        "source_type": "upload",
        "url": "/api/materials/preview?id=12",
        "full_url": "https://admin.bin9k.top/api/materials/preview?id=12",
        "updated_at": 1774411200
      }
    ],
    "agreements": {
      "user_agreement": {
        "key": "user_agreement",
        "title": "用户协议",
        "source_type": "upload",
        "url": "/api/materials/preview?id=12",
        "full_url": "https://admin.bin9k.top/api/materials/preview?id=12",
        "updated_at": 1774411200
      }
    },
    "item": null
  }
}
返回字段说明
list协议列表，按后台排序返回。
agreements以协议 key 为键的协议对象，方便前端按类型读取。
item传入 type 时返回对应协议；未找到时为 null。
list[].source_typeupload 后台上传 PDF，remote 远程 PDF 链接。
list[].full_url可直接访问的完整 PDF 地址，前端推荐优先使用。

语言

GET/api/frontend/languages公开

获取后台启用的语言列表。列表排序第一项就是接口提示的默认语言。

返回示例

{
  "code": 0,
  "data": {
    "list": [
      {"code": "zh-CN", "name": "简体中文", "native_name": "简体中文", "sort": 1}
    ]
  }
}
返回字段说明
list[]启用语言列表，按后台拖拽排序返回。
list[].codeGoogle 翻译语言码，例如 zh-CN、en、ja。
list[].name后台配置的语言名称。
list[].native_name语言本地名称。
list[].sort排序值；第一项是默认语言。

Web Push

Web Push 用于前端浏览器订阅推送、取消订阅和读取后台推送配置。浏览器端需要先注册 service worker，再调用 Push API 生成 subscription，并把 subscription 提交给后台保存。

运行环境
浏览器 Push API 只允许在 HTTPS 或 localhost/127.0.0.1 下使用，线上域名必须配置 HTTPS。
订阅归属
订阅记录按当前登录用户保存，所有接口都需要 Authorization: Bearer <access_token>。
演示页面
/frontend/webpush-demo 已提供配置读取、订阅、解除订阅和本地通知测试。
GET/api/frontend/push/config需登录

接口名：获取 Web Push 配置

作用：获取当前站点 Web Push 开关、VAPID 公钥、默认图标、默认点击跳转地址，并判断当前用户是否已有有效订阅。

请求参数必填说明
无。请求头必须携带 Authorization，可选携带 lang。

请求示例

GET https://admin.bin9k.top/api/frontend/push/config
Authorization: Bearer <access_token>
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "status": 1,
    "public_key": "BKn1...example",
    "default_icon": "https://admin.bin9k.top/storage/push/default.png",
    "default_icon_raw": "/storage/push/default.png",
    "default_url": "/",
    "subscribed": 1
  }
}
返回字段说明
statusWeb Push 入口状态：1 启用，0 禁用。禁用时前端不应发起订阅。
public_keyVAPID 公钥，前端传给 pushManager.subscribe() 的 applicationServerKey。
default_icon默认通知图标的完整访问地址，前端展示或 service worker 兜底时使用。
default_icon_raw后台保存的原始图标路径。
default_url默认通知点击跳转地址，推送模板没有配置跳转地址时使用。
subscribed当前登录用户是否存在启用中的订阅：1 是，0 否。
POST/api/frontend/push/subscribe需登录

接口名：保存浏览器推送订阅

作用：前端通过浏览器 Push API 获取 subscription 后提交到后台。后台会优先按 user_id + device_id 判断同一用户的同一设备，已存在则更新订阅；没有传 device_id 时按 endpoint_hash 兼容旧逻辑。

参数必填说明
device_id建议必填前端为当前浏览器设备生成并长期保存的稳定 ID。用于同一用户同一设备更新订阅，避免重复创建订阅记录。也可以放在 subscription.device_id。
subscription.endpoint是浏览器 Push 服务生成的 endpoint。
subscription.keys.p256dh是浏览器订阅公钥。
subscription.keys.auth是浏览器订阅 auth token。
subscription.expirationTime否浏览器返回的过期时间，当前后台只保存原始数据。

请求示例

POST https://admin.bin9k.top/api/frontend/push/subscribe
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "device_id": "web-7e9f0a8c-4b3c-4d6a-9a8b-1234567890ab",
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/example-token",
    "expirationTime": null,
    "keys": {
      "p256dh": "BMM...browser-public-key",
      "auth": "x7g...auth-token"
    }
  }
}

返回示例

{
  "code": 0,
  "msg": "订阅成功",
  "data": {
    "subscribed": 1,
    "subscription": {
      "id": 1,
      "endpoint": "https://fcm.googleapis.com/fcm/send/example-token",
      "endpoint_hash": "9c1d1b0e...",
      "device_id": "web-7e9f0a8c-4b3c-4d6a-9a8b-1234567890ab",
      "device_hash": "0b8f0a7c...",
      "status": 1,
      "created_at": 1777276800,
      "updated_at": 1777276800
    }
  }
}
返回字段说明
subscribed订阅状态，成功保存后固定为 1。
subscription.id后台订阅记录 ID。
subscription.endpoint浏览器 Push endpoint。
subscription.endpoint_hashendpoint 的 MD5，后台用于去重和展示。
subscription.device_id前端传入的设备 ID。同一用户再次使用相同 device_id 订阅时会更新这条记录。
subscription.device_hash设备 ID 的服务端哈希，用于唯一约束。
subscription.status订阅记录状态：1 启用，0 停用。
POST/api/frontend/push/unsubscribe需登录

接口名：取消浏览器推送订阅

作用：把当前用户指定 endpoint 的订阅记录置为停用。前端也应该同步调用浏览器原生的 subscription.unsubscribe()。

参数必填说明
endpoint是要取消的浏览器 Push endpoint。也可以传 subscription.endpoint。

请求示例

POST https://admin.bin9k.top/api/frontend/push/unsubscribe
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/example-token"
}

返回示例

{
  "code": 0,
  "msg": "取消订阅成功",
  "data": {
    "subscribed": 0
  }
}
返回字段说明
subscribed取消后的订阅状态，成功后为 0。

前端接入流程示例

const config = await fetch('/api/frontend/push/config', {
  headers: { Authorization: 'Bearer ' + token, lang: 'zh-CN' }
}).then(res => res.json());

const registration = await navigator.serviceWorker.register('/frontend-webpush-sw.js');
await Notification.requestPermission();
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(config.data.public_key)
});
const deviceId = localStorage.getItem('alpha_push_device_id') || crypto.randomUUID();
localStorage.setItem('alpha_push_device_id', deviceId);

await fetch('/api/frontend/push/subscribe', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + token,
    lang: 'zh-CN'
  },
  body: JSON.stringify({ device_id: deviceId, subscription: subscription.toJSON() })
});

充值

充值方式接口返回后台开启展示的充值入口，当前支持银行卡、加密货币和线下充值。每种充值方式都可返回多语言富文本充值规则；线下充值会把后台配置的充值客服、平台客服、代理客服按运营拖拽顺序合并返回。

演示页面
/frontend/recharge-demo 可直接测试充值方式、线下客服、银行卡和加密货币流程。
线下客服排序
后台“充值配置 - 线下充值”中排在前面的客服来源，会在 customer_services 中优先返回。
GET/api/frontend/recharge/methods公开

接口名：获取充值方式

参数必填说明
无。可选携带 Authorization，用于后续支持按登录用户返回代理客服。
GET https://admin.bin9k.top/api/frontend/recharge/methods
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "method": "offline",
        "name": "线下充值",
        "display_status": 1,
        "enable_status": 1,
        "enabled": 1,
        "available_count": 2,
        "status_text": "联系客服充值",
        "rule_html": "<p>选择客服后请按客服指引完成线下充值。</p>",
        "rule_content": "<p>选择客服后请按客服指引完成线下充值。</p>",
        "description": "选择客服后跳转，由客服协助完成线下充值",
        "customer_service_types": [
          {
            "type": "recharge",
            "label": "充值客服",
            "available_count": 1
          },
          {
            "type": "platform",
            "label": "平台客服",
            "available_count": 1
          }
        ],
        "customer_services": [
          {
            "id": 1,
            "source_type": "recharge",
            "source_text": "充值客服",
            "name": "充值客服A",
            "url": "https://service.example.com/recharge-a",
            "status": 1,
            "sort": 10
          }
        ]
      }
    ],
    "proof_upload": {
      "upload_url": "https://v1.imgstoragebobo.com/api/uploads",
      "field": "cert",
      "public_base_url": "https://v1.imgstoragebobo.com",
      "path_replace_from": "public/",
      "path_replace_to": "storage/"
    }
  }
}
返回字段类型说明
list[].methodstringbank 银行卡，crypto 加密货币，offline 线下充值。
list[].namestring充值方式展示名称。
list[].display_statusint展示状态，1 表示该方式会返回给前端。
list[].enable_statusint启用状态，1 可用，0 不可用。
list[].enabledint是否可进入该充值方式。
list[].available_countint当前方式下可用收款账户、渠道或客服数量。
list[].status_textstring后台配置的状态文案，支持多语言。
list[].rule_htmlstring后台配置的充值规则富文本 HTML，支持多语言，未配置时为空。
list[].rule_contentstring充值规则富文本内容，和 rule_html 一致，方便前端按原字段名读取。
list[].descriptionstring充值方式说明文案。
list[].customer_service_typesarray仅线下充值返回，客服来源类型和顺序。
customer_service_types[].typestringrecharge 充值客服，platform 平台客服，agent 代理客服。
customer_service_types[].labelstring客服来源展示文案。
customer_service_types[].available_countint当前来源下可返回的客服数量。
list[].customer_servicesarray仅线下充值返回，按后台配置顺序合并后的客服列表。
customer_services[].idint客服 ID，平台客服为 0。
customer_services[].source_typestringrecharge 充值客服，platform 平台客服，agent 代理客服。
customer_services[].source_textstring客服来源展示文案。
customer_services[].namestring客服名称。
customer_services[].urlstring客服跳转地址。
customer_services[].statusint状态，1 可用。
customer_services[].sortint来源内部排序值。
proof_uploadobject转账凭证上传配置，银行卡和手动加密货币充值提交凭证时使用。
proof_upload.upload_urlstring凭证上传地址。
proof_upload.fieldstring上传文件字段名。
proof_upload.public_base_urlstring上传后文件访问域名。
proof_upload.path_replace_fromstring上传服务返回路径需要替换的前缀。
proof_upload.path_replace_tostring上传服务返回路径替换后的前缀。
GET/api/frontend/recharge/offline/customer-services公开

接口名：获取线下充值客服列表

作用：用户选择线下充值后，单独拉取可展示的客服列表，方便充值页按运营配置顺序展示客服入口。

参数必填说明
无请求参数。可选携带 Authorization，用于返回登录用户相关的代理客服。

请求示例

GET https://admin.bin9k.top/api/frontend/recharge/offline/customer-services
Authorization: Bearer <access_token>
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "enabled": 1,
    "customer_service_types": [
      {
        "type": "recharge",
        "label": "充值客服",
        "available_count": 1
      },
      {
        "type": "platform",
        "label": "平台客服",
        "available_count": 1
      }
    ],
    "list": [
      {
        "id": 1,
        "source_type": "recharge",
        "source_text": "充值客服",
        "name": "充值客服A",
        "url": "https://service.example.com/recharge-a",
        "status": 1,
        "sort": 10
      }
    ],
    "count": 1
  }
}
返回字段类型说明
enabledint线下充值入口是否启用。
customer_service_typesarray后台配置的客服来源顺序。
customer_service_types[].typestringrecharge 充值客服，platform 平台客服，agent 代理客服。
customer_service_types[].labelstring客服来源展示文案。
customer_service_types[].available_countint当前来源下可返回的客服数量。
listarray充值页展示的客服列表。
list[].idint客服 ID，平台客服为 0。
list[].source_typestringrecharge 充值客服，platform 平台客服，agent 代理客服。
list[].source_textstring客服来源展示文案。
list[].namestring客服名称。
list[].urlstring客服跳转地址。
list[].statusint状态，1 可用。
list[].sortint来源内部排序值。
countint本次返回的客服数量。
GET/api/frontend/recharge/crypto/channels公开

接口名：获取加密货币充值渠道

作用：返回已启用的加密货币充值渠道，平铺列表和按币种聚合列表都会带上当前平台币换算汇率。

参数必填说明
无请求参数。

请求示例

GET https://admin.bin9k.top/api/frontend/recharge/crypto/channels

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "channel_key": "TRC20-USDT",
        "chain": "TRC20",
        "coin": "USDT",
        "module": 1,
        "min_amount": "10",
        "max_amount": "0",
        "exchange_rate": "1",
        "platform_currency": "JPY",
        "platform_usd_rate": "0.00670000",
        "crypto_platform_rate": "149.25373134",
        "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY",
        "buttons": ["10", "20", "50"]
      }
    ],
    "coins": [
      {
        "coin": "USDT",
        "name": "USDT",
        "networks": []
      }
    ]
  }
}
返回字段类型说明
list[]array平铺渠道列表。
coins[]array按币种聚合后的列表。
coins[].networksarray该币种可选择的网络，字段结构同 list[]。
channel_keystring渠道唯一 key，可用于创建订单和查询当前订单。
exchange_ratestring当前有效的加密货币兑 USD 汇率。
platform_currencystring平台货币符号。
platform_usd_ratestring平台货币兑 USD 汇率。
crypto_platform_ratestring1 个加密货币可折算的平台币数量。
crypto_platform_rate_textstring1加密货币 = 多少平台币 的展示文案。
GET/api/frontend/recharge/crypto/orders/current需登录

接口名：查询当前加密货币待充值订单

作用：用户选中币种网络后查询是否已有待充值订单；无论是否存在订单，channel 都会返回当前平台币换算汇率。

参数必填说明
channel_key推荐渠道唯一 key，例如 TRC20-USDT。
id二选一渠道 ID，没有传 channel_key 时可用。
chain / coin二选一网络和币种一起传入时可生成渠道 key。

请求示例

GET https://admin.bin9k.top/api/frontend/recharge/crypto/orders/current?channel_key=TRC20-USDT
Authorization: Bearer <access_token>
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "has_order": 1,
    "channel": {
      "channel_key": "TRC20-USDT",
      "chain": "TRC20",
      "coin": "USDT",
      "module": 1,
      "exchange_rate": "1",
      "platform_currency": "JPY",
      "platform_usd_rate": "0.00670000",
      "crypto_platform_rate": "149.25373134",
      "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY"
    },
    "order": {
      "order_no": "RC202604231200001234",
      "method": "crypto",
      "channel_name": "TRC20 / USDT",
      "amount": "100",
      "crypto_platform_rate": "149.25373134",
      "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY",
      "status": 0,
      "status_text": "待充值",
      "can_cancel": 1
    },
    "wallet": {
      "address": "Txxxxxxxxxxxxxxxx"
    }
  }
}
返回字段类型说明
has_orderint1 存在待充值订单，0 没有。
channelobject当前选择的加密货币渠道信息。
channel.crypto_platform_ratestring1 个加密货币可折算的平台币数量。
channel.crypto_platform_rate_textstring1加密货币 = 多少平台币 的展示文案。
orderobject存在待充值订单时返回，字段结构和订单详情一致。
order.crypto_platform_ratestring订单锁定汇率下 1 个加密货币可折算的平台币数量。
wallet.addressstring前端需要展示的收款钱包地址。
GET/api/frontend/recharge/orders需登录

接口名：获取用户充值记录

作用：分页返回当前用户的银行卡和加密货币充值记录，只返回 H5 记录页展示和操作需要的字段。

参数必填说明
method否bank 银行卡，crypto 加密货币；不传返回全部。
status否0 待充值，1 已到账，2 充值失败，3 已取消，4 自动取消。
page否页码，默认 1。
page_size否每页数量，默认 10，最大 50。

请求示例

GET https://admin.bin9k.top/api/frontend/recharge/orders?page=1&page_size=10&method=crypto
Authorization: Bearer <access_token>
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 21,
        "order_no": "RC202604231200001234",
        "method": "crypto",
        "method_name": "加密货币",
        "channel_name": "TRC20 / USDT",
        "account_summary": "Txxxxxxxxxxxxxxxx",
        "amount": "100",
        "amount_unit": "USDT",
        "paid_amount": "0",
        "paid_amount_unit": "USDT",
        "arrive_amount": "0",
        "arrive_unit": "JPY",
        "platform_currency": "JPY",
        "platform_currency_symbol": "JPY",
        "platform_usd_rate": "0.00670000",
        "status": 0,
        "status_text": "待充值",
        "status_type": "warning",
        "proof_required": 0,
        "cert_url": "",
        "cert_is_image": 0,
        "can_cancel": 1,
        "created_at": 1710000000,
        "created_time": "2024-03-10 12:00:00",
        "paid_at": 0,
        "paid_time": "",
        "chain": "TRC20",
        "coin": "USDT",
        "module": 1,
        "module_text": "代收",
        "rate_display": "1",
        "crypto_usd_rate": "1",
        "crypto_usd_amount": "100",
        "rate_text": "1 USDT = 1 USD",
        "platform_rate_text": "1 JPY = 0.0067 USD",
        "expected_arrival_amount": "14925.37313433",
        "expected_arrival_currency": "JPY",
        "expire_time": 1710001800,
        "countdown_seconds": 1800
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "method": "crypto",
    "status": ""
  }
}
返回字段类型说明
listarray当前页充值记录列表，按创建时间倒序。
totalint符合筛选条件的总数量。
list[].order_nostring充值订单号。
list[].methodstringbank 或 crypto。
list[].channel_namestring银行卡为银行名称，加密货币为网络/币种。
list[].account_summarystring收款账户摘要。
list[].amountstring用户提交的充值数量或金额。
list[].amount_unitstring充值数量或金额单位。
list[].arrive_amountstring折算后入账到用户余额的金额。
list[].platform_currencystring平台货币符号。
list[].platform_usd_ratestring平台货币兑 USD 汇率。
list[].status_textstring状态文案。
list[].proof_requiredint是否需要补传转账凭证。
list[].can_cancelint是否允许取消。
list[].created_timestring创建时间文案。
list[].module_textstring仅加密货币返回，代收或手动。
list[].crypto_usd_ratestring仅加密货币返回，加密货币兑 USD 汇率。
list[].crypto_usd_amountstring仅加密货币返回，币种数量折算后的 USD 金额。
list[].rate_textstring仅加密货币返回，加密货币兑 USD 汇率文案。
list[].platform_rate_textstring仅加密货币返回，平台货币兑 USD 汇率文案。
list[].countdown_secondsint仅加密货币待充值订单返回剩余倒计时秒数。

提现

提现接口用于 H5 用户读取提现入口配置、维护收款资料、提交提现申请、查询提现记录和详情。收款资料包含银行卡绑定和加密货币提现钱包绑定，提交成功后会立即扣减用户余额，后台拒绝时自动退回余额并写入账变记录。

演示页面
/frontend/withdrawal-demo 可直接测试银行卡绑定、钱包绑定、提交提现、记录和详情接口。
收款资料
银行卡接口复用 /api/frontend/user/bank-cards，加密钱包接口使用 /api/frontend/withdrawal/crypto/wallets/bind，文档统一放在提现章节。
GET/api/frontend/user/bank-cards需登录

接口名：获取提现银行卡列表

参数必填说明
无请求参数。银行卡提现时使用返回的 list[].id 作为 bank_card_id。

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "can_update_bank_card": 1,
    "can_add_bank_card": 1,
    "bank_card_count": 1,
    "bank_card_max_count": 3,
    "bank_card_duplicate_bind_enabled": 0,
    "list": [
      {
        "id": 12,
        "account_name": "张三",
        "bank_name": "中国银行",
        "branch_name": "东京支行",
        "branch_no": "001",
        "card_no_masked": "6222 **** **** 4218",
        "status": 1
      }
    ]
  }
}
返回字段类型说明
can_update_bank_cardint后台是否允许用户修改已绑定银行卡。
can_add_bank_cardint当前用户是否还能新增银行卡。
bank_card_max_countint每个用户可绑定银行卡数量，0 表示不限制。
list[].idint银行卡 ID，提交银行卡提现时传入。
list[].card_no_maskedstring脱敏银行卡号，前端列表展示优先使用。
POST/api/frontend/user/bank-cards/create / update需登录

接口名：新增或修改提现银行卡

参数必填说明
id修改必填银行卡 ID；新增不传。
account_name是持卡人姓名，必须与当前用户真实姓名一致。
bank_name是银行名称。
branch_name是分行名称。
branch_no是分行编号。
card_no是银行卡号。
payment_password是支付密码。

请求示例

{
  "account_name": "张三",
  "bank_name": "中国银行",
  "branch_name": "东京支行",
  "branch_no": "001",
  "card_no": "6222026006705354218",
  "payment_password": "123456"
}

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "item": {
      "id": 12,
      "account_name": "张三",
      "bank_name": "中国银行",
      "branch_name": "东京支行",
      "branch_no": "001",
      "card_no_masked": "6222 **** **** 4218",
      "status": 1
    },
    "can_update_bank_card": 1,
    "can_add_bank_card": 1,
    "bank_card_count": 1,
    "bank_card_max_count": 3,
    "list": []
  }
}
返回字段类型说明
itemobject新增或修改后的银行卡。
item.idint银行卡 ID。
can_add_bank_cardint保存后是否还能继续添加银行卡。
listarray保存后的当前用户银行卡列表。
GET/api/frontend/withdrawal/methods公开

接口名：获取提现方式

参数必填说明
无。可选携带 Authorization，已登录时返回当前用户提现限额。

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "method": "bank",
        "name": "银行卡",
        "display_status": 1,
        "enable_status": 1,
        "enabled": 1,
        "available_count": 1,
        "status_text": "可用",
        "rule_content": "<p>银行卡提现规则</p>",
        "rule_html": "<p>银行卡提现规则</p>",
        "description": "使用已绑定银行卡提交提现申请"
      }
    ],
    "limits": {
      "min_amount": "10.00",
      "max_amount": "5000.00",
      "daily_limit": 3,
      "balance": "1000.00"
    }
  }
}
返回字段类型说明
list[].methodstringbank 银行卡，crypto 加密货币，offline 线下提现。
list[].enable_statusint当前方式是否可提交。
list[].rule_contentstring后台配置的提现规则富文本，支持多语言。
limitsobject已登录用户提现金额范围、每日次数和余额。
GET/api/frontend/withdrawal/offline/customer-services公开

接口名：获取线下提现客服列表

参数必填说明
无。客服排序由后台线下提现客服类型拖拽顺序决定。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "enabled": 1,
    "customer_service_types": [
      {"type": "withdrawal", "label": "提现客服", "available_count": 1}
    ],
    "list": [
      {"id": 1, "source_type": "withdrawal", "source_text": "提现客服", "name": "提现客服A", "url": "https://example.com/kefu", "status": 1, "sort": 10}
    ],
    "count": 1
  }
}
返回字段类型说明
enabledint线下提现入口是否开启。
list[].source_typestringwithdrawal 提现客服，platform 平台客服，agent 代理客服。
list[].urlstring点击跳转客服地址。
GET/api/frontend/withdrawal/crypto/channels公开

接口名：获取提现加密货币通道

参数必填说明
无。可选携带 Authorization，已登录时会返回当前用户在对应币种网络下绑定的钱包。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {"id": 1, "channel_key": "TRC20-USDT", "chain": "TRC20", "coin": "USDT", "icon": "https://admin.bin9k.top/common/crypto/TRC20-USDT.png", "min_amount": "10", "max_amount": "5000", "exchange_rate": "1", "platform_currency": "JPY", "platform_usd_rate": "0.0067", "crypto_platform_rate": "149.25373134", "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY", "wallet_bound": 1, "wallet": {"id": 8, "address": "Txxxxxxxxxxxxxxxx"}, "buttons": [100, 500]}
    ],
    "coins": [{"coin": "USDT", "name": "USDT", "networks": []}],
    "wallet_config": {"update_enabled": 1, "duplicate_bind_enabled": 0}
  }
}
返回字段类型说明
list[].channel_keystring提交提现时传入的通道标识。
list[].min_amount / max_amountstring当前通道金额范围，0 表示不限制。
list[].crypto_platform_ratestring1 个加密货币可折算的平台币数量。
list[].crypto_platform_rate_textstring1加密货币 = 多少平台币 的展示文案。
list[].walletobject/null已登录用户在该网络币种下绑定的钱包，没有绑定时为 null。
wallet_configobject后台钱包修改和重复绑定策略。
coinsarray按币种聚合的网络列表。
POST/api/frontend/withdrawal/crypto/wallets/bind需登录

接口名：绑定或更新提现钱包

参数必填说明
channel_key推荐提现币种网络标识，例如 TRC20-USDT。
chain / coin二选一未传 channel_key 时可用网络和币种组合。
address是用户收款钱包地址。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "wallet": {"id": 8, "channel_key": "TRC20-USDT", "chain": "TRC20", "coin": "USDT", "address": "Txxxxxxxxxxxxxxxx", "status": 1},
    "channel": {"channel_key": "TRC20-USDT", "chain": "TRC20", "coin": "USDT"},
    "wallet_config": {"update_enabled": 1, "duplicate_bind_enabled": 0}
  }
}
返回字段类型说明
wallet.addressstring当前绑定的钱包地址，用于前端回填。
wallet_config.update_enabledint0 表示已绑定后不能修改，只允许首次绑定。
wallet_config.duplicate_bind_enabledint0 表示同一币种网络下同一钱包不能被其他用户重复绑定。
POST/api/frontend/withdrawal/orders/create需登录

接口名：提交提现申请

参数必填说明
method是bank、crypto、offline。
amount是提现金额。
payment_password是支付密码。
bank_card_id银行卡必填用户已绑定的银行卡 ID。
channel_key加密货币必填提现币种网络标识。
address否加密货币钱包地址；不传时使用该用户已绑定的钱包。
remark否用户备注。

请求示例

{
  "method": "bank",
  "amount": "100.00",
  "bank_card_id": 1,
  "payment_password": "123456",
  "remark": "提现到银行卡"
}

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "order": {
      "id": 10,
      "order_no": "TX202605141650001234",
      "method": "bank",
      "method_text": "银行卡",
      "amount": "10000.00",
      "amount_unit": "JPY",
      "amount_text": "10000.00 JPY",
      "account_text": "中国银行 / 6222 **** **** 4218 / 张三",
      "account": {
        "type": "bank",
        "type_text": "银行卡",
        "summary": "中国银行 / 6222 **** **** 4218 / 张三"
      },
      "status": 0,
      "status_text": "待审核",
      "created_time": "2026-05-14 16:50:00",
      "bank": {"account_name": "张三", "bank_name": "中国银行", "card_no_masked": "6222 **** **** 0000"},
      "crypto": null
    },
    "balance": {"before_balance": "1000.00", "after_balance": "900.00"}
  }
}
返回字段类型说明
order.order_nostring提现订单号，账变备注会记录。
order.amount_unitstring提现金额单位，例如 $。
order.amount_textstring带单位的提现金额展示文案。
order.accountobject本次提现收款账户快照，银行卡、加密货币和线下提现结构会按类型返回。
order.account_textstring收款账户摘要，列表可直接展示。
order.statusint0 待审核，1 已通过，2 已拒绝。
balance.after_balancestring提交后余额；拒绝提现时会自动退回。
GET/api/frontend/withdrawal/orders需登录

接口名：获取提现记录

参数必填说明
page / page_size否分页参数，默认 1 / 20。
method否bank、crypto、offline，不传返回全部。
status否0 待审核，1 已出款，2 已拒绝，3 待出款。

请求示例

GET https://admin.bin9k.top/api/frontend/withdrawal/orders?page=1&page_size=20&method=crypto
Authorization: Bearer <access_token>
lang: zh-CN

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 10,
        "order_no": "TX202605141650001234",
        "method": "crypto",
        "method_text": "加密货币",
        "amount": "10000.00",
        "amount_unit": "JPY",
        "amount_text": "10000.00 JPY",
        "platform_currency": "JPY",
        "platform_currency_symbol": "JPY",
        "account_text": "TRC20 / USDT / Txxxxx...xxxxxx",
        "exchange_rate": "1",
        "crypto_usd_rate": "1",
        "platform_usd_rate": "0.0067",
        "crypto_usd_amount": "67",
        "rate_text": "1 USDT = 1 USD",
        "crypto_platform_rate": "149.25373134",
        "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY",
        "platform_rate_text": "1 JPY = 0.0067 USD",
        "expected_arrival_amount": "67",
        "expected_arrival_currency": "USDT",
        "expected_arrival_text": "67 USDT",
        "status": 0,
        "status_text": "待审核",
        "status_type": "warning",
        "created_time": "2026-05-14 16:50:00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "method": "crypto",
    "status": ""
  }
}
返回字段类型说明
listarray当前用户自己的提现记录。
list[].method_textstring提现方式文案，会根据请求头 lang 返回对应语言。
list[].amount_textstring带货币单位的提现金额。
list[].account_textstring收款账户摘要，银行卡展示银行/卡号/姓名，加密货币展示网络/币种/钱包。
list[].exchange_ratestring加密货币兑 USD 汇率，非加密货币为空。
list[].platform_usd_ratestring平台货币兑 USD 汇率。
list[].crypto_usd_amountstring提现金额折算的 USD 金额。
list[].crypto_platform_ratestring1 个加密货币可折算的平台币数量。
list[].crypto_platform_rate_textstring1加密货币 = 多少平台币 的展示文案。
list[].expected_arrival_textstring加密货币预计到账数量和币种，非加密货币为空。
list[].status_textstring提现状态文案。
list[].status_typestring状态标签类型，前端可映射颜色。
list[].created_timestring创建时间文案。
totalint总条数。
methodstring实际使用的提现方式筛选值。
statusstring实际使用的状态筛选值。
GET/api/frontend/withdrawal/orders/detail需登录

接口名：获取提现详情

参数必填说明
id二选一提现订单 ID。
order_no二选一提现订单号。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "order": {
      "id": 10,
      "order_no": "TX202605141650001234",
      "method_text": "加密货币",
      "amount": "100.00",
      "amount_unit": "$",
      "amount_text": "100.00 $",
      "account_text": "TRC20 / USDT / Txxxxx...xxxxxx",
      "account": {
        "type": "crypto",
        "type_text": "加密货币",
        "summary": "TRC20 / USDT / Txxxxx...xxxxxx"
      },
      "status_text": "已拒绝",
      "remark": "资料不完整",
      "audit_username": "admin",
      "bank": null,
      "crypto": {
        "channel_key": "TRC20-USDT",
        "chain": "TRC20",
        "coin": "USDT",
        "address": "Txxxxxxxxxxxxxxxx",
        "address_masked": "Txxxxx...xxxxxx",
        "exchange_rate": "1",
        "crypto_usd_rate": "1",
        "platform_usd_rate": "0.0067",
        "crypto_usd_amount": "67",
        "rate_text": "1 USDT = 1 USD",
        "crypto_platform_rate": "149.25373134",
        "crypto_platform_rate_text": "1 USDT = 149.25373134 JPY",
        "platform_rate_text": "1 JPY = 0.0067 USD",
        "expected_arrival_amount": "67",
        "expected_arrival_currency": "USDT",
        "expected_arrival_text": "67 USDT"
      }
    }
  }
}
返回字段类型说明
order.accountobject通用收款账户快照。
order.bankobject/null银行卡提现资料。
order.cryptoobject/null加密货币提现资料，包含钱包地址、汇率和预计到账。
order.crypto.rate_textstring加密货币兑 USD 汇率展示文案。
order.crypto.crypto_platform_ratestring1 个加密货币可折算的平台币数量。
order.crypto.crypto_platform_rate_textstring1加密货币 = 多少平台币 的展示文案。
order.crypto.platform_rate_textstring平台货币兑 USD 汇率展示文案。
order.crypto.crypto_usd_amountstring提现金额折算的 USD 金额。
order.crypto.expected_arrival_textstring预计到账展示文案。

影院

影院接口按重构后的前端标准返回 {code,msg,data}，包含影院分类、影院列表、影院详情和热门推荐。热门推荐只返回后台标记为热门的视频，并随机排序。

演示页面
/frontend/cinema-demo 可直接测试影院分类、列表、详情和热门推荐接口。
排序
latest 最新，hot 热门，play_count_desc 播放次数从高到低，play_count_asc 播放次数从低到高。
GET/api/frontend/cinema/categories公开

接口名：获取影院分类

作用：返回启用状态的影院分类。

参数必填说明
无请求参数。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "默认分类",
        "sort": 10,
        "video_count": 0,
        "status": 1,
        "created_at": 1710000000,
        "updated_at": 1710000000
      }
    ]
  }
}
返回字段类型说明
listarray影院分类列表。
list[].idint分类 ID。
list[].namestring分类名称。
list[].sortint排序值。
list[].video_countint分类下视频数量。
list[].statusint状态，1 启用。
list[].created_atint/string创建时间。
list[].updated_atint/string更新时间。
GET/api/frontend/cinema/list公开

接口名：获取影院列表

作用：分页返回启用状态的影院视频，可按分类和排序筛选。

参数必填说明
category_id否分类 ID，不传返回全部分类。
page否页码，从 1 开始。
page_size否每页数量，默认 8，最大 50。
sort否latest、hot、play_count_desc、play_count_asc。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "示例视频",
        "cover_url": "/storage/video/demo.png",
        "cover_full_url": "http://127.0.0.1:8841/storage/video/demo.png",
        "play_url": "https://example.com/demo.m3u8",
        "duration": "",
        "play_count": 100,
        "category_id": 1,
        "category_name": "默认分类",
        "is_hot": 0,
        "status": 1,
        "created_at": 1710000000,
        "updated_at": 1710000000
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 8,
    "sort": "latest"
  }
}
返回字段类型说明
listarray影院视频列表。
totalint符合条件的总数量。
pageint当前页码。
page_sizeint每页数量。
sortstring实际使用的排序值。
list[].idint视频 ID。
list[].titlestring视频标题。
list[].cover_urlstring后台保存的封面地址。
list[].cover_full_urlstring可直接访问的完整封面地址。
list[].play_urlstring视频播放地址。
list[].durationstring视频时长。
list[].play_countint播放次数。
list[].category_idint分类 ID。
list[].category_namestring分类名称。
list[].is_hotint是否热门，1 是，0 否。
list[].statusint状态，1 启用。
list[].created_atint/string创建时间。
list[].updated_atint/string更新时间。
GET/api/frontend/cinema/detail公开

接口名：获取影院详情

作用：按视频 ID 返回影院视频详情。

参数必填说明
id是视频 ID。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "item": {
      "id": 1,
      "title": "示例视频",
      "cover_url": "/storage/video/demo.png",
      "cover_full_url": "http://127.0.0.1:8841/storage/video/demo.png",
      "play_url": "https://example.com/demo.m3u8",
      "duration": "",
      "play_count": 100,
      "category_id": 1,
      "category_name": "默认分类",
      "is_hot": 1,
      "status": 1,
      "created_at": 1710000000,
      "updated_at": 1710000000
    }
  }
}
返回字段类型说明
itemobject视频详情，字段与影院列表项一致。
item.idint视频 ID。
item.titlestring视频标题。
item.cover_urlstring后台保存的封面地址。
item.cover_full_urlstring可直接访问的完整封面地址。
item.play_urlstring视频播放地址。
item.durationstring视频时长。
item.play_countint播放次数。
item.category_idint分类 ID。
item.category_namestring分类名称。
item.is_hotint是否热门，1 是，0 否。
item.statusint状态，1 启用。
item.created_atint/string创建时间。
item.updated_atint/string更新时间。
GET/api/frontend/cinema/hot公开

接口名：获取热门推荐影院

作用：从热门视频中随机返回推荐列表，可按分类过滤。

参数必填说明
category_id否分类 ID，不传则从全部热门视频中随机返回。
limit否返回数量，默认 8，最大 20。
{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "示例视频",
        "cover_url": "/storage/video/demo.png",
        "cover_full_url": "http://127.0.0.1:8841/storage/video/demo.png",
        "play_url": "https://example.com/demo.m3u8",
        "duration": "",
        "play_count": 100,
        "category_id": 1,
        "category_name": "默认分类",
        "is_hot": 1,
        "status": 1,
        "created_at": 1710000000,
        "updated_at": 1710000000
      }
    ],
    "limit": 8,
    "category_id": 1,
    "is_random": 1
  }
}
返回字段类型说明
listarray热门推荐视频列表，只返回 is_hot=1 的视频。
limitint本次请求使用的返回数量。
category_idint本次请求使用的分类 ID，未传时为 0。
is_randomint是否随机排序，1 表示每次请求随机返回。
list[]object视频项，字段与影院列表项一致。
list[].idint视频 ID。
list[].titlestring视频标题。
list[].cover_urlstring后台保存的封面地址。
list[].cover_full_urlstring可直接访问的完整封面地址。
list[].play_urlstring视频播放地址。
list[].durationstring视频时长。
list[].play_countint播放次数。
list[].category_idint分类 ID。
list[].category_namestring分类名称。
list[].is_hotint热门推荐接口固定返回 1。
list[].statusint状态，1 启用。
list[].created_atint/string创建时间。
list[].updated_atint/string更新时间。

资源

资源接口按地区组织资源列表，传 recommend=1 时返回首页推荐资源；详情接口额外返回图集字段 gallery_urls 和 gallery_full_urls。

演示页面
/frontend/resources-demo 可直接测试资源地区、列表和详情接口。
图片地址
列表返回 cover_full_url，详情返回完整图集地址，前端可直接展示。
GET/api/frontend/resources/regions公开

接口名：获取资源地区

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {"id": 1, "name": "默认地区", "sort": 10, "item_count": 0, "status": 1}
    ]
  }
}
GET/api/frontend/resources/items公开

接口名：获取资源列表 / 首页推荐资源

作用：分页获取选妃资源列表。普通资源列表和首页推荐资源共用该接口，传 recommend=1 时只返回后台标记为“首页推荐”的资源。

参数必填说明
region_id否地区 ID，不传返回全部地区。
recommend否传 1 时只返回后台标记为首页推荐的资源。
page否页码，从 1 开始。
page_size否每页数量，默认 8，最大 50。

请求示例

https://admin.bin9k.top/api/frontend/resources/items?recommend=1&page=1&page_size=8

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "23",
        "age": "23",
        "cover_url": "/api/materials/preview?id=6",
        "cover_full_url": "https://admin.bin9k.top/api/materials/preview?id=6",
        "region_id": 1,
        "region_name": "默认地区",
        "height_cm": "168",
        "bust": "C",
        "tags_text": "温柔，认证",
        "tags": ["温柔", "认证"],
        "rating": 5,
        "address": "台北",
        "like_count": 100,
        "description": "简介",
        "weight_kg": "48",
        "video_url": "",
        "status": 1,
        "is_home_recommend": 1,
        "created_at": 1710000000
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 8,
    "recommend": 1
  }
}
返回字段说明
list资源列表，按添加时间倒序返回。
total符合当前筛选条件的总数量。
page当前页码。
page_size当前每页数量。
recommend本次是否启用首页推荐过滤，1 是，0 否。
list[].id资源 ID，详情接口使用。
list[].title / age资源主标题和年龄展示值，当前都来自后台“年龄/名称”字段。
list[].cover_url站内封面地址，后台素材地址会转为前端公开预览地址。
list[].cover_full_url带当前域名的完整封面地址，H5 可直接用于图片展示。
list[].region_id / region_name所属地区 ID 和地区名称。
list[].height_cm / bust / weight_kg身高、胸围、体重展示值。
list[].tags_text / tags标签原始文本和拆分后的标签数组。
list[].rating评分展示值。
list[].address资源地址文案。
list[].like_count点赞数。
list[].description资源简介。
list[].video_url视频地址，没有配置时为空字符串。
list[].status资源状态，前端接口只返回启用状态资源。
list[].is_home_recommend是否首页推荐，1 是，0 否。
list[].created_at创建或添加时间戳。
GET/api/frontend/resources/items/detail公开

接口名：获取资源详情

作用：按资源 ID 获取单条资源详情。详情包含列表中的全部基础字段，并额外返回图集地址数组。

参数必填说明
id是资源 ID。

请求示例

https://admin.bin9k.top/api/frontend/resources/items/detail?id=1

返回示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "item": {
      "id": 1,
      "title": "23",
      "age": "23",
      "cover_url": "/api/materials/preview?id=6",
      "cover_full_url": "https://admin.bin9k.top/api/materials/preview?id=6",
      "region_id": 1,
      "region_name": "默认地区",
      "height_cm": "168",
      "bust": "C",
      "tags_text": "温柔，认证",
      "tags": ["温柔", "认证"],
      "rating": 5,
      "address": "台北",
      "like_count": 100,
      "description": "简介",
      "weight_kg": "48",
      "video_url": "",
      "status": 1,
      "is_home_recommend": 1,
      "created_at": 1710000000,
      "gallery_urls": ["/api/materials/preview?id=6"],
      "gallery_full_urls": ["https://admin.bin9k.top/api/materials/preview?id=6"]
    }
  }
}
返回字段说明
item资源详情对象。
item.id资源 ID。
item.title / age资源主标题和年龄展示值。
item.cover_url / cover_full_url封面站内地址和完整访问地址。
item.region_id / region_name所属地区 ID 和地区名称。
item.height_cm / bust / weight_kg身高、胸围、体重展示值。
item.tags_text / tags标签原始文本和拆分后的标签数组。
item.rating评分展示值。
item.address资源地址文案。
item.like_count点赞数。
item.description详情简介文案。
item.video_url视频地址，没有配置时为空字符串。
item.status资源状态，前端接口只返回启用状态资源。
item.is_home_recommend是否首页推荐。
item.created_at创建或添加时间戳。
item.gallery_urls图集站内地址数组。
item.gallery_full_urls图集完整访问地址数组，H5 可直接用于大图预览。

彩票

彩票接口按当前项目统一结构返回，公开接口用于展示分类、彩票、当前期号、开奖历史和赔率；下注与投注记录需要登录 token。

演示页面
/frontend/lottery-demo 可直接测试彩票全套前端接口。
玩法约定
big 大、small 小、odd 单、even 双，和值玩法为 sum_3 到 sum_18。
GET/api/frontend/lottery/categories公开

接口名：获取彩票分类

作用：返回启用状态的彩票分类。

参数必填说明
无-本接口无请求参数。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "默认分类",
        "sort": 10,
        "lottery_count": 3,
        "status": 1
      }
    ]
  }
}
返回字段说明
list分类列表。
list[].id / name分类 ID 和分类名称。
list[].sort排序值，值越小越靠前。
list[].lottery_count分类下彩票数量。
list[].status状态，1 启用。
GET/api/frontend/lottery/items公开

接口名：获取彩票列表

参数必填说明
category_id / class_id否分类 ID，不传返回全部。
keyword / q否按彩票名称、标识或分类名称搜索。
hot否1 只返回热门。
page否页码，默认 1。
page_size否每页数量，默认 20，最大 50。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "五分快三",
        "lottery_key": "jsk3",
        "category_id": 1,
        "icon_full_url": "https://admin.bin9k.top/storage/lottery/demo.png",
        "interval_seconds": 300,
        "is_hot": 1
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
返回字段说明
list彩票列表。
list[].id / name / lottery_key彩票 ID、名称和标识。
list[].category_id / category_name所属分类。
list[].icon_url / icon_full_url图标站内地址和完整地址。
list[].condition_amount做单要求金额。
list[].interval_seconds开奖间隔秒数。
total / page / page_size分页总数、当前页和每页数量。
GET/api/frontend/lottery/hot公开

接口名：获取热门彩票

作用：返回后台标记为热门的彩票。

参数必填说明
limit否返回数量，默认 8，最大 30。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "五分快三",
        "lottery_key": "jsk3",
        "is_hot": 1
      }
    ],
    "limit": 8
  }
}
返回字段说明
list热门彩票列表，字段同彩票列表。
limit本次请求限制返回数量。
GET/api/frontend/lottery/detail公开

接口名：获取彩票详情

参数必填说明
lottery_id / lottery_key二选一彩票 ID 或彩票标识。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "五分快三",
      "lottery_key": "jsk3",
      "play_count": 4
    },
    "current_issue": {
      "expect": "202605120001",
      "status": 0,
      "remaining_seconds": 180
    },
    "last_issue": {
      "expect": "202605120000",
      "opencode": "1,2,3",
      "sum": 6
    },
    "play_options": [
      {
        "play_key": "big",
        "name": "大",
        "odds": "1.98"
      }
    ]
  }
}
返回字段说明
item彩票基础信息。
current_issue当前最近一条待开奖期号。
last_issue最近一条已开奖期号。
play_options启用玩法列表。
GET/api/frontend/lottery/play-page公开

接口名：获取认证页彩票聚合

作用：认证页首屏一次返回彩票基础信息、页面配置、当前期、上期开奖结果、买入选项和往期结果。

参数必填说明
lottery_id / lottery_key否彩票 ID 或彩票标识；不传时使用默认启用彩票。
page否往期结果页码，默认 1。
page_size / history_limit否往期结果每页数量，默认 20，最大 50。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "赞助轮调",
      "lottery_key": "sponsor",
      "play_count": 4
    },
    "config": {
      "default_amount": "1.00",
      "allow_multi_select": 1,
      "result_refresh_seconds": 5
    },
    "current_issue": {
      "expect": "202605133363",
      "remaining_seconds": 82
    },
    "last_issue": {
      "expect": "202605133362",
      "numbers": [
        6,
        1,
        2
      ],
      "sum": 9
    },
    "buy_options": [
      {
        "play_key": "plane",
        "name": "飞机",
        "odds": "1.98"
      }
    ],
    "history": {
      "list": [],
      "total": 0,
      "page": 1,
      "page_size": 20
    },
    "server_time": 1778666918
  }
}
返回字段说明
item彩票基础信息。
config认证页配置，包含金额、刷新、倒计时和展示文案。
current_issue当前可买入期号。
last_issue最近已开奖期号。
buy_options买入选项数组。
history往期结果分页数据。
server_time服务端时间戳，用于校准倒计时。
GET/api/frontend/lottery/config公开

接口名：获取认证页彩票配置

参数必填说明
lottery_id / lottery_key否彩票 ID 或彩票标识；不传时使用默认启用彩票。
page_size / history_limit否往期结果默认分页数量。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "赞助轮调",
      "lottery_key": "sponsor"
    },
    "config": {
      "default_amount": "1.00",
      "min_amount": "1.00",
      "allow_multi_select": 1,
      "history_page_size": 20
    },
    "server_time": 1778666918
  }
}
返回字段说明
item彩票基础信息。
config.default_amount / min_amount / amount_step每单积分默认值、最小值和步进值。
config.allow_multi_select / max_selected_options是否允许多选以及最大可选数量。
server_time服务端当前时间戳。
GET/api/frontend/lottery/buy-options公开

接口名：获取买入选项

参数必填说明
lottery_id / lottery_key否彩票 ID 或彩票标识；不传时使用默认启用彩票。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "赞助轮调",
      "lottery_key": "sponsor"
    },
    "list": [
      {
        "id": 1,
        "play_key": "rocket",
        "type": "rocket",
        "name": "火箭",
        "odds": "1.98",
        "status": 1,
        "icon_key": "rocket",
        "style_key": "purple",
        "sort": 1
      }
    ]
  }
}
返回字段说明
item彩票基础信息。
list[].play_key前端下单使用的玩法标识。
list[].name / odds展示名称和当前赔率。
list[].icon_key / style_key图标和卡片样式建议值。
list[].sort排序值。
GET/api/frontend/lottery/current公开

接口名：获取当前期号

参数必填说明
lottery_id / lottery_key否彩票 ID 或彩票标识；不传时使用默认启用彩票。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "赞助轮调"
    },
    "current_issue": {
      "expect": "202605133363",
      "open_time": "2026-05-13 13:30:00",
      "remaining_seconds": 82
    },
    "last_issue": {
      "expect": "202605133362",
      "opencode": "6,1,2",
      "numbers": [
        6,
        1,
        2
      ],
      "sum": 9,
      "actual_open_time": "2026-05-13 13:28:03"
    }
  }
}
返回字段说明
current_issue.expect当前期号。
current_issue.open_time预计开奖时间。
current_issue.remaining_seconds距离开奖剩余秒数。
last_issue.numbers / sum上期开奖数字和和值。
last_issue.result_badges和值、大小、单双标签。
GET/api/frontend/lottery/results公开

接口名：获取往期结果

参数必填说明
lottery_id / lottery_key否彩票 ID 或彩票标识；不传时使用默认启用彩票。
page否页码，默认 1。
page_size否每页数量，默认 20，最大 50。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "id": 1,
      "name": "赞助轮调"
    },
    "list": [
      {
        "expect": "202605133363",
        "opencode": "6,1,2",
        "numbers": [
          6,
          1,
          2
        ],
        "sum": 9,
        "actual_open_time": "2026-05-13 13:30:03"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
返回字段说明
list往期已开奖列表。
list[].expect期号。
list[].opencode / numbers开奖号码文本和数组。
list[].sum开奖数字和值。
list[].actual_open_time实际开奖时间。
total / page / page_size分页信息。
GET/api/frontend/lottery/issues公开

接口名：获取开奖历史

参数必填说明
lottery_id / lottery_key二选一彩票 ID 或彩票标识。
status否drawn 已开奖，pending 待开奖，all 全部。
page / page_size否页码和每页数量。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "expect": "202605133363",
        "status": 1,
        "opencode": "6,1,2",
        "sum": 9
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 10,
    "status": "drawn"
  }
}
返回字段说明
list开奖期号列表，字段同往期结果。
status本次查询使用的状态参数。
total / page / page_size分页信息。
GET/api/frontend/lottery/odds公开

接口名：获取玩法赔率

参数必填说明
lottery_id / lottery_key二选一彩票 ID 或彩票标识。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "lottery_id": 1,
    "lottery_key": "jsk3",
    "list": [
      {
        "play_key": "big",
        "type": "big",
        "name": "大",
        "odds": "1.98",
        "status": 1
      }
    ]
  }
}
返回字段说明
lottery_id / lottery_key彩票 ID 和标识。
list玩法赔率列表，字段同买入选项。
POST/api/frontend/lottery/orders需登录

接口名：提交彩票投注

参数必填说明
lottery_id / lottery_key二选一彩票 ID 或彩票标识。
plays是玩法数组，例如 [{"type":"big","amount":"10"}]。
amount否统一每注金额；当 plays[].amount 为空时使用。
expect是当前期号；必须传 current_issue.expect，期号过期、已开奖或不是当前最近一期时会拒绝下注。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "order_ids": [
      101
    ],
    "orders": [
      {
        "id": 101,
        "lottery_id": 1,
        "expect": "202605120001",
        "play_key": "big",
        "amount": "10.00",
        "status_text": "待开奖"
      }
    ],
    "count": 1,
    "total_amount": "10.00",
    "balance_before": "100.00",
    "balance_after": "90.00"
  }
}
返回字段说明
order_ids本次创建的投注订单 ID。
orders本次创建的订单列表。
orders[].expect本次投注期号。
orders[].play_key / play_name玩法标识和名称。
total_amount本次投注总金额。
balance_before / balance_after扣款前后余额。
GET/api/frontend/lottery/orders需登录

接口名：我的投注记录

参数必填说明
lottery_id否按彩票筛选。
status否pending 待开奖，won 已中奖，lost 未中奖，all 全部。
page / page_size否页码和每页数量。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [
      {
        "id": 101,
        "lottery_id": 1,
        "expect": "202605120001",
        "play_key": "big",
        "amount": "10.00",
        "profit": "9.80",
        "status_text": "已中奖",
        "issue": {
          "expect": "202605120001",
          "sum": 18
        }
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
返回字段说明
list投注记录列表。
list[].amount / odds / profit投注金额、赔率和结算盈亏。
list[].status / status_text状态和状态文案。
list[].issue对应期号和开奖结果。
total / page / page_size分页信息。
GET/api/frontend/lottery/orders/detail需登录

接口名：彩票投注记录详情

返回当前登录用户某一条投注记录的详情，并把同彩票、同期号、同下单时间的多玩法订单聚合成一组，适合 H5 任务结果页。

参数必填说明
id / order_id二选一投注订单 ID。
{
  "code": 0,
  "msg": "ok",
  "data": {
    "item": {
      "order_id": 101,
      "title": "活动三",
      "expect": "202605135179",
      "expect_text": "202605135179期",
      "total_amount": "40.00",
      "total_amount_text": "40积分",
      "amount_label": "任务积分",
      "settlement_status": 1,
      "settlement_status_text": "礼品已完成",
      "status": 1,
      "status_text": "已中奖",
      "order_content": "单,小,大,双",
      "order_time": "2026-05-13 14:50:58"
    },
    "details": [
      {
        "content": "单",
        "amount": "10.00",
        "result_status": 2,
        "result_text": "任务失败",
        "time": "2026-05-13 14:55:01"
      }
    ]
  }
}
返回字段说明
item详情页顶部和订单信息卡片。
item.total_amount_text积分展示文案，会根据请求头 lang 返回对应语言。
item.settlement_status_text结算状态文案，会根据请求头 lang 返回对应语言。
item.order_content本组投注内容，多个玩法用逗号分隔，会根据请求头 lang 返回对应语言。
details投注明细列表。
details[].content / amount玩法内容和投注金额，玩法内容会根据请求头 lang 返回对应语言。
details[].result_status / result_text结果状态和展示文案，展示文案会根据请求头 lang 返回对应语言。
details[].time结果时间；待开奖时返回下单时间。

错误码和状态

0请求成功。
400参数错误、验证码错误、注册/登录失败、业务规则不满足。
401未登录、token 无效、token 已过期。
404资源不存在。
500服务端异常或配置未完成。
lang接口提示优先使用请求头语言，未启用则回退默认语言。
最近更新：2026-08-19 16:29:10