UDun Wallet API development interface document

1、API Integration Notes

1.1 Field Types and body Format

When building requests, serializing the body field, or processing callback data, preserve each field type exactly as defined in the API documentation. Do not convert Integer, Long, or Boolean fields to String, and do not rely on implicit type conversion. Some languages and development environments may not raise a clear error when a conversion fails, but the subsequent logic may not execute. For C integrations, validate every field type before serialization and log conversion or parsing failures.

The outer body field is a String. Its contents must be a valid JSON string that follows the object or array structure shown in the relevant API example. Keep all required braces and brackets. An incorrectly formatted body may return error code B0001.

1.2 Shared Address Rules for EVM-Compatible Networks

UDun Wallet 3.0 uses a shared-address model for EVM-compatible networks. Within the same wallet, networks such as Ethereum, BNB Smart Chain, and Polygon share one address beginning with 0x. This differs from UDun Wallet 2.0, where each network used a separate address.

Generate Address API: When generating an address for any EVM-compatible network or token, always set mainCoinType to 60, the main coin type for Ethereum. Do not use the individual main coin type for BNB Smart Chain, Polygon, or another EVM-compatible network. For non-EVM networks, use the corresponding mainCoinType.

Transaction Callback and Withdrawal APIs: Continue to use the actual mainCoinType and coinType to identify the specific network and asset. For example, Ethereum uses mainCoinType 60, while BNB uses mainCoinType 2510. Refer to the Get Supported Assets API response for the applicable values.

EVM Tokens: The shared-address rule also applies to tokens issued on EVM-compatible networks. When calling the Generate Address API, set mainCoinType to 60 for USDC.ERC20, USDT.ERC20, USDT.BEP20, USDC.BEP20, and other supported EVM tokens. For withdrawals and transaction callbacks, use the actual mainCoinType and coinType for the relevant network and token.

Summary: For all supported EVM-compatible networks and tokens, use mainCoinType = 60 when generating an address. For non-EVM networks such as Bitcoin and TRON, use the network-specific main coin type.

2、Generate addresses

2.1 Scenario description

Requests an address for a specified asset. Before generating an address, make sure the merchant has created a wallet and the wallet supports the asset.

2.2 Interface details

2.2.1 Interface addresses

2.2.2 Parameters

2.2.2.1 Parameter description

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

2.2.2.2 Body parameter field

2.2.2.3 Examples

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

2.2.3 Return to status code

2.3 Call examples

2.3.1 Success

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

2.3.2 Failure

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

3、Send withdrawal application

3.1 Scenario description

Withdrawal application

3.2 Interface details

3.2.1 Interface addresses

3.2.2 Parameters

3.2.2.1 Parameter description

[
    {
        "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 parameter field

3.2.2.3 Examples

{
  "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 Return to status code

3.3.1 Success

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

3.3.2 Failure

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

4、Payment on behalf

4.1 Scenario description

Withdrawal. It works the same as the withdrawal interface. You can directly use the withdrawal interface, and this interface can be ignored.。

4.2 Interface details

4.2.1 Interface addresses

4.2.2 Parameters

4.2.2.1 Parameter description

[
  {
      "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 parameter description

4.2.2.2 Examples

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

4.2.3 Return to status code

4.3 Call examples

4.3.1 Success

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

4.3.2 Failure

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

5、Trade callback interface

5.1 Scenario description

The gateway receives the transaction processing result and calls the callback interface provided by the merchant to notify the merchant of the specific change information. The interface gateway sends you the content of the callback address specified by you to process your business information. There are callbacks for deposit and withdrawal, of which up to two callbacks will be made for withdrawals (audit callback and transaction result callback)

5.2 Interface details

5.2.1 Interface addresses

5.2.2 Parameters

5.2.2.1 Parameter description

{
    "address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW",
    "amount":"12345678",
    "blockHigh":"102419",
    "coinType":"206",
    "decimals":"8",
    "fee":"452000",
    "mainCoinType":"206",
    "status":3,
    "tradeId":"20181024175416907",
    "tradeType":1,
    "txId":"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0",
    "businessId":"",// The coin withdrawal callback is the business id passed from the coin withdrawal interface, and the coin has no value.
    "memo":""
}

4.2.2.2 Body parameter description

5.2.2.2 Examples

{
    "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\"}"
}

6、Verify address legality

6.1 Scenario description

Check the legality of the address. You can check the legality of the address first when adding addresses, withdrawing coins and other scenarios, see Verification rule

6.2 Interface details

6.2.1 Interface addresses

6.2.2 Parameters

6.2.2.1 Parameter description

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

5.2.2.2 Body parameter description

6.2.2.3 Examples

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

6.2.3 Return to status code

6.3 Call examples

6.3.1 Success

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

6.3.2 Failure

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

7、Obtain the information of tokens supported by merchants

7.1 Scenario description

Obtain the tokens supported by merchants and the balance

7.2 Interface details

7.2.1 Interface addresses

7.2.2 Parameters

7.2.2.1 Parameter description

6.2.2.2 Body parameter description

7.2.2.3 Examples

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

7.2.3 Return to status code

7.3 Call examples

7.3.1 Success

{
    "code": 200,
    "message": "SUCCESS",
    "data":[
        {
            "name": "BTC", Coin alias
            "coinName":"Bitcoin", Full name of the coin
            "symbol":"BTC", Coin unit
            "mainCoinType":"0", Main coin type
            "coinType":"0", Coin type
            "decimals":"8", Coin precision
            "tokenStatus":"0", 0: Main coin 1:Token
            "mainSymbol":"BTC", Main coin unit
            "balance":"0", Balance 
            "logo":"" Coin log address
        },
        {
            "name": "ETH", Coin alias
            "coinName":"Ethereum", Full name of the coin
            "symbol":"ETH", Coin unit
            "mainCoinType":"60", Main coin type
            "coinType":"60", Coin type
            "decimals":"18", Coin precision
            "tokenStatus":"0", 0: Main coin 1:Token
            "mainSymbol":"ETH", Main coin unit
            "balance":"0", Balance 
            "logo":"" Coin log address
        }
    ]
}

7.3.2 Failure

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