开放API接口 USDT快捷接入充提教程

Posted 2020-12-16 区块链研究僧

 

API，全称Application Programming Interface，中文翻译为应用程序编程接口，口语中常称接口。API是一些预先设定好的函数。为应用程序及技术开发人员提供基于某种软件或者硬件获取访问例程的能力，且不需要对源码进行访问，或者去理解一些内部工作机制的细枝末节。

 

为了让这个冰冷的技术名词易于理解，可以通俗的理解为，api相当于一个房门的钥匙。在这个大House里，每个房间都具备了不一样的用途与资源。如果想得到对应房间里的资源，第一步肯定是拿钥匙打开房门。调用API的过程，相当于钥匙开门的过程。

 

在API中，可分为open API以及私有APIi。Open API ，从字面理解，指的是对外公开的API接口，允许任何人调用它并得到到它背后的数据。它就好比于当前你要进入大型购物商场，首先必须得做出相应的身份认证比如扫描安康码，才可以进入商超获取到相应的产品及资源，而身份认证扫安康码意味着是你得到商场里产品资源的一个钥匙，道理同API。

 

现在很多企业或者应用程序都开放自己的open api，以便于技术开发人员调用方便，并且很多企业采用详细接口文档的形式进行输出，或者采用sdk文档方式打包。像优盾钱包研发团队就为企业及个人能够快速方便的接入数字货币而开发的一套应用系统，开放了优盾钱包API开发接口文档以及像Java、.Net、php多种语言的SDK对接交易所。

 

稳定币USDT在规避整个行情下跌风险、反向操作 数字货币提现方面占据着得天独厚的优势。不仅是各个交易所的宠儿，也深受投资者的青睐。随着企业(交易所、商城、游戏)业务型系统快速方便对接USDT的需求逐步扩大，API“钥匙”的作用愈发明显， 交易所等企业不得不面临接口对接怎么实现，对接步骤如何实现，支付接口如何对接的困惑。优盾钱包，作为全球首款交易所钱包管理系统，集审核、代付、归集功能于一身。自上线以来，安全运行700+天，交易所用户遍及中国、中国台湾、日、韩、美国、澳大利亚及加拿大等国家和地区，累计为用户管理资产总额达100000000+USDT，用户日均交易额达2000万USDT。

 

接下来，以它为例， 来解答usdt钱包接口对接怎么实现，对接步骤如何实现，支付接口如何对接的困惑。

 

详细接口文档如下：

1、目录

1.1、生成地址

1.2、提币

1.3、代付

1.4、交易回调

1.5、校验地址合法性

1.6、获取商户支持币种信息

2、接口明细

1、生成地址

1.1 场景说明

请求指定币种地址,如要成功获取地址,需先存在钱包,且钱包支持该币种, 详情参看

1.2 接口详情

1.2.1 接口地址

接口详情
URL	【/mch/address/create】
请求方式	POST

1.2.2 参数

1.2.2.1 参数说明

参数	类型	是否必填	说明	备注
timestamp	String	是	时间戳	见 验签说明
nonce	String	是	随机数	见 验签说明
sign	String	是	签名	见 验签说明
body	String	是	消息内容	json字符串，格式如下

[

    {

     "merchantId":"300015",

     "coinType":520,

     "callUrl":"http://localhost:8080/callBack"

    }

]

1.2.2.2 body参数字段

body参数名	类型	是否必填	说明
merchantId	String	是	商户号
coinType	Integer	是	主币种编号，见 附录一
callUrl	String	是	回调地址，通过该接口创建的地址，以后关于该地址的充币信息会通过您指定的回调地址通知您。具体示例见 交易回调接口
walletId	String	否	钱包编号,默认根据主钱包生成地址
alias	String	否	地址别名

1.2.2.3 示例

{

    "timestamp": 1535005047,

    "nonce": 10000,

    "sign": "a230def43c1a12b14393880a28d4e005",

    "body": "[{"merchantId":"300015","coinType":520,"callUrl":"http://localhost:8080/callBack"}]" 

}

1.2.3 返回状态码表

code	解释
200	成功
4005	非法参数
4001	商户不存在
4169	商户已禁用
4162	签名错误
4175	钱包编号错误
4017	商户没有创建钱包
4176	钱包未添加支持该币种
4166	商户没有配置套餐
4168	商户地址达到上限
4045	币种信息错误
-1	获取地址失败

1.3 调取示例

1.3.1 成功

{

    "data":{

        "coinType":520,

        "address":"0xbe4e3699cb870bc95365fe04a187dd279a651a58"

    },

    "message":"SUCCESS",

    "code":200

}

1.3.2 失败

{

    "code": "4101",

    "message": "SIGN_MSG_ERROR"

}

 

 

 

2、发送提币申请

2.1 场景说明

提币申请

2.2 接口详情

2.2.1 接口地址

接口详情
URL	【/mch/withdraw】
请求方式	POST

2.2.2 参数

2.2.2.1 参数说明

参数	类型	是否必填	说明	备注
timestamp	String	是	时间戳	见 验签说明
nonce	String	是	随机数	见 验签说明
sign	String	是	签名	见 验签说明
body	String	是	消息内容	json字符串，格式如下

[

    {

        "address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",

        "amount":"0.11",

        "merchantId":"100109",

        "mainCoinType":"144",

        "coinType":"144",

        "callUrl":"http://localhost:8080/mch/callBack",

        "businessId":"15",

        "memo":"10112"

    }

]

2.2.2.2 body参数字段

body参数名称	是否必填	类型	说明
address	是	String	提币地址
amount	是	String	提币数量
merchantId	是	String	商户号
mainCoinType	是	String	主币种编号 （见 附录一 ）
coinType	是	String	子币种编号 （见 附录一 ）
callUrl	是	String	回调地址，通过该callUrl告知您该笔提币交易的状态,具体示例见 交易回调接口
businessId	是	String	业务id，必须保证该字段在系统内唯一，如果重复，则该笔审核钱包不会接收。
memo	否	String	备注,XRP和EOS，这两种币的提币申请该字段可选，起他类型币种不填

2.2.2.3 示例

{

  "timestamp": 1535005047,

  "nonce": 100000,

  "sign": "6df1512ee650431632ce1541a6b064e1",

  "body": "[{"address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s","amount":"0.11","merchantId":"100109","mainCoinType":"144","coinType":"144","callUrl":"http://localhost:8080/callBack","businessId":"15","memo":"10112"}]" 

}

2.2.3 返回状态码表

code	解释
200	成功
4005	非法参数
4598	传入body中的list对象中的所有merchantId必须保持一致
4001	商户不存在
4169	商户已被禁用
4183	到账地址异常
4193	EOS金额小数点后超过4位长度
4034	未找到该币种信息

2.3.1 成功

{

    "message":"SUCCESS",

    "code":200

}

2.3.2 失败

{

    "code": "4101",

    "message": "SIGN_MSG_ERROR"

}

3、代付

3.1 场景说明

代付,发送自动付款申请，未设置代付信息或代付失败则进入审核状态。

3.2 接口详情

3.2.1 接口地址

接口详情
URL	【/mch/withdraw/proxypay】
请求方式	POST

3.2.2 参数

3.2.2.1 参数说明

参数	类型	是否必填	说明	备注
timestamp	String	是	时间戳	见 验签说明
nonce	String	是	随机数	见 验签说明
sign	String	是	签名	见 验签说明
body	String	是	消息内容	JSON字符串，格式如下

[

  {

      "address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",

      "amount":"0.1",

      "merchantId":"100146",

      "mainCoinType":"144",

      "coinType":"144",

      "callUrl":"http://localhost:8080/callBack",

      "businessId":"571001",

      "memo":"10112"

  }

]

3.2.2.2 body参数说明

body参数名称	类型	是否必填	说明
merchantId	String	是	商户号
address	String	是	提币地址
mainCoinType	String	是	主币种编号，见 附录一
coinType	String	是	子币种编号，见 附录一
amount	String	是	交易数量
callUrl	String	是	回调地址,提币（审核、交易）结果将通过该地址进行回调，具体示例见 交易回调接口
businessId	String	是	业务id，必须保证该字段在系统内唯一，如果重复，则该笔提币钱包将不会进行接收
memo	String	否	备注,XRP和EOS，这两种币的提币申请该字段可选，起他类型币种不填

3.2.2.2 示例

{

    "timestamp": 1535005047,

    "nonce": 100000,

    "sign": "e1bee3a417b9c606ba6cedda26db761a",

    "body": "[{"address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s","amount":"0.1","merchantId":"100146","mainCoinType":"144","coinType":"144","callUrl":"http://localhost:8080/callBack","businessId":"571001","memo":"10112"}]"

}

3.2.3 返回状态码表

code	解释
200	成功
4005	非法参数
4001	商户不存在
4166	商户没有配置套餐
4169	商户已被禁用
4612	签名错误
4163	签名信息错误
569	无效的地址
571	已存在审核记录,将不再进行处理
581	非法提币金额
554	商户不支持该币种

3.3 调取示例

3.3.1 成功

{

    "message":"SUCCESS",

    "code":200

}

3.3.2 失败

{

    "code": "4101",

    "message": "SIGN_MSG_ERROR"

}

 

 

 

4、交易回调接口

4.1 场景说明

网关收到交易处理结果，调用商户提供的回调接口，通知商户具体变化信息。该接口网关发送给您指定的回调地址的内容，处理您的业务信息。 分充值回调和提币回调，其中提币最多会进行两次回调（审核回调+交易结果回调）

4.2 接口详情

4.2.1 接口地址

接口详情
URL
请求方式	POST

4.2.2 参数

4.2.2.1 参数说明

参数	类型	是否必填	说明	备注
timestamp	String	是	时间戳	见 验签说明
nonce	String	是	随机数	见 验签说明
sign	String	是	签名	见 验签说明
body	String	是	消息内容	JSON字符串，格式如下

{

    "address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW",

    "amount":"12345678",

    "blockHigh":"102419",

    "coinType":"206",

    "decimals":"8",

    "fee":"452000",

    "mainCoinType":"206",

    "status":3,

    "tradeId":"20181024175416907",

    "tradeType":1,

    "txId":"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0",

    "businessId":"",// 提币回调为提币接口传入的businessId，充币无值

    "memo":""

}

4.2.2.2 body参数说明

body参数名称	类型	说明
address	String	地址
amount	String	交易数量，根据币种精度获取实际金额，实际金额=amount/pow(10,decimals)，即实际金额等于amount除以10的decimals次方
fee	String	矿工费，根据币种精度获取实际金额，实际金额获取同上
decimals	String	币种精度
coinType	String	子币种编号,见 附录一
mainCoinType	String	主币种编号,见 附录一
businessId	String	业务编号，提币回调时为提币请求时传入的，充币回调无值
blockHigh	String	区块高度
status	Integer	状态，见 回调接口状态说明
tradeId	String	交易流水号
tradeType	Integer	交易类型,见 回调接口交易类型说明
txid	String	区块链交易哈希
memo	String	备注，XRP和EOS（见 附录一 ），这2种类型币的充提币可能有值

4.2.2.2 示例

{

    "timestamp": 1535005047,

    "nonce": 100000,

    "sign": "e1bee3a417b9c606ba6cedda26db761a",

    "body": "{"address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW","amount":"12345678","blockHigh":"102419","coinType":"206","decimals":"8","fee":"452000","mainCoinType":"206","status":3,"tradeId":"20181024175416907","tradeType":1,"txId":"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0"}"

}

5、校验地址合法性

5.1 场景说明

校验地址的合法性,添加地址、提币申请等场景时可先校验地址合法性，参看 校验规则

5.2 接口详情

5.2.1 接口地址

接口详情
URL	【/mch/check/address】
请求方式	Post

5.2.2 参数

5.2.2.1 参数说明

参数	类型	是否必填	说明	备注
timestamp	String	是	时间戳
nonce	String	是	随机数
sign	String	是	签名
body	String	是	消息内容	JSON字符串，格式如下

{

    "merchantId":200000,

    "mainCoinType":"206",

    "address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW"

}

5.2.2.2 body参数说明

body参数名称	类型	是否必填	说明
merchantId	Long	是	商户号
mainCoinType	String	是	主币种编号，见 附录一
address	String	是	需校验的地址

5.2.2.2 示例

{

    "timestamp": 1535005047,

    "nonce": 100000,

    "sign": "e1bee3a417b9c606ba6cedda26db761a",

    "body": "[{"merchantId":200000,"mainCoinType":"206","address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW"}]"

5.2.3 返回状态码表

code	解释
200	成功
4005	非法参数
4162	签名错误
4165	地址不合法

5.3 调取示例

5.3.1 成功

{

    "code":200,

    "message":"SUCCESS"

}

5.3.2 失败

{

    "code":4005,

    "message":"PARAM_ERROR"

}

6、获取商户支持的币种信息

6.1 场景说明

获取商户支持的币种,以及余额

6.2 接口详情

6.2.1 接口地址

接口详情
URL	【/mch/support-coins】
请求方式	POST

6.2.2 参数

6.2.2.1 参数说明

参数	类型	是否必填	说明
timestamp	String	是	时间戳
nonce	String	是	随机数
sign	String	是	签名
body	String	是	消息内容

6.2.2.2 body参数说明

body参数名称	类型	是否必填	说明
merchantId	Long	是	商户号
showBalance	Boolean	是	是否查询余额，false不获取，true获取

6.2.2.3 示例

{

    "timestamp": 1535005047,

    "nonce": 100000,

    "sign": "e1bee3a417b9c606ba6cedda26db761a",

    "body": "{"merchantId":"200032","showBalance":true}"

}

6.2.3 返回状态码表

状态码	解释
200	成功
4005	body参数错误

6.3 调取示例

6.3.1 成功

{

    "code": 200,

    "message": "SUCCESS",

    "data":[

        {

            "name": "BTC", // 币种别名

            "coinName":"Bitcoin", // 币种全称

            "symbol":"BTC", // 币种单位

            "mainCoinType":"0", //主币种类型

            "coinType":"0", // 币种类型

            "decimals":"8", // 币种精度

            "tokenStatus":"0", // 0： 主币 1：代币

            "mainSymbol":"BTC", //主币种单位

            "balance":"0", // 币种余额

            "logo":"http://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/BTC.png" // 币种log地址

        },

        {

            "name": "ETH", // 币种别名

            "coinName":"Ethereum", // 币种全称

            "symbol":"ETH", // 币种单位

            "mainCoinType":"60", //主币种类型

            "coinType":"60", // 币种类型

            "decimals":"18", // 币种精度

            "tokenStatus":"0", // 0： 主币 1：代币

            "mainSymbol":"ETH", //主币种单位

            "balance":"0", // 币种余额

            "logo":"https://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/ETH.png" // 币种log地址

        }

    ]

}

6.3.2 失败

{

    "code":4005,

    "message":"BGS_ILLEGAL_PARAMETER"

}

附录一

主币种编号	子币种编号	币种简称	币种英文名	币种中文名称	精度
0	0	BTC	Bitcoin	比特币	8
60	60	ETH	Ethereum	以太坊	18
0	31	USDT	Tether USD	泰达币	8
520	520	CNT	CNT	测试币	18
5	5	DASH	DASH	达世币	8
133	133	ZEC	ZEC	大零币	8
145	145	BCH	Bitcoincash	比特币现金	8
61	61	ETC	Ethereum Classic	以太坊经典	18
2	2	LTC	LTC	莱特币	8
2301	2301	QTUM	QTUM	量子链币	8
502	502	GCC	GalaxyChain		8
60	合约地址	eth代币	eth代币		根据代币具体情况而定
144	144	XRP	Ripple	瑞波币	6
194	194	EOS	EOS	柚子币	4
194	194	EOS	EOS	柚子币	4
2304	2304	IOTE	IOTE	IOTE	8
2303	2303	VDS	Vollar	Vollar币	8

回调接口状态说明

状态	说明
0	待审核
1	审核成功
2	审核驳回
3	交易成功
4	交易失败

回调接口交易类型说明

状态	说明
1	充币回调
2	提币回调

验签说明

为了保证商户传送到优盾的参数信息不被恶意篡改，网关为商户接口提供Md5加密摘要认证。商户可用基础加密参数：时间戳、随机数、签名密钥(商户唯一的APIKEY)、请求明文参数按指定顺序排列进行Md5加密，产生一个验签串sign，商户请求网关接口时，带上参数时间戳、随机数、请求明文参数、sign作为参数。网关拿到相应的参数以同样的方式进行签名验签。同理，网关请求商户也以同样的方式进行身份验证。

sign=md5(body + key + nonce + timestamp)

key为接口授权码APIKEY，由网关分配给商户，加密字段顺序不能错误

币种地址校验规则

主币种类型	币种简称	币种英文名称	币种中文名称	地址前缀	地址长度限制区间
0	BTC	Bitcoin	比特币	1或者3	[26,36]
60	ETH	Ethereum	以太坊	0x	[42]
145	BCH	Bitcoincash	比特币现金	1	[26,36]
61	ETC	EthereumClassic	以太坊经典	0x	[42]
2	LTC	Litecoin	莱特币	L或者M	[26,36]
508	GX	GX		G	[26,36]
503	NBTC	NBTC		N	不限制
99	STO	STO	证券型通证发行	S	不限制
5	DASH	DASH	达世币	X	[26,36]
2301	QTUM	QTUM	量子链币	Q	[26,36]
133	ZEC	ZCash	大零币	t1	不限制
144	XRP	Ripple	瑞波币	r	[34]

 

 

加密货币交易平台对接不同的钱包，对应的接口都可能有所不同，在上述接口文档中，具备多币种钱包的参数说明，不仅解决了接口对接怎么实现的问题、展示了对接步骤如何实现的解决方案，更为支付接口如何对接提供了策略，充分解决了接口不同的各种麻烦，实现快速对接交易所平台。