📘CoinSend篇

CoinSend可让用户在不触碰私钥或设备的情况下，通过币种、限额等参数的设定，实现多角色流程审批的下发/ 提币/ 付款业务管理。

CoinSend客户端详情

请在Google Play商店，或CoinsDo官网下载应用程序，并运行在可靠的设备中。

使用CoinSend业务时，CoinSend客户端需保持在线。

接口描述

• 查询下发钱包的详情

请求地址

• {URL}/v1/deviceDetail

请求方式

• POST

• Body 参数

参数名	必填	类型	说明
data	是	string	内容（JSON字符串，如下）

{
    "apiKey": "cd384rt80f5575dc",
    "deviceUuid": "2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4D"
}

• data 参数

参数名	必填	类型	说明
apiKey	是	string	API KEY
deviceUuid	是	string	下发钱包标识

请求示例

{
    "data": "{\"apiKey\":\"cd384rt80f5575dc\",\"deviceUuid\":\"2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4D\"}",
    "sign": "d32bfb9905f0b6713be45fea2bce001449146a43b3319479076a6d8c2bf22055"
}

返回示例

{
    "code": 200, // 状态码
    "msg": "成功", // 提示信息
    "data": {
        "onlineStatus": 1,
        "useStatus": 1,
        "addressList": [{
            "flag": "TRX",
            "address": "TEN51U1W5hW5bJ833J6CLojvJdFGEQtz39",
            "balance": "222.1",
            "currency": "TRX"
        }, {
            "flag": "0xe7b0d9104aec8ea4ec6a02dfc5ae5180f9f78f95",
            "address": "TKU69qcQPoR5jDEE7ertPpdaxoLGCTX4xR",
            "balance": "6161.999",
            "currency": "TRC20"
        }],
        "devicePublicKey":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQD311wvweaxTv9bJBz3dxxd8e1nhInyoS/my8zarbeyqwAcTjWkMsWQt5cquU5G463nd5nSAOUGDgdytOZu78ZT4OQPFyeKRM/TWC7ghibhi/FDxJvE7txj7QRjdY0vTDTM/6CYxi2F8PIgjzX9TKBP7DK6pZq/sN1VciBuRWz2kQIDAQAB"
        "deviceExpiryTime": "1628380800",
        "deviceRegisterTime": "1625802606"
    }
}

添加子账户的审批设备

子账户仅可在已绑定CoinSign插件的Chrome/ Firefox浏览器或CoinSign客户端完成审批操作。 CoinSend会对下发指令进行签名验证，确保指令不可篡改且来自授权角色的可信设备。

接口描述

• 添加子账户的审批设备

请求地址

• {URL}/v1/reviewAdd

请求方式

• POST

• Body 参数

参数名	必填	类型	说明
data	是	string	内容（JSON字符串，如下）

{
    "apiKey": "cd384rt80f5575dc",
    "reviewPubkey":"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDi7RszjTelyGLJmpyXUPKo7xSUGQSv/5fUXO0npAGKP0oukx7tHQ6nJsnXdztX3yR3zhgjBnCdqN8DBPr+LzF4kSzG4t2/a6NdFlnPAUrtFZcqRbGDwliIqlKb5XCTu0Pgs6fNjx8tPE6XIW7OX/8NmQIbBw9Qjn28gjSuaTAD9QIDAQAB",
    "plainText":"test",
    "signature":"Fy6kcJsOY38jO+m/OsvmVj9kJdkC8CCl4WwPbMjWP/AAGS3dAAUHgIGQQlkIo3uBiEIIr85axpYmmsvXfeGg3MmYLim1XOeI65oOnDN084EaXjlCvTlFMqnt61YUYcN/9WPRjtbOsfSaK1ivOfKux9Fh8lGzRoNYKahCA1t69Kk=",
    "authorizationCode": "CFZQ-RJWN-VDDH"
}

• data参数

参数名	必填	类型	说明
apiKey	是	string	API KEY
reviewPubkey	是	string	审核设备公钥
plainText	是	string	待验证字符串
signature	是	string	签名(对plainText字段进行SHA256withRSA签名)
authorizationCode	是	string	设备授权码

请求示例

{
    "data": "{\"apiKey\":\"cd384rt80f5575dc\",\"reviewPubkey\":\"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDi7RszjTelyGLJmpyXUPKo7xSUGQSv/5fUXO0npAGKP0oukx7tHQ6nJsnXdztX3yR3zhgjBnCdqN8DBPr+LzF4kSzG4t2/a6NdFlnPAUrtFZcqRbGDwliIqlKb5XCTu0Pgs6fNjx8tPE6XIW7OX/8NmQIbBw9Qjn28gjSuaTAD9QIDAQAB\",\"plainText\":\"test\",\"signature\":\"Fy6kcJsOY38jO+m/OsvmVj9kJdkC8CCl4WwPbMjWP/AAGS3dAAUHgIGQQlkIo3uBiEIIr85axpYmmsvXfeGg3MmYLim1XOeI65oOnDN084EaXjlCvTlFMqnt61YUYcN/9WPRjtbOsfSaK1ivOfKux9Fh8lGzRoNYKahCA1t69Kk=\",\"authorizationCode\":\"CFZQ-RJWN-VDDH\"}",
    "sign": "ee7809433ed0200b55f79e85f3489d455a28ac3f14c8757b7799f890f42d74e8"
}

返回示例

{
    "code": 200, // 状态码
    "msg": "成功", // 提示信息
    "data": {
        "uuid": "2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4W"
    }
}

• data 参数

参数名	必填	类型	说明
uuid	是	string	审核设备标识

返回状态码

状态码	说明
4015	查询授权码失败
4016	授权码失效或不存在
4018	添加审核设备失败
4019	SHA256withRSA验签失败

下发（提币）

企业可以通过CoinsDo API 来执行全自动下发或人工手动审批下发。

审批角色说明

数据提交：有这个权限的子账号可以添加下发记录。

数据审批：有这个权限的子账号可以审批提交者的下发记录。有数据审批权限的子账号（一审）会审核所提交的数据然后进行签名。一审审核的数据是业务ID、发送地址、下发数量、币种/协议、和标识/代币ID/合约地址。

执行审批：有这个权限的子账号可以执行审批后的下发记录。执行审批权限的子账号（二审）会审核一审所签名的数据然后进行签名。二审审核的数据是业务ID和选择下发钱包。二审签名后会执行下发记录。

手动下发

企业会先设置提交数据、数据审批、和执行审批权限给子账号。这三个角色都是由不同的人物来处理。首先，拥有数据提交权限的子账号会提交下发记录，填写币种/协议、标识/代币ID/合约地址、接受地址、和下发数量。其次，拥有数据审批权限的子账号会对提交的数据进行审批。签名后会提交给拥有执行审批的子账号签名然后执行下发。

1. 具有提交数据权限的子账号可以使用企业业务服务器进行提款

2. 企业业务服务器透过CoinsDo API提交下发请求给CoinsDo服务器

3. 企业设置的审核人员A可以进行数据审批并签名

4. 企业设置的审核人员B可以进行执行审批并签名然后提交签名A和B给CoinsDo服务器

5. CoinsDo服务器收到企业设置的审核人员的签名后透过CoinsDo API提交带有签名的数据给企业下发钱包客户端

6. 企业下发钱包客户端对收到的签名A和签名B进行校签后执行下发

自动下发

企业必须把提交数据、数据审批、和执行审批权限分配给一个服务端账号才能执行自动下发方案。

企业也可以把自动下发的部分过程分配给服务端和普通账号。举个例子，服务端账号可以自动创建一个下发记录然后让其他两个普通账号来手动的数据审批和手动的执行审批那个下发记录。

1. 具有提交数据权限的子账号可以使用企业业务服务器进行提款

2. 企业业务服务器透过CoinsDo API提交下发请求和把数据签名后提交给CoinsDo服务器

3. CoinsDo服务器收到带有签名的数据后透过CoinsDo API提交给企业下发钱包客户端

4. 企业下发钱包客户端对收到带的签名的数据进行校签后执行下发

接口描述

• 发起下发申请

请求地址

• {URL}/v1/withdraw

请求方式

• POST

请求参数

• Body 参数

参数名	必填	类型	说明
data	是	string	内容（JSON字符串，如下）

{
    "apiKey": "cd384rt80f5575dc",
    "submitAccount": "coinsdoTest",
    "address": "TKU69qcQPoR5jDEE7ertPpdaxoLGCTX4xR",
    "amount": "616.616",
    "coinsDoId": "3",
    "businessId": "TRX_999",
    "businessScene": "1",
    "timestamp": "1622775712229",
    "txMemo": "COINSDO TEST TRX",
    "reviewUuid": "A65F7B1C-8FF8-4E0D-ADF2-AE0BCB0F378B",
    "reviewSign": "DXoICpzZN7/yoHCLbb32czn0Goq9XLTdW9Dcn281qNNgcejzXPToGOJReA/wYMI0e3ikjAVxzXSDXImAFqslbjBbiR8PVnXImV6VBMYL5J3Lssfu4nZMPEPNgIFtAWlLk9drWoElGe/Ch6NaozD9VJx5xPNIPq7ErVwfeB+g2LM=",
    "reviewRemark": "trx test",
    "targetDeviceUuid": "2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4D",
    "approveUuid": "BD9D4D2C-6689-4FE1-88BB-C9DA5A251A30",
    "approveSign": "vPuFWmtV/KbemdN/5IqRhyfY63kp55HSZEErFa0rtJco861WkUsesaJ1U5kV0oX3bn5U8iVEKGeAzA37s/jMBy8hq62r1fstvhZ6vcgX5FuqtvvL8fTOeRuK9v85e7FR/89U2Jm/KbVt0US2Xe1oQz2D7lDvFW15ZtSQdp8JoVA=",
    "approveRemark": "trx test"
}

• data 参数

参数名	必填	类型	说明
apiKey	是	string	API KEY
submitAccount	是	string	提交账号(服务端审核账号)
address	是	string	下发地址
amount	是	string	下发数量
coinsDoId	是	string	币种ID(参数见币种列表)
businessId	是	string	业务ID(不可重复)
businessScene	否	string	业务场景
timestamp	是	string	时间戳(秒或毫秒)
txMemo	否	string	链上备注( XRP 和 EOS tag 填这里）
reviewUuid	否	string	数据审批(一审)设备标识 (已一审的数据该字段必填)
reviewSign	否	string	数据审批(一审)数据签名 (已一审的数据该字段必填，进行RSA-SHA256签名:businessId=业务ID&address=地址&amount=数量&coinsDoId=coinsDoId， ❗注：数量字段需去除小数位后多余的零， 例：amount=1.010 应转换成 amount=1.01、amount=1.000 应转换成 amount=1)
reviewRemark	否	string	数据审批(一审)备注
targetDeviceUuid	否	string	审批执行(二审)指定下发钱包 (已二审的数据该字段必填)
approveUuid	否	string	审批执行(二审)设备标识 (已二审的数据该字段必填)
approveSign	否	string	审批执行(二审)数据签名(已二审的数据该字段必填，进行RSA-SHA256签名:businessId=业务ID&deviceUuid=CoinSend客户端标识)
approveRemark	否	string	审批执行(二审)备注
targetAddrIndex	否	string	指定发送地址派生序号(指定发送地址后审批执行(二审)数据签名规则更改，进行RSA-SHA256签名:businessId=业务ID&deviceUuid=CoinSend客户端标识&targetAddrIndex=指定发送地址派生序号)

请求示例

{
    "data": "{\"apiKey\":\"cd384rt80f5575dc\",\"submitAccount\":\"coinsdoTest\",\"address\":\"TKU69qcQPoR5jDEE7ertPpdaxoLGCTX4xR\",\"amount\":\"616.616\",\"coinsDoId\":\"3\",\"businessId\":\"TRX_999\",\"businessScene\":\"1\",\"timestamp\":\"1622775712229\",\"txMemo\":\"COINSDOTESTTRX\",\"reviewUuid\":\"A65F7B1C-8FF8-4E0D-ADF2-AE0BCB0F378B\",\"reviewSign\":\"3pIsqtrXPG/I4o/YGLOvtIvBUUrBrRyFehlt0wkezWU4u0dj5xXEoZ9E4EXSes9WawqfpxrRfOIHgXV1BnPNM2tt0DLloCnJkzR7smC26+z6kuZb87s3hitZWgM3UaWWghB8/qNMQImvCZ6MREqChoNmEVyaqCnTbjorKsrU/V0=\",\"reviewRemark\":\"trxreview\",\"targetDeviceUuid\":\"2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4D\",\"approveUuid\":\"BD9D4D2C-6689-4FE1-88BB-C9DA5A251A30\",\"approveSign\":\"vPuFWmtV/KbemdN/5IqRhyfY63kp55HSZEErFa0rtJco861WkUsesaJ1U5kV0oX3bn5U8iVEKGeAzA37s/jMBy8hq62r1fstvhZ6vcgX5FuqtvvL8fTOeRuK9v85e7FR/89U2Jm/KbVt0US2Xe1oQz2D7lDvFW15ZtSQdp8JoVA=\",\"approveRemark\":\"trxapprove\"}",
    "sign": "d32bfb9905f0b6713be45fea2bce001449146a43b3319479076a6d8c2bf22055"
}

返回示例

{
    "code": 200, // 状态码
    "msg": "成功", // 提示信息
    "data": null // 返回内容
}

返回状态码

状态码	说明
4006	下发币种暂不支持
4008	业务ID已存在
4009	新增下发记录失败
4011	查询审核设备失败
4012	数据审批(一审)设备不存在
4013	审核设备未绑定审核账号
4014	数据审批(一审)签名验签失败
4015	查询授权码失败
4016	授权码失效或不存在
4017	查询审核设备失败
4018	添加审核设备失败
4019	SHA256withRSA验签失败
4020	查询商户子账户失败
4021	没有数据提交权限
4022	没有数据审批(一审)权限
4023	超过币种最大小数位
4024	数据审批(一审)参数不全
4025	下发地址格式有误
4026	审批执行(二审)参数不全
4027	审批执行(二审)设备不存在
4028	审批执行(二审)签名验签失败
4029	没有审批执行(二审)权限
4030	下发数量超过数据审批(一审)额度
4031	下发数量超过审批执行(二审)额度
4032	查询钱包失败
4033	钱包不存在
4038	校验下发地址失败
4039	提交账号已停用
4040	数据审批(一审)设备所绑定的账号已停用
4041	审批执行(二审)设备所绑定的账号已停用
4048	下发数量小于最低要求
4049	提交账号不是服务端账号
4056	数据审批账号当前绑定的审核设备未在钱包授权，请联系管理员重新授权钱包
4057	执行审批账号当前绑定的审核设备未在钱包授权，请联系管理员重新授权钱包
4065	检查业务ID失败
4066	检查支持的币种失败
4067	CoinsDoId应是整数
4069	商户子账户不存在
4070	请指定币种

回调通知

参数名	必填	类型	说明
data	是	string	内容（JSON字符串，如下）

{
    "txTime": "1661336430",
    "businessId": "0x6305fb61_JDXqh_0_2",
    "mainnet": "TRX",
    "withdrawStatus": "1",
    "txMemo": "0",
    "feeSymbol": "TRX",
    "blockNumber": "29232059",
    "txFee": "8.34196",
    "coinName": "JST",
    "txHash": "b29e917066ed433b5d2753ae07a9b4bd71245509f8f9de51ec5a2e43425f91a8"
}

• data 参数

参数名	必填	类型	说明
businessId	是	string	业务ID
withdrawStatus	是	string	下发状态(1.下发成功 2.下发驳回 5.下发取消)可扩展字段，后续会增加其他的状态回调
txHash	否	string	交易哈希
blockNumber	否	string	区块高度
txTime	否	string	交易确认时间戳(秒)
txFee	否	string	矿工费
feeSymbol	否	string	矿工费单位/标识
businessScene	否	string	业务场景(API提交该字段的原数据返回)
txMemo	否	string	链上备注
mainnet	是	string	主链名称
coinName	是	string	币种名称

请求示例

{
    "data": "{\"txTime\":\"1661336430\",\"businessId\":\"0x6305fb61_JDXqh_0_2\",\"mainnet\":\"TRX\",\"withdrawStatus\":\"1\",\"txMemo\":\"0\",\"feeSymbol\":\"TRX\",\"blockNumber\":\"29232059\",\"txFee\":\"8.34196\",\"coinName\":\"JST\",\"txHash\":\"b29e917066ed433b5d2753ae07a9b4bd71245509f8f9de51ec5a2e43425f91a8\"}",
    "sign": "1b248bbf33dffb5004f4f179bb4b20e1a455e5c7d3be366c0b07e75ddc229d10"
}

返回示例

{
    "code": 200, // 状态码
    "msg": "成功", // 提示信息
    "data": {
        "businessId": "TRX_999"
    } 
}

• data 参数

参数名	必填	类型	说明
onlineStatus	是	string	在线状态(0.离线 1.在线)
useStatus	是	string	使用状态（0.停用 1.启用）
devicePublicKey	是	string	钱包公钥
deviceRegisterTime	是	string	钱包注册时间戳(秒)
deviceExpiryTime	是	string	钱包过期时间戳(秒)
addressList	否	array	发币地址列表

• addressList 参数

参数名	必填	类型	说明
currency	是	string	币种/协议
flag	是	string	标识/代币ID/合约地址
address	是	string	钱包发币地址
balance	否	string	地址余额

返回状态码

状态码	说明
4032	查询钱包失败
4033	钱包不存在
4034	查询地址失败
4035	查询币种失败
4036	查询余额失败
4037	查询钱包在线状态失败