API 文档

# 兑换API文档

# 1. 如何获取API Key

  用户登录收银台 -> 开发者中心 -> API Key -> 创建API key。API Key 都有单独的配置页，并绑定固定的 IP 地址（“0.0.0.0”表示不做 IP 拦截过滤，任何IP都可以访问），可配置不同的 API Key 满足不同的需求。请不要泄露您的 Access Key 及 Secret Key，以免造成资产损失。Secret Key 生成后将无法再次查看，请注意及时保存，如您忘记了 Secret Key，请在商户后台回收该密钥对并申请新的密钥对。

# 1.1 如何创建API KEY

• 点击开发者中心-API Key

• 1选择是否开启调试模式 ( 开启调试模式后，你有任何错误会有规范的提示信息和日志查看地址 ）

• 2选择API Key权限

• 3输入白名单地址 (0.0.0.0 表示任意IP地址可以访问)

注：( 输⼊⽩名单域名时应注意多个IP时用","隔离。)

• 4点击创建，可⽣成API KEY

(⽣成API KEY后可以在下⽅我的API KEY列表进⾏复制、查看、编辑和删除等操作，注意Secret key只在生成的时候出现一次，请妥善保存，如您忘记了Secret Key,请回收该密钥对并申请新的密钥对。)

• 点击编辑可关闭或开启【开始调试】及修改API Key权限和白名单地址，修改完成后点击保存即可

注意：创建或编辑API Key之后请耐心等待90秒API Key生效

# 2. 如何使用API Key

当前API Key是在请求的Header中添加参数列表

参数名 参数说明 类型 是否必须
access_key Api Key 访问密钥 （如：TPhoa7ZQ） String 是
timestamp 毫秒级时间戳（13位 如：1679669488472） String 是
nonce UUID（36位 如：02f7a04f-53cc-47d4-bb3f-fae69dab49ac） 五个部分分别为8个字符、4个字符、4个字符、4个字符、12个字符，中间用“-”号间隔 String 是
sign 参数签名 （如：GXx2wYUD6UVr+zcmeCSFFPzcBLA=） String 是

# 3. 技术侧参数接入流程

# 4. 如何接口签名

# 签名说明

  API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保请求未被更改，除公共接口（基础信息，行情数据等）外的私有接口均必须使用您的 API Key 做签名认证，以校验参数或参数值在传输途中是否发生了更改。

一个合法的请求由以下几部分组成：

  • access_key： API 访问密钥；
  • secret_key： 签名加密所使用的密钥（仅在后台申请 API Key 时可见一次，请复制保存在安全处，不可泄露）；
  • timestamp： 您发出请求的时间 (UTC 时间) 。如：1632811287325（13位）。在查询请求中包含此值有助于防止第三方截取您的请求；
  • nonce： 随机 UUID 字符串。如：053a1b81-48a0-4bb1-96b2-60f6e509d911（36位）；
  • sign： 签名计算得出的值，用于确保签名有效和未被篡改；
  • 所有接口都需要在http请求头 （header） 中传递以上除 secret_key 外的几个公共参数，公共参数包含（access_key ，timestamp，nonce，sign）其他涉及到签名参数以API接口说明为准 。

# 签名步骤

​ 1.定义一个 Map 字典类型对象，将请求中的参数以 key-value 的形式放入其中

​ 2.将 access_key、timestamp、nonce 也放入第一步定义的 Map 中

​ 3.将 Map 里面的属性按照 ASCII 码从小到大做升序排序（字典序）并将 Map 转换输出为“key1=value1&key2=value2” 形式的字符串

​ 4.将上一步转换的字符串用 secret_key 进行 HMAC_SHA1 加密并进行 Base64 转码，得到 sign 参数值。secret_key 是在收银平台创建的 apikey 中的信息

​ 5.将 sign 值和其他所需参数加到请求头 header 中，发送请求目标接口

# 签名调试工具

  • SignUtil: 用户登录收银台 -> 开发者中心 -> API 文档 -> 签名工具 打开签名工具页面 (工具中的access_key请使用有效的access_key 并且请设置允许这个access_key访问的IP白名单为 0.0.0.0,我们强烈推荐使用过的access_key调试完成后废弃)

# 5. 接口列表

# 5.1 测试接口连通性

请求方式

Get

请求URL

/ping

响应数据

{"version":"1.0.1","timestamp":1688116827306}

响应参数说明

Param Type Desc
version String 返回该参数则本文档中所有接口都可正常请求
timestamp int64 Unix时间戳

# 5.2 法币兑换加密

请求方式

Post

请求URL

/api/v3/exchange/fiat/to/wallet

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"addressTo": "0x0CBFD17AE9E1d6D881b2CAde71277f48aBf64D24",
	"chainType": "ETH",
	"tokenType": "USDT",
	"currencyAmount": 1,
	"currencyType": "BRL",
	"externalOrderId": "469170783478455217",
	"remark": "123"
}

请求参数说明

Param Desc Require
addressTo 收款地址（String） required
chainType 主链类型（String）oneof=ETH TRON BSC required
tokenType 代币类型 oneof=USDT（String） required
currencyAmount 法币金额不能小于1（String） required
currencyType 法币类型oneof=BRL MXN（String） required
externalOrderId 商户订单ID（String） required
remark 备注 max=255（String） optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"orderId": "OCURREXCH202307180805431689667543340DOCKER020000000200000250",
		"symbolType": "CURRENCY TO TOKEN",
		"externalOrderId": "469170783478455217",
		"currencyType": "BRL",
		"tokenType": null,
		"chainType": "ETH",
		"currencyAmount": 1,
		"tokenAmount": 0.145985
	}
}

响应参数说明

Param Type Desc
orderId String 订单ID
symbolType String 基准类型
externalOrderId String 商户订单ID
currencyType String 法币类型
tokenType String 代币类型
chainType String 主链类型
currencyAmount int64 法币金额
tokenAmount float64 代币金额

# 5.3 查询法币兑换加密订单

请求方式

Post

请求URL

/api/v3/exchange/query/exchange/orderinfo

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"externalOrderId": "469170783478455217",
	"orderId": "OCURREXCH202307180805431689667543340DOCKER020000000200000250"
}

请求参数说明

Param Desc Require
externalOrderId 商户订单号 max=64（String） required
orderId 订单ID（String） required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"tokenAmount": "0.145985",
		"currencyAmount": "1.00",
		"orderAmount": "1",
		"orderActualAmount": null,
		"orderFee": null,
		"orderPayTime": null,
		"orderCompleteTime": null,
		"currencyType": "BRL",
		"tokenType": "USDT",
		"chainType": "ETH",
		"exSymbolType": "CURRENCY TO TOKEN",
		"exchangeRate": "6.85",
		"addressTo": "0x0CBFD17AE9E1d6D881b2CAde71277f48aBf64D24",
		"remark": "123",
		"tradeHash": "",
		"errorMsg": null,
		"errorMsgEn": null,
		"orderId": "OCURREXCH202307180805431689667543340DOCKER020000000200000250",
		"externalOrderId": "469170783478455217",
		"orderStatus": 2
	}
}

响应参数说明

Param Type Desc
tokenAmount String 代币金额
currencyAmount String 法币金额
orderAmount String 订单金额
orderActualAmount float64 订单实际金额
orderFee String 订单手续费
orderPayTime int64 订单支付时间
orderCompleteTime int64 订单完成时间
currencyType String 法币类型
tokenType String 代币类型
chainType String 主链类型
exSymbolType String 基准类型
exchangeRate String 订单生成时汇率
addressTo String 收款地址
remark String 备注
tradeHash String 交易hash
errorMsg String 错误信息
errorMsgEn String 错误信息en
orderId String 订单ID
externalOrderId String 商户订单ID
orderStatus int64 订单状态1-等待支付法币
2-收到法币
4-待收加密货币
8-兑换已完成
32-兑换失败

# 5.4 加密兑换法币

请求方式

Post

请求URL

/api/v3/exchange/wallet/to/fiat

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"tokenAmount": 1010,
	"chainType": "TRON",
	"addressFrom": "TBoG3wMvQhFUYQdcrHF6M3s7TKNHvCdW4w",
	"currencyType": "BRL",
	"tokenType": "USDT",
	"externalOrderId": "2564895864",
	"notifyUrl": "",
	"remark": "TEST"
}

请求参数说明

Param Desc Require
tokenAmount 代币金额（String） required
chainType 主链类型 oneof=TRON（String） required
addressFrom 出款地址（String） required
currencyType 法币类型 oneof=BRL（String） required
tokenType 代币类型 oneof=USDT（String） required
externalOrderId 商户订单ID（String） optional
notifyUrl 通知地址（String） optional
remark 备注（String） optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"orderId": "OCRYPEXCH202310090612161696831936686DEV001OO0000000200000250",
		"symbolType": "TOKEN TO CURRENCY",
		"externalOrderId": "11705714",
		"currencyType": "BRL",
		"tokenType": "USDT",
		"chainType": "TRON",
		"currencyAmount": 5171.2,
		"tokenAmount": 1010,
		"addressTo": "TNZEyuAhvDX1YoHpGPVzD5gBqK7e56tbF5"
	}
}

响应参数说明

Param Type Desc
orderId String 订单ID
symbolType String 基准类型
externalOrderId String 商户订单ID
currencyType String 法币类型
tokenType String 代币类型
chainType String 主链类型
currencyAmount int64 法币金额
tokenAmount float64 代币金额
addressTo String 收款地址

# 5.5 查询加密兑换法币订单

请求方式

Post

请求URL

/api/v3/exchange/query/wallet/exchange/orderinfo

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
	"externalOrderId": "2564895864",
	"orderId": "OCRYPEXCH202310090610471696831847220DEV001OO0000000200000249"
}

请求参数说明

Param Desc Require
externalOrderId 商户订单号 max=64（String） required
orderId 订单ID（String） required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": {
		"tokenAmount": "1010",
		"currencyAmount": "5171.20",
		"orderAmount": "1010",
		"orderActualAmount": null,
		"orderFee": "0",
		"orderPayTime": null,
		"orderCompleteTime": null,
		"currencyType": "BRL",
		"tokenType": "USDT",
		"chainType": "TRON",
		"exSymbolType": "TOKEN TO CURRENCY",
		"exchangeRate": "5.12",
		"addressTo": "TNZEyuAhvDX1YoHpGPVzD5gBqK7e56tbF5",
		"remark": "TEST",
		"notifyUrl": "https://tofficeapi.hambit.io/api/v1/hambit/hambit-operate/testNotify",
		"tradeHash": "",
		"errorMsg": null,
		"errorMsgEn": null,
		"orderId": "OCRYPEXCH202310090610471696831847220DEV001OO0000000200000249",
		"externalOrderId": "33857163",
		"orderStatus": 4
	}
}

响应参数说明

Param Type Desc
tokenAmount String 代币金额
currencyAmount String 法币金额
orderAmount String 订单金额
orderActualAmount float64 订单实际金额
orderFee String 订单手续费
orderPayTime int64 订单支付时间
orderCompleteTime int64 订单完成时间
currencyType String 法币类型
tokenType String 代币类型
chainType String 主链类型
exSymbolType String 基准类型
exchangeRate String 订单生成时汇率
addressTo String 收款地址
remark String 备注
tradeHash String 交易hash
errorMsg String 错误信息
errorMsgEn String 错误信息en
orderId String 订单ID
externalOrderId String 商户订单ID
orderStatus int64 订单状态1-等待支付法币
2-收到法币
4-待收加密货币
8-兑换已完成
32-兑换失败

注意 http响应status_code优先级最高 只要收到响应status_code=200 响应数据则忽略

# 6. 公共响应代码

filed Type Default value and comment
code String 成功"200" 其他请参考失败code
success Bool 成功 true 失败false 和code保持意义上的同步
msg String 一级code返回的文字性描述
data Object 参考接口列表章节

# 7. 失败code

Code Desc
200 正常
300 参数异常
301 IP无权限
307 签名错误
500 系统错误