📘CoinSend

Dispatch/Transfer

To initiate a transfer via API.

Before you proceed

Server sub-account is required to setup API integration. You may refer to guide below on how to create a server sub-account.

https://app.gitbook.com/o/IH18q5jVHaB5yVgZO7Xv/s/bq6zziU9PCtrTYtaegKj/~/changes/124/coinsend/setup/setup-sub-account-and-coinsign

Sub Account Roles

• Submitter – Responsible for creating dispatch records.

• Reviewer – Reviews and approves dispatch records submitted by the Submitter.

• Executor – Determines which CoinSend client and address the the funds will be sent from.

Making a Transfer

Below is the graphical illustration of how transfer works in CoinsDo.

1. End user submits a withdrawal request on the corporate platform.

2. Corporate platform initiates a transfer request via the API.

3. CoinsDo server forwards the request to the Reviewer.

4. The Reviewer approves (signs) and forwards Signature A to the Executor.

5. The Executor approves, selects the CoinSend client and wallet address to use, and forwards both Signatures A and B back to the CoinsDo server.

6. The data and both signatures are forwarded to the selected CoinSend client.

7. The CoinSend client verifies the data and signatures, then executes the transaction.

8. CoinSend client sync transaction status with CoinsDo server.

9. CoinsDo server notify platform via API callback.

Automatic transfer

Corporate can skip 1 of all of the approval process by including either reviewSign (skip 1st-level approval) , or both reviewSign and approveSign (skip both level approval) in the API request parameter to achieve semi or fully automated transfer, as such.

Semi-automated

Fully automated

Request

POST /v1/withdraw

Parameter	Required	Type	Description
data	Yes	string	Content（JSON, refer below）

• Data content

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

Parameter	Required	Type	Description
apiKey	Yes	string	API KEY
submitAccount	Yes	string	Submit account(Client side approval account)
address	Yes	string	Receive address
amount	Yes	string	Receive 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	UUID of the executor's device. This is mandatory if you want to automate 1st-level approval.
reviewSign	No	string	Reviewer signature, generate using RSA-SHA256 algorithm with the following data. This is mandatory if you want to automate 1st-level approval. businessId=<Business ID>&address=<Receive address>&amount=<Receive amount>&coinsDoId=<CoinsDo ID>， ❗ Important： Remove trailing zeros from the decimal places of the receive amount. For eg: 1.010 to 1.01, 1.000 to 1.
reviewRemark	No	string	Reviewer approval remarks
targetDeviceUuid	No	string	UUID of the target CoinSend client from which the funds will be sent. This is mandatory if you want to automate 2nd-level approval.
approveUuid	No	string	UUID of the executor's device. This is mandatory if you want to automate 2nd-level approval.
approveSign	No	string	Executor signature, generate using RSA-SHA256 algorithm with the following data. This is mandatory if you want to automate 2nd-level approval. businessId=<Business ID> & deviceUuid=<CoinSend UUID>
approveRemark	No	string	Executor approval remarks
targetAddrIndex	No	string	Designated send address index, default to 0 if not present. If this parameter is present, approveSign will have to include this parameter to produce signature as such businessId=<Business ID>&deviceUuid=<CoinSend UUID>&targetAddrIndex=<Send address index>

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

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

Parameter	Type	Description
data	string	Content（JSON string，refer below）

• Data content

Parameter	Type	Description
businessId	string	Business ID
withdrawStatus	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	string	Transaction hash
blockNumber	string	Block height
txTime	string	Transaction confirmation timestamp(seconds)
txFee	string	Gas fees
feeSymbol	string	Gas fees unit/symbol
businessScene	string	Business scenario(The data returned from submitting through API)
txMemo	string	On-chain remarks
mainnet	string	mainnet
coinName	string	currency

{
    "txTime": "1661336430",
    "businessId": "0x6305fb61_JDXqh_0_2",
    "mainnet": "TRX",
    "withdrawStatus": "1",
    "txMemo": "0",
    "feeSymbol": "TRX",
    "blockNumber": "29232059",
    "txFee": "8.34196",
    "coinName": "JST",
    "txHash": "b29e917066ed433b5d2753ae07a9b4bd71245509f8f9de51ec5a2e43425f91a8"
}

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

Callback response example

Platform has to return code: 200 otherwise the callback will be considered failed and retry for 5 times. A failed callback can be re-initiated manually from CoinsDo web backend.

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

---

Get device info

To retrieve CoinSend client device information.

Request

POST /v1/deviceDetail

Parameter	Type	Description
data	string	Content（JSON string，refer below）

• Data content

Parameter	Required	Type	Description
apiKey	Yes	string	API KEY
deviceUuid	Yes	string	CoinSend client UUID

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

Request example

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

Response

Parameter	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, refer to content below.

• addressList content

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

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

To add new approval device

Request

POST /v1/reviewAdd

Parameter	Required	Type	Description
data	Yes	string	Content（JSON string，refer below）

• Data content

Parameter	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

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

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

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

Parameter	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

---

Withdraw Record Detail

To view details of withdrawal records

Request

POST /v1/listWithdrawRecordDetail

Parameter	Required	Type	Description
data	Yes	string	Content (JSON string, refer below)

{
    "apiKey": "aa465953d55641b3",
    "businessIdList": "20241125T023627_615, 20241125T013051_799",
    "timestamp": "2847982343622"
}

• Data content

Parameter	Required	Type	Description
apiKey	Yes	string	API Key
businessIdList	Yes	string	Business ID (separate multiple entries with commas)
timestamp	Yes	string	Timestamp (seconds or milliseconds)

Request example

{
    "data": "{\"apiKey\":\"aa465953d55641b3\",\"businessIdList\":\"20241125T023627_615, 20241125T013051_799\",\"timestamp\":\"2847982343622\"}",
    "sign": "22212634c772653e4074347d36040d9c51613c9a827591b12ea5888e6c301fbe"
}

Response

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
        {
            "businessId": "20241125T013051_799",
            "chain": "TRX",
            "currency": "TRX",
            "flag": "TRX",
            "coinsDoId": null,
            "fromAddress": "TUsh9f5waEaHmeKPM1dTKg1DAvPYEktB9L",
            "toAddress": "T9yTVCyAvXpHE4MKji5e6nhZf7RqpxyiSZ",
            "amount": "100",
            "withdrawDeviceUuid": "12DEFEF7-6D5B-4C94-8967-4DEC062B790E",
            "dataApprover": "merchant_child_test2",
            "dataApproveTime": "1732498297",
            "executiveApprover": "merchant_child_test2",
            "executiveApproveTime": "1732498368",
            "withdrawStatus": 6,
            "txHash": "ec10197c20a1be2a3c07f98c3ac62ab11b3243a22849f7a77f7d4215499c6314",
            "txTime": "1732498386",
            "callbackStatus": -1,
            "callbackTime": null,
            "createTime": "1732498257",
            "unsentMsgList": null
        },
        {
            "businessId": "20241125T023627_615",
            "chain": "TRX",
            "currency": "TRX",
            "flag": "TRX",
            "coinsDoId": null,
            "fromAddress": "TUsh9f5waEaHmeKPM1dTKg1DAvPYEktB9L",
            "toAddress": "TQPrt12nsL9Ks7on5LUcG99UUXtFhJDgsK",
            "amount": "50",
            "withdrawDeviceUuid": "12DEFEF7-6D5B-4C94-8967-4DEC062B790E",
            "dataApprover": "merchant_child_test2",
            "dataApproveTime": "1732517994",
            "executiveApprover": "merchant_child_test2",
            "executiveApproveTime": "1732518023",
            "withdrawStatus": 6,
            "txHash": "e54b3c7b5ba6a2e46d7c99e2034578f0f5314644c88126a748e6333c6385bc74",
            "txTime": "1732518048",
            "callbackStatus": -1,
            "callbackTime": null,
            "createTime": "1732502211",
            "unsentMsgList": null
        }
    ]
}

---

Withdraw Statistic

To view details of withdrawal statistic.

Request

POST /v1/withdrawStatistic

Parameter	Required	Type	Description
data	Yes	string	Content (JSON string, refer below)

{
    "apiKey": "7bb52d79e46e47ab",
    "withdrawDeviceUuid": "3FA9B3EE-6275-49F4-8886-13B5A58F32CF",
    "startTime": "1738886400",
    "endTime": "1738943999",
    "timestamp": "1740379248"
}

• Data content

Parameter	Required	Type	Description
apiKey	Yes	string	API Key
withdrawDeviceUuid	Yes	string	CoinSend client UUID
startTime	Yes	string	Start Time (UTC+0 timezone). Query limit: 1 day, must not span multiple days
endTime	Yes	string	End Time (UTC+0 timezone). Query limit: 1 day, must not span multiple days
timestamp	Yes	string	Timestamp (seconds or milliseconds)

Request example

{
    "data":"{\"apiKey\":\"7bb52d79e46e47ab\",\"withdrawDeviceUuid\":\"3FA9B3EE-6275-49F4-8886-13B5A58F32CF\",\"startTime\":\"1738886400\",\"endTime\":\"1738943999\",\"timestamp\":\"1740379248\"}",
    "sign":"03dabf4073bad9d5fcde3b881bba076cae211ac28b11995289740f96f51162a5"
}

Response

{
    "code": 200,
    "msg": "Success",
    "success": true,
    "data": {
        "deviceName": "alpha",
        "deviceRemark": "Pixel 7-5be6",
        "withdrawDeviceUuid": "3FA9B3EE-6275-49F4-8886-13B5A58F32CF",
        "details": [
            {
              "chain": "ADA",
              "currency": "ADA",
              "currencyName": "ADA",
              "flag": "ADA",
              "customName": "ADA",
              "withdrawTotalAmount": 0,
              "balance": 0,
              "lastUpdateTime": null,
              "currencyType": 0
            },
            {
              "chain": "ALGO",
              "currency": "ALGO",
              "currencyName": "ALGO",
              "flag": "ALGO",
              "customName": "ALGO",
              "withdrawTotalAmount": 0,
              "balance": 0,
              "lastUpdateTime": null,
              "currencyType": 0
            }
        ]
    }
}

• Data content

Parameter	Required	Type	Description
deviceName	Yes	string	CoinSend client name
deviceRemark	Yes	string	CoinSend client remark
withdrawDeviceUuid	Yes	string	CoinSend client UUID
details	Yes	array	Array of content (refer to Details content)

• Details content

Parameter	Required	Type	Description
chain	Yes	string	Name of Mainnet
currency	Yes	string	Currency/Protocol
currencyName	Yes	string	Name of the currency
flag	Yes	string	Contract address/Currency
customName	Yes	string	Custom name of the currency
withdrawTotalAmount	Yes	Decimal	Total transfer amount
balance	Yes	Decimal	Balance
lastUpdateTime	No	string	Last update time
currencyType	Yes	Integer	Currency type (0-Native coin, 1-Token)

Response status

Status code	Description
4002	Invalid parameter format
4003	JSON data parsing error
4004	APIKEY does not exist
4005	IP restricted. Current IP:
4007	Signature verification failed
4010	Request expired
4032	Failed to verify wallet
4068	APIKEY validation failed
4099	Too many requests
4116	Selected time exceeds the allowed range
4117	Error querying distribution statistics
4118	Failed to retrieve coin configuration
4119	Failed to retrieve supported coin list
4123	Start time is later than end time
4124	Query time must be within the same day