ChainUp 开放平台 TypeScript SDK

本 SDK 基于官方文档端点实现，已对齐以下板块：OAuth、支付、赠金（赠币接口）、用户、交易（含现货与场外）、出入金、增值服务、第三方免登录、Fireblocks 钱包。端点定义见 src/constants/endpoints.ts。

安装

npm i chainup-open-platform-sdk

快速开始

import { ChainUpSDK } from 'chainup-open-platform-sdk';

const sdk = new ChainUpSDK({
  baseURL: 'https://service.xxx.com/platformapi/chainup/open',
  appKey: process.env.CHAINUP_APP_KEY!,
  appSecret: process.env.CHAINUP_APP_SECRET!,
  version: 'v1',
});

OAuth 授权

• 生成登录页（浏览器访问）：sdk.oauth.getLoginPageUrl({ appKey, redirectUrl })（/platform/login.html）
• 使用 code 换 token：POST /auth/token
• 刷新 token：POST /auth/refreshToken

// 登录页 URL
const loginUrl = sdk.oauth.getLoginPageUrl({ appKey: process.env.CHAINUP_APP_KEY!, redirectUrl: 'https://your.site/callback' });

// code 换 token
const tokenRes = await sdk.oauth.getAuthToken({ code: 'code-from-callback' });
if (tokenRes.code === 0) sdk.setAccessToken(tokenRes.data.token);

// 刷新 token
await sdk.oauth.refreshAccessToken(tokenRes.data.refreshToken);

支付

• 创建订单：POST /opay/createThirdOrder
• 查询订单：GET /opay/orderDetail
• 取消订单：POST /opay/cancelOrder
• 商家日贴对账单：POST /opay/merchantBillingDay
• 支付页（浏览器访问）：/platform/pay.html

const order = await sdk.payment.createThirdOrder({
  merchant_order_no: 'ORDER_' + Date.now(),
  amount: '10',
  currency: 'USDT',
  subject: '测试',
  pay_user_id: 'uid',
  notify_url: 'https://your.site/notify',
  return_url: 'https://your.site/return',
  order_scene_type: 1001,
});

const detail = await sdk.payment.getOrderDetail({ order_no: order.data.orderNum });
const payUrl = sdk.payment.getPayPageUrl({ order_no: order.data.orderNum, appKey: process.env.CHAINUP_APP_KEY! });

用户

• 已封装：邀请上下级、登录历史、注册信息、实名认证、充值地址、账户余额、用户资产查询（含 V2）、按起始ID/更新时间批量资产查询等。

示例：

// 注册信息列表（regStartTime 为 13 位毫秒；兼容 startTime 秒会自动×1000）
await sdk.user.getRegInfoListOfficial({
  page: 1,
  pageSize: 100,
  regStartTime: Date.now() - 7 * 24 * 3600 * 1000,
});

// 用户注册（mobile/email 二选一；countryCode 仅数字，不带+）
await sdk.user.postRegistration({
  password: '******',
  mobileNumber: '13800138000',
  countryCode: '86',
  invitedCode: 'INV123',
});

// 用户资产查询（多币种）与 V2（coinSymbols 必填，多个用逗号）
await sdk.user.getUserAccounts({ openId: 'xxx', coinSymbols: 'USDT,BTC', assetType: '201' });
await sdk.user.getUserAccountsV2({ userId: '10001', coinSymbols: 'USDT' });

// 账户余额、充值地址（优先传 openId，其次 userId；uid 会被兼容映射）
await sdk.user.getAccountBalance({ userId: '10001' });
await sdk.user.getDepositAddress({ userId: '10001', coin: 'USDT', chain: 'TRX' });

// 邀请上下级 & 登录历史
await sdk.user.getUserInvite({ uid: '10001', page: 1, pageSize: 20 });
await sdk.user.getUserSuperior({ uid: '10001' });
await sdk.user.getUserHistoryLogin({ uid: '10001', page: 1, pageSize: 20 });

// 批量资产（按起始ID / 按更新时间；batchSize 或兼容 pageSize）
await sdk.user.getBatchUserAccountsByStartId({ startId: 0, batchSize: 100 });
await sdk.user.getBatchUserAccountsByUpdateTime({ startTime: Date.now() - 3600_000, batchSize: 100 });

交易

• 现货：成交记录、订单记录、订单详情、手续费分成 → sdk.trading.spot*
• 场外：OTC 记录（V1/V2）、OTC 手续费分成 → sdk.trading.otc*

出入金

• 充值/提现列表、商户赠币、其他划转 → sdk.fund.*

增值服务

• 经纪人分成、合约手续费/角色/体验金、理财矿池记录 → sdk.valueAdded.*

第三方免登录

• openApiKey/secret、交易所登录 Token、退出登录 → sdk.thirdLogin.*

Fireblocks 钱包

• 地址映射、币种映射、公司资产（含 V2）、划转记录 → sdk.wallet.*

类型与工具

• 错误码、订单状态、账户类型、场景枚举 → src/types/index.ts
• 国家编码枚举与查询：CountryDialCode、COUNTRY_CODES、findCountryCode()（来源于国家编码）

端点与时间参数说明

• 所有端点集中于 src/constants/endpoints.ts，与官方文档一致。用户资产类接口位于 ouser 路径，例如：

    /** 充值地址 */
    depositAddress: '/user/depositAddress',
    /** 用户资产查询（多币种） */
    userAccounts: '/ouser/userAccounts',
    /** 用户资产查询（多币种）V2 */
    userAccountsV2: '/ouser/v2/userAccounts',
    /** 批量查询商户下所有用户非0资产（按ID分批查询） */
    batchQueryUserAccountsByStartId: '/ouser/batchQueryUserAccountsByStartId',
    /** 批量查询商户下所有近期变动的用户资产（按更新时间） */
    batchQueryUserAccountsByUpdateTime: '/ouser/batchQueryUserAccountsByUpdateTime',
    /** 用户账户余额（全币种） */
    accountBalance: '/user/accountBalance',

• 时间字段：SDK 对多处接口的秒级时间戳自动乘以 1000（转为毫秒），包括现货/OTC 手续费、资金记录、增值服务、钱包划转记录等，减少 10020 参数错误。

示例

见 examples/quickstart.ts，覆盖授权、下单、支付页拼接与常用查询。

测试

此仓库为示例 SDK，不包含对真实接口的联调测试。建议在集成项目中以 Mock 或沙箱环境自测。