用户体系接入

第三方平台可以使用自身用户标识在 HoldFi 登记用户、查询用户 USD，并为已登录用户创建 HoldFi 门户会话。启用 OAuth2 授权登录后，用户也可以通过第三方身份注册或登录 HoldFi。

1. 用户标识

HoldFi 使用外层报文中的 platform 与业务字段 open_id 共同识别第三方用户。

open_id 须满足以下要求：

1. 由第三方生成，是用户在该平台内长期稳定的不透明标识。
2. 长度为 1～128 个 Unicode 字符。
3. 不得包含控制字符或首尾空白。
4. 区分大小写，并在同一 platform 内保持唯一。
5. 不得转让、回收或分配给其他用户。
6. 不应使用短期 token、会话 ID、手机号或邮箱等可能变化的字段。

HoldFi 不会对 open_id 进行 trim 或大小写转换。不同 platform 下相同的 open_id 表示不同用户。

2. 登记第三方用户

类型：HoldFi 实现。
调用方向：第三方调用 HoldFi。
API path：/openapi/v1/users/register。

第三方可主动将用户登记至 HoldFi。该接口不要求提供手机号、邮箱、用户名或密码。

2.1 业务请求

{
  "open_id": "u_123456789"
}

字段	必填	类型	说明
open_id	是	String	第三方用户标识，须符合第 1 节要求

请求只允许 open_id 字段。

2.2 业务响应

{
  "open_id": "u_123456789",
  "registered": true
}

字段	类型	说明
open_id	String	原样返回请求中的第三方用户标识
registered	Boolean	true 表示用户已在 HoldFi 登记

2.3 业务说明

1. HoldFi 按 platform + open_id 登记用户。
2. 接口支持重复调用。同一用户首次登记和重复登记均返回 registered=true，不会重复创建账户。
3. 主动登记、OAuth2 首次登录和门户首次访问会复用同一用户身份。
4. 缺少 open_id 返回 400002；字段格式错误或包含其他字段返回 400001。

3. 批量查询用户 USD

类型：HoldFi 实现。
调用方向：第三方调用 HoldFi。
API path：/openapi/v1/users/accounts/query。

第三方可以批量查询用户在 HoldFi 的登记状态、可用 USD 和冻结 USD。

3.1 业务请求

{
  "open_ids": [
    "u_123456789",
    "u_987654321"
  ]
}

字段	必填	类型	说明
open_ids	是	Array	1～500 个第三方用户标识，每项均为 String，且须符合第 1 节要求

请求只允许 open_ids 字段。数组中的重复标识不会被去重。

3.2 业务响应

{
  "accounts": [
    {
      "open_id": "u_123456789",
      "registered": true,
      "available_usd": "120.5",
      "frozen_usd": "10"
    },
    {
      "open_id": "u_987654321",
      "registered": false,
      "available_usd": null,
      "frozen_usd": null
    }
  ]
}

字段	类型	说明
accounts	Array	用户查询结果
accounts[].open_id	String	第三方用户标识
accounts[].registered	Boolean	是否已在 HoldFi 登记
accounts[].available_usd	String/null	可用 USD；未登记时为 null
accounts[].frozen_usd	String/null	冻结 USD；未登记时为 null

3.3 业务说明

1. 响应顺序与请求 open_ids 完全一致，重复项也按原位置返回。
2. 已登记用户暂无 USD 记录时，available_usd 和 frozen_usd 均返回 "0"。
3. 未登记用户的两个金额字段均返回 null。
4. 查询不会自动登记用户，也不会改变用户 USD。
5. 金额使用普通十进制字符串，请使用 Decimal 或 BigNumber 类型处理。

4. 创建 HoldFi 门户会话

类型：HoldFi 实现。
调用方向：第三方调用 HoldFi。
API path：/openapi/v1/users/portal-sessions/create。

第三方已完成用户登录后，可以为指定 open_id 创建短期门户会话，并将用户浏览器跳转至 HoldFi。

创建会话前无需预先调用用户登记接口。用户成功进入门户时，HoldFi 会登记或复用对应用户。

4.1 业务请求

{
  "open_id": "u_123456789",
  "return_url": "https://partner.example.com/holdfi/return",
  "scene": "account",
  "state": "ORDER_202608270001",
  "landing_page": "equity",
  "expires_in": 300
}

字段	必填	类型	说明
open_id	是	String	第三方用户标识
return_url	是	String	用户完成门户访问后返回第三方的地址，最长 1000 个字符
scene	否	String/null	第三方业务场景，最长 64 个字符
state	否	String/null	第三方状态值，回跳时原样返回，最长 512 个字符
landing_page	否	String/null	门户落地页，当前仅支持 equity；默认值为 equity
expires_in	否	Integer/null	会话有效期，单位秒，范围 60～900，默认 300

return_url 须满足：

1. 使用绝对 HTTP(S) 地址，不包含用户名、密码信息或 fragment。
2. 与接入时登记的返回地址保持同源，即协议、域名和端口一致；path 和 query 可以不同。
3. 不使用 localhost、内网 IP、回环地址或保留地址。

4.2 业务响应

{
  "portal_session_id": "ps_nGnbdN2H8Y2Qq4jQ2dJ1wYtP",
  "portal_url": "https://www.holdfi.org/portal?directToken=OPAQUE_ONE_TIME_TOKEN",
  "expires_at": 1787803500000
}

字段	类型	说明
portal_session_id	String	门户会话标识，可用于双方排查和记录本次跳转
portal_url	String	HoldFi 门户完整访问地址
expires_at	Integer	会话过期时间，Unix 毫秒时间戳

4.3 浏览器跳转与返回

第三方收到响应后，应将用户浏览器直接跳转至完整的 portal_url。请勿修改地址或重复使用其中的一次性访问凭证。

用户完成门户访问后，HoldFi 将浏览器跳转至本次请求的 return_url：

https://partner.example.com/holdfi/return?result=COMPLETED&state=ORDER_202608270001&portal_session_id=ps_nGnbdN2H8Y2Qq4jQ2dJ1wYtP

参数	说明
result	当前返回 COMPLETED
state	请求中提供时原样返回
portal_session_id	本次门户会话标识

COMPLETED 表示用户完成本次门户访问流程，不表示发生了充值或其他资产操作。

4.4 会话说明

1. 门户访问凭证短期有效且只能使用一次。
2. 完全相同的 OpenAPI 请求重复提交会返回 409002。
3. 如需创建新的门户会话，请重新生成 timestamp、加密数据和签名后发起请求。