Mixin 全币种钱包接入指南

简介

Mixin 是一个安全、免费、快速、加强隐私的去中心化支付网络，现已支持 13 条主链（BTC/ETH/EOS/DASH/XRP/XEM/SC/DOGE/BCH/LTC/ZEC/ETC/ZEN）超过 5.9 万种代币充值、提现和转账。

接入

0、准备

• 下载 Mixin Messenger，体验设置 PIN、充值、转账、提现流程，便于理解 API 文档
• 阅读官方开发指南：https://developers.mixin.one/guides

1、注册成为 Mixin 的 Developer

通过 Mixin Messenger 扫码登录 https://developers.mixin.one （点右上角）。

2、为您的全币种钱包创建一个 Mixin App

点 Create New App 按提示创建就行，通过这个 App 创建的用户都是你的用户，后续可以监听你创建用户的充值、提现和转账信息，并且可以获得提现手续费返还。

• The home uri. —— 这个一般填你们公司网站首页就行，例如 https://mixin.one，可以为空。
• The OAuth redirect uri. —— OAuth 授权回调，用于 Mixin Messenger 小程序，或者通过 Mixin Messenger 来登录你的应用。一般自己做 Dapp 用不着，但是又是必填项可以随便写一个链接，例如和 home uri 写一样的。

3、生成 Mixin App 相关的 Session

点 Click to generate a new session 生成 PIN、Session Id 、Pin Token、Private Key，这些都要记下来后面要用，服务器和浏览器都不会保存这些敏感信息（注意刷新再次点又会生成一个新的，会覆盖旧的）。

4、创建 Mixin Network 用户

参考文档 https://developers.mixin.one/api/alpha-mixin-network/app-user/ 和 https://developers.mixin.one/api/alpha-mixin-network/authentication-token/ ，会用到前面所说的 Session Id。

绝大部分 API 访问都需要在请求的 Header 里设置授权的 Token ，创建用户也需要，相关文档： https://developers.mixin.one/api/alpha-mixin-network/authentication-token/

• Mixin App 本身也是一个 Mixin Network 用户，这里称之为主账号，你可以给这个用户转入、转出资产，而通过主账号创建的用户这里称之为子账号。所以访问 API 之前你要想清楚你是要用哪个账号访问，才能正确的设置 User Id 和 Session Id。
• 如果子账号是由服务器生成的，不要与主账号共用私钥，应该为每一个用户生成一个新的私钥，通过新生成的私钥导出公钥创建子账号。参考 OceanONE 的代码： https://github.com/MixinNetwork/ocean.one/blob/master/example/models/pool_key.go 的 GeneratePoolKey 方法。
• 注意参考文档里的代码和文章末尾的 SDK 、Demo，生成的 Authentication Token 不对访问 API 会返回 401

Authentication Token 出错可能存在的几种情况：

• 复用了 jwt ，每次请求 API 都必须重新生成 jwt，不同的 API path 参数都是不一样的，不能复用
• 私钥不对，搞混了主账号和子账号的私钥，或私钥字符串换行有空格

5、设置 PIN 码

6 位数字 PIN 码是用户转移资产的唯一途径，丢失无法找回，可以理解为自己在 BTC/ETH 链上资产私钥同等作用。强烈建议不要替用户保管 PIN 码，除非特殊用途并且有能力保管好。相关 API : https://developers.mixin.one/api/alpha-mixin-network/create-pin/ 和 https://developers.mixin.one/api/alpha-mixin-network/encrypted-pin/

为了帮助用户安全记住自己的 6 位数字 PIN 码，Mixin Messenger 做了如下提醒：

• 设置初始 PIN 码或修改 PIN 码会让用户反复输入多达 4 - 5 次。
• 设置 PIN 码时会提醒用户不要设置过于简单不安全的 PIN 码，例如 123456。
• 每输入 PIN 码后间隔 24 小时进入钱包首页都会提醒用户输入一次 PIN 码辅助用户记忆。

注意事项：

• 要引导新用户设置自己的 PIN 码
• PIN 丢失无法找回，可以参考 Mixin Messenger 多一些提醒帮助用户记忆
• PIN 输入错误有时间锁，一天输错 5 次就不要再尝试了，建议用户记一下试过的 PIN 码，隔日再试

调用 API 提示 PIN 不对一般就几种情况：

• 私钥不对，搞混了主账号和子账号的私钥，或私钥字符串换行有空格
• PIN 本身不对
• iterator 用错了 —— 加密 PIN 的 iterator 参数必须是递增的，比如第一次加密用的 1 ，第二次必须大于 1 ，用当前系统时间也可以。
• 重复使用了加密 PIN —— 被加密的 PIN 只能用一次，不能设置完 PIN 后又马上拿上一次的加密 PIN 去转账或者修改 PIN。

关于安全的指纹支付方案 iOS 可以搜索 Secure Enclave 、Android 搜索 isInsideSecureHardware ，也可以直接使用 Mixin Messenger 的源码来实现。

6、获取用户资产

相关 API：https://developers.mixin.one/api/alpha-mixin-network/read-assets/ 和 https://developers.mixin.one/api/alpha-mixin-network/read-asset/

• 有图标的代币说明我们已经验证过了 —— 这个代币就是图标所代表的代币类型，防止类似重名币带来的问题。如果需要显示项目代币图标，需要先把项目信息提交到 https://coinmarketcap.com ，然后在 https://github.com/MixinNetwork/asset-profile 提 pr 。
• 注意新用户 GET /assets 默认不会返回任何资产列表，Dapp 自己的服务器可以自定义一个列表返回，例如 OceanONE 的就用一个 json 来配置的 https://github.com/MixinNetwork/ocean.one/blob/master/example/web/src/api/assets.json 。如果想要特定资产 asset id 而接口没有返回，可以充值或转账该类型的代币，到账后再次调用接口就有了。
• 注意 GET /assets 并不会创建充值地址，需要调用 GET /assets/:id 才会为用户创建充值地址（链上地址），有可能需要间隔调用多次才会返回充值地址（创建地址也需要时间，不过一般很快），界面上可以显示一个转圈。

7、充值

https://developers.mixin.one/api/alpha-mixin-network/read-assets/ 会返回充值地址，如果没有返回进入资产详情界面继续调用 https://developers.mixin.one/api/alpha-mixin-network/read-asset/ 来刷新获取充值地址。

• 同一主链的充值地址是相同的，例如可以直接往 BTC 的充值地址充入 Omni USDT，符合 ERC-20 的代币都可以充到 ETH 的充值地址。
• EOS、BTS 充值需要通过 account_name 和 account_tag（memo） 来获取充值地址，其他的资产通过 public_key 获取充值地址，需要同时判断这三个字段来区别充值类型和是否返回了充值地址。
• Mixin Network 充值确认数高于一般钱包和交易所两倍以上，充值会慢一些，主要目的是为了安全，可以有效阻止双花等问题。可以通过 confirmations 字段动态获取展示给用户。
• 超过正常充值时间许久还未到账可能是我们的区块数据同步出现了故障，可以查看区块链浏览器 https://mixin.one/network/chains 检查，确认故障请提醒 Mixin 开发团队。
  

8、转账

相关 API https://developers.mixin.one/api/alpha-mixin-network/transfer/ ，注意 trace_id 非常重要，可以有效的防止重复支付。

Mixin Messenger 会在进入转账界面时生成一个 trace id ，这样后续支付出现网络问题重试的时候就不会重复支付

有的团队会使用 snapshot_id 来做随机数，这是一个 UUID ，转账成功才会生成，Mixin Network 能确保唯一性

/snapshots 可能查看自己的转账记录，参考 API : https://developers.mixin.one/api/alpha-mixin-network/network-snapshots/ ，但是不支持 order 参数（注意不是 /network/snapshots ，没有 network 就只返回自己的转账记录，有的话就是全网转账记录）

9、提现

注意提现需要先添加提现地址（收币地址），并且每次修改、删除地址都需要 PIN。内部充值提现（Mixin Network 的 Dapps 之间充值提现）是免费秒到的，例如从 Mixin Messenger 充值提现到 OceanONE、从 FOX.ONE 充值提现到 Mixin Messenger。

• EOS、BTS 提现需要通过 account_name 和 account_tag 来添加提现地址，其他的资产通过 public_key 和 label 来添加提现地址，相关 API https://developers.mixin.one/api/alpha-mixin-network/create-address/。
• 提现有最小限制，可以根据 dust 字段判断，内部提现不受影响
• 有的代币提现需要账户留储备金（不能提空），可以根据 reserve 判断，例如 XRP
• 提现手续费是动态的，可以根据 fee 获取，内部提现一般为 0 ，个别 Dapp 出于业务考虑仍然会收提现手续费
• 注意充值地址和提现地址并不相同，提现可能从一个或多个随机链上资产地址提取，相关细节可以参考 Mixin 的技术白皮书。
• 提现手续费会以 XIN 的形式按月申请返还给开发者（具体细节有待进一步落实）

10、监听用户充值、提现和转账

如果需要监听所有你 App 创建用户发生的充值、提醒和转账记录，你需要不断的扫描整个 Mixin Network ，是你的用户就会返回 user_id 字段，相关 https://developers.mixin.one/api/alpha-mixin-network/network-snapshots/

• 注意 API 不提供过滤只有自己用户的参数

可以参考一下 OceanONE 的代码 https://github.com/MixinNetwork/ocean.one/blob/master/exchange.go 里的 PollMixinNetwork

• 监听用户充值进度 API : https://developers.mixin.one/api/alpha-mixin-network/external-transactions/ ，这个是全网的充值进度，并不保证 100% 准确性，只是提供一个查询功能，该 API 和 Network Snapshots 是两个独立的服务运行，所有极少数情况下会出现同时返回。注意 API 不提供根据用户来过滤的参数，需要 Dapp 记录一下自己用户的 public key 或者 account tag 和 account name 来过滤自己用户的充值进度

11、转移主账号的资产

• 点 App Id 进入 Update Token 界面，输入步骤 3 保存的 Session Id、Pin Token、Private Key 提交
• 点 App Id 右边的钥匙图标进入资产列表界面（如果没有设置 Token 也会引导至 Update Token 界面）
• 点击具体某个资产进入提现界面即可

给主账号充值需要通过 Mixin Messenger 来完成，先将资产充值到开发者账号（扫描登录 developers.mixin.one 的这个账号），然后在 Mixin Messenger 里搜索主账号的 App Id，进入会话再完成转账操作（可以先小额转账测试一下）。注意只能给开发者自己的主账号转账，你会发现点别人开发的小程序都没有转账这一项。

12、资源

• Golang SDK：https://github.com/MixinNetwork/bot-api-go-client
• Mixin Messager Android：https://github.com/MixinNetwork/android-app
• Mixin Messager iOS：https://github.com/MixinNetwork/ios-app
• Nodejs Demo （非官方）: https://github.com/virushuo/mixin-node
• Python Demo（非官方）: https://github.com/myrual/mixin_client_demo
• Java Demo（非官方）: https://github.com/qige-one/mixin_java_sdk
• Mixin 官方开发者群：https://mixin.one/codes/0f2a743d-d86b-4a6c-b26c-14e320799311

13、其他

• Mixin 全币种钱包支持 EOS、BTS 空投，但不完全支持其他代币的空投，用户可能会收到数量不定的空投币，充值和提现地址不同可以说明这点，这与 Mixin Network 整体设计有关。