優盾錢包API開發接口文檔

1、API 對接注意事項

1.1 字段類型與 body 格式

組裝請求、序列化 body 或處理回調數據時，請嚴格按照接口文檔定義傳入及轉換字段類型。請勿將 Integer、Long 或 Boolean 字段轉換為 String，亦不要依賴程式語言的隱式類型轉換。部分語言或開發環境在類型轉換錯誤時未必會返回明確報錯，但後續邏輯可能無法繼續執行。使用 C 語言對接時，請在序列化前逐項校驗字段類型，並記錄轉換失敗及解析異常。

外層 body 字段的類型為 String，body 內部內容必須是符合接口示例結構的有效 JSON 字符串。需要傳入 JSON 對象或對象數組時，必須保留完整的大括號及方括號。格式不正確時，接口可能返回 B0001。

1.2 EVM 兼容鏈的共用地址規則

UDun Wallet 3.0 對 EVM 兼容鏈採用共用地址機制。同一錢包下，ETH、BNB、POL 等 EVM 兼容鏈共用一個以 0x 開頭的地址。該規則與 2.0 的「每條鏈生成獨立地址」機制不同。

生成地址接口：為任何 EVM 兼容鏈或其代幣生成地址時，mainCoinType 統一傳入 ETH 的主幣編號 60。無需分別傳入 BNB、POL 等鏈的主幣編號。非 EVM 鏈仍按各自的 mainCoinType 傳入。

交易回調及提幣接口：沿用 2.0 的幣種識別方式，必須使用實際的 mainCoinType 和 coinType 區分具體鏈及資產。例如 ETH 的 mainCoinType 為 60，BNB 的 mainCoinType 為 2510。具體數值以「獲取商戶支持的幣種信息」接口返回結果為準。

EVM 代幣：生成地址時，所有基於 EVM 兼容鏈發行的代幣均按共用地址規則處理。USDC.ERC20、USDT.ERC20、USDT.BEP20 及 USDC.BEP20 在調用生成地址接口時，mainCoinType 均傳入 60。調用提幣接口或處理交易回調時，仍須使用實際 mainCoinType 和 coinType 識別對應網絡及代幣。

簡要規則：在 UDun Wallet 3.0 支持的幣種中，EVM 兼容鏈及其代幣在生成地址時統一使用 mainCoinType = 60；BTC、TRX 等非 EVM 鏈按各自的主幣編號傳入。

2、生成地址

2.1 場景說明

請求指定幣種的地址。生成地址前，請確認商戶已建立錢包，且錢包支持該幣種。

2.2 接口詳情

2.2.1 接口地址

2.2.2 參數

2.2.2.1 參數說明

[
    {
     "merchantId":"300015",
     "mainCoinType":60,
     "callUrl":"http://localhost:8080/callBack"
    }
]

2.2.2.2 body參數字段

2.2.2.3 示例

{
    "timestamp": 1535005047,
    "nonce": 10000,
    "sign": "a230def43c1a12b14393880a28d4e005",
    "body": "[{\"merchantId\":\"300015\",\"mainCoinType\":60,\"callUrl\":\"http://localhost:8080/callBack\"}]"
}

2.2.3 返回狀態碼表

2.3 調取示例

2.3.1 成功

{
    "data":{
        "coinType":60,
        "address":"0xbe4e3699cb870bc95365fe04a187dd279a651a58"
    },
    "message":"SUCCESS",
    "code":200
}

2.3.2 失敗

{
    "code": "4101",
    "message": "SIGN_MSG_ERROR"
}

3、發送提幣申請

3.1 場景說明

提幣申請

3.2 接口詳情

3.2.1 接口地址

3.2.2 參數

3.2.2.1 參數說明

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

3.2.2.2 body參數字段

3.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\"}]"
}

3.2.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 接口地址

4.2.2 參數

4.2.2.1 參數說明

{
    "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參數說明

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 接口地址

5.2.2 參數

5.2.2.1 參數說明

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

5.2.2.2 body參數說明

5.2.2.3 示例

{
    "timestamp": 1535005047,
    "nonce": 100000,
    "sign": "e1bee3a417b9c606ba6cedda26db761a",
    "body": "[{\"merchantId\":200000,\"mainCoinType\":\"206\",\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\"}]"
}

5.2.3 返回狀態碼表

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 接口地址

6.2.2 參數

6.2.2.1 參數說明

6.2.2.2 body參數說明

6.2.2.3 示例

{
    "timestamp": 1535005047,
    "nonce": 100000,
    "sign": "e1bee3a417b9c606ba6cedda26db761a",
    "body": "{\"merchantId\":\"200032\",\"showBalance\":true}"
}

6.2.3 返回狀態碼表

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":"" // 幣種log地址
        },
        {
            "name": "ETH", // 幣種別名
            "coinName":"Ethereum", // 幣種全稱
            "symbol":"ETH", // 幣種單位
            "mainCoinType":"60", //主幣種類型
            "coinType":"60", // 幣種類型
            "decimals":"18", // 幣種精度
            "tokenStatus":"0", // 0： 主幣 1：代幣
            "mainSymbol":"ETH", //主幣種單位
            "balance":"0", // 幣種余額 
            "logo":"" // 幣種log地址
        }
    ]
}

6.3.2 失敗

{
    "code":4005,
    "message":"BGS_ILLEGAL_PARAMETER"
}

7、校驗地址是否存在

7.1 場景說明

校驗地址是否為該商戶生成的地址，請求參數及返回結果類型同校驗地址合法性接口類似

7.2 接口詳情

7.2.1 接口地址

7.2.2 參數

7.2.2.1 參數說明

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

7.2.2.2 body參數說明

7.2.2.2 示例

{
    "timestamp": 1535005047,
    "nonce": 100000,
    "sign": "e1bee3a417b9c606ba6cedda26db761a",
    "body": "[{\"merchantId\":200000,\"mainCoinType\":\"206\",\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\"}]"
}

7.2.3 返回狀態碼表

7.3 調取示例

7.3.1 成功

{
    "code":200,
    "message":"SUCCESS"
}

7.3.2 失敗

{
    "code":4165,
    "message":"ILLEGAL_ADDRESS"
}

回調接口狀態說明

回調接口交易類型說明

驗簽說明

為了保證商戶傳送到優盾的參數信息不被惡意篡改， 網關為商戶接口提供Md5加密摘要認證。 商戶可用基礎加密參數： 時間戳、 隨機數、 簽名密鑰、 請求明文參數按指定順序排列進行Md5加密並轉化成小寫， 產生一個驗簽串sign， 商戶請求網關接口時， 帶上參數時間戳、 隨機數、 請求明文參數、 sign作為參數。 網關拿到相應的參數以同樣的方式進行簽名驗簽。 同理， 網關請求商戶也以同樣的方式進行身份驗證。

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

key為簽名密鑰，由網關分配給商戶，加密字段順序不能錯誤