📘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

For webhook request of transfer record upon completion, please refer to Webhook notification section.


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


Withdrawal Record

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
        }
    ]
}

Withdrawal Summary

To check total transfer amount based on network.

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

Last updated

Was this helpful?