📘CoinSend

Dispatch/Withdrawal

Roles

• Data Submitter: This permission grants sub-accounts the ability to create a dispatch record.

• Data Approver: This permission grants sub-accounts the ability to approve the data submitted by the data submitter in the dispatch record. The sub-account with data approval permission (first approver) will verify the data, including business ID, sending address, sending amount, token type, and associated flag.

• Execution Approver: This permission grants sub-accounts the ability to execute the dispatch record created by the data submitter and approved by the data approver. The sub-account with execution approval permission (second approver) will verify the data's business ID and select the dispatching wallet for execution.

Manual withdraw

The corporate entity can execute an automated withdrawal through the CoinsDo API. To do this, the corporate entity can assign the required roles (data submitter, data approval, execution approval) to a server-based sub-account.

Another approach to semi-automate the dispatch process is by assigning specific roles to a server-based account while allowing other general accounts to handle different roles. For instance, the server-based account can automatically create a dispatch record, while sub-accounts with data approval and execution approval permissions will manually approve the record.

1. A corporate user initiates a withdrawal.

2. The corporate business's server uses the CoinsDo API to request a dispatch.

3. Corporate's appointed approver A signs the data submitted in the dispatch record.

4. Corporate's appointed approver B signs the data in the dispatch record and submits the final dispatch record with both approvers' signatures to CoinDo's server.

5. Upon receiving the signed dispatch record, CoinDo's server submits the data to the corporate dispatching wallet through the CoinsDo API.

6. The corporate dispatching wallet verifies both approvers' signatures before executing the dispatch request.

Automatic withdraw

Enterprises can utilize the CoinsDo API for automatic issuance. To implement an automatic issuance plan, the enterprise needs to assign submission data, data approval, and execution approval permissions to a server account.

Additionally, the enterprise can assign certain automatic issuance processes to both server and regular accounts. For instance, the server account can automatically create an issuance record, while the other two regular accounts can manually approve the data and execute the approval for that specific issuance record.

1. A corporate user initiates a withdrawal.

2. The corporate business's server uses the CoinsDo API to request a dispatch and signs the data before sending it to CoinsDo's server.

3. Upon receiving the signed dispatch record, CoinsDo's server submits the data to the CoinSend through CoinsDo's API.

4. CoinSend verifies both signatures before executing the dispatch request.

Access points

• Execute a dispatch request

Address request

• {URL}/v1/withdraw

Request method

• POST

Request parameters

• Body parameters

Name of parameters	Required	Type	Description
data	Yes	string	Content（JSON, refer below）

{
    "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 parameters

Name of parameters	Required	Type	Description
apiKey	Yes	string	API KEY
submitAccount	Yes	string	Submit account(Client side approval account)
address	Yes	string	Dispatch address
amount	Yes	string	Dispatch amount
coinsDoId	Yes	string	CoinsDoID (refer to currency control)
businessId	Yes	string	Business ID (cannot be repeated)
businessScene	No	string	Business scenario
timestamp	Yes	string	Timestamp (seconds or milliseconds)
txMemo	No	string	On-chain remarks (XRP and EOS tag can insert here)
reviewUuid	No	string	Reviewer (first approver) device UUID (Data section must be filled for approved transaction)
reviewSign	No	string	Reviewer (first approver) signature (Data section must be filled for approved transaction) To undergo RSA-SHA256 signing: businessId=business ID&address=address&amount=amount&coinsDoId=coinsDoId，❗ Important：Remove the trailing zero for the amount. For example: Convert 1.010 to 1.01. Convert 1.000 to 1.
reviewRemark	No	string	Reviewer(first approver) remarks
targetDeviceUuid	No	string	Executor (second approver) decides on the targeted CoinSend client (Data section must be filled for approved transaction)
approveUuid	No	string	Executor (second approver) device UUID (Data section must be filled for approved transaction)
approveSign	No	string	Executor (second approver) signature (Data section must be filled for approved transaction. To sign using RSA-SHA256, businessId=Business ID&deviceUuid=CoinSend client UUID)&targetAddrIndex=specify sending address index number)
approveRemark	No	string	Executor (second approver) remarks

Request Example

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

Response example

{
  "code": 200, // State code
  "msg": "Success", // Response message
  "data": null // Response data
}

Response status

Status code	Description
4006	Currently do not support the tokens dispatched
4008	Business ID already exists
4009	Failed to add new dispatch record
4011	Failed to verify device for approval
4012	Data approver's (first approver) device does not exists
4013	Approval device not bound to approval account
4014	Data approver's (first approver) signature verification failed
4015	Authorization code verification failed
4016	Authorization code expired or does not exists
4017	Device verification failed
4018	Ading new approval device failed
4019	Signature verification through SHA256 with RSA failed
4020	Corporate sub-account could not be found
4021	Does not have data submission rights
4022	Does not have data approver (first approver) rights
4023	Exceeded token’s largest decimal
4024	Incomplete parameters found for execution approver (first approver)
4025	Wrong format for dispatch address
4026	Incomplete parameters found for execution approver (second approver)
4027	Device does not exists for execution approver (second approver)
4028	Failed to verify execution approver (second approver)’s signature
4029	Does not have the rights to do execution approval (second approval)
4030	Dispatch amount exceeded the limit designated for your role as the data approver (first approver)
4031	Dispatch amount exceeded the limit designated for your role as the execution approver (second approver)
4032	Failed to verify wallet
4033	Wallet does not exists
4038	Failed to verify dispatch address
4039	Withdrawal account has been deactivated
4040	Data approver (first approver)’s bound device has been deactivated
4041	Execution approver (second approver)’s bound device has been deactivated
4046	Failed to verify whitelisted dispatch address
4047	Dispatch address not found amongst the whitelist
4048	Dispatch amount is less than the minimum required amount
4049	Data submitter account does not belong to an API account
4056	The approval device associate with the data approval account does have the required permission. Contact your merchant account holder to assign permission for this account
4057	The approval device associated with the execution approval account does have the required permission. Contact your merchant account holder to assign permission for this account
4065	Failed to verify business ID
4066	Failed to verify supported tokens
4067	CoinsDoId must be a whole number
4069	Sub account does not exists
4070	Select a coin

Callback notice

Name of parameters	Required	Type	Description
data	Yes	string	Content（JSON string，refer below）

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

Name of parameters	Required	Type	Description
businessId	Yes	string	Business ID
withdrawStatus	Yes	string	Dispatch status (1. Dispatch successfully 2. Dispatch rejected 5. Dispatch cancelled) Able to extend word length, will include more state callback in the future
txHash	No	string	Transaction hash
blockNumber	No	string	Block height
txTime	No	string	Transaction confirmation timestamp(seconds)
txFee	No	string	Gas fees
feeSymbol	No	string	Gas fees unit/symbol
businessScene	No	string	Business scenario(The data returned from submitting through API)
txMemo	No	string	On-chain remarks
mainnet	Yes	string	mainnet
coinName	Yes	string	currency

Request example

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

Response example

{
  "code": 200, // State code
  "msg": "Success", // Remarks
  "data": {
    "businessId": "TRX_999"
  }
}

Get device info

Endpoint description

• Retrieve information from CoinSend client.

Request URL

• {URL}/v1/deviceDetail

Request method

• POST

• Body parameter

Name of parameters	Required	Type	Description
data	Yes	string	Content（JSON string，refer below）

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

• data parameter

Name of parameters	Required	Type	Description
apiKey	Yes	string	API KEY
deviceUuid	Yes	string	CoinSend client UUID

Request example

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

Response example

{
  "code": 200, // State code
  "msg": "成功", // Remarks
  "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"
  }
}

• data parameter

Name of parameters	Required	Type	Description
onlineStatus	Yes	string	Online status (0: offline 1: online)
useStatus	Yes	string	Use status (0: stopped 1: In Use)
devicePublicKey	Yes	string	Wallet's public key
deviceRegisterTime	Yes	string	Timestamp when you register wallet (seconds)
deviceExpiryTime	Yes	string	Timestamp of wallet’s expiry (seconds)
addressList	No	array	List of sending addresses

• Address List parameter

Name of parameters	Required	Type	Description
currency	Yes	string	Token/currency
flag	Yes	string	Contract address/Token ID
address	Yes	string	Wallet's sending address
balance	No	string	Balance in address

Response status

Status code	Description
4032	Failed to verify wallet
4033	Wallet does not exists
4034	Failed to verify address
4035	Failed to verify token
4036	Failed to verify the balance
4037	Failed to verify the wallet’s network status

Adding a new approval device

Endpoint description

• Adding a new approval device

Request URL

• {URL}/v1/reviewAdd

Request method

• POST

• Body parameter

Name of parameters	Required	Type	Description
data	Yes	string	Content（JSON string，refer below）

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

• Data parameter

Name of parameters	Required	Type	Description
apiKey	Yes	string	API Key
reviewPubkey	Yes	string	Verify device’s public key
plainText	Yes	string	String to be verified
signature	Yes	string	Signature (Signs plainText using SHA256 with RSA)
authorizationCode	Yes	string	Device’s authorization code

Request example

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

Response example

{
  "code": 200, // State code
  "msg": "Success", // Remarks
  "data": {
    "uuid": "2DEA1BEB-CFE9-4E1D-9D88-F983D84D2E4W"
  }
}

• Data parameter

Name of parameters	Required	Type	Description
uuid	Yes	string	Authorization device’s uuid

Response status

Status code	Description
4015	Failed to verify authorization code
4016	The authorization code does not exist or has expired
4018	Failed to add new authorization device
4019	Failed to sign through SHA256 with RSA