# General

Below is the general information regarding our API URL and the tokens supported.

## API URL <a href="#api-url" id="api-url"></a>

{% hint style="warning" %}
Make sure to use the correct API URL corresponding to the account you are using. To verify, please check your current login URL based on below.

Mainnet: [https://merchant.coinsdo.com](https://merchant.coinsdo.com/) \
Testnet: <https://merchant.coinsdotest.com/>
{% endhint %}

<table><thead><tr><th width="173">Environment</th><th>URL</th></tr></thead><tbody><tr><td>Mainnet </td><td><code>https://open.coinsdo.com/coinsdo/open</code></td></tr><tr><td>Testnet</td><td><code>https://open.coinsdotest.com/coinsdo/open</code></td></tr></tbody></table>

***

## Supported Tokens <a href="#supported-tokens" id="supported-tokens"></a>

Please go to currency control list in your CoinSend/CoinGet center for the most up-to-date list of support tokens and also coinsDoId for making API request.

![](https://3529283920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fbq6zziU9PCtrTYtaegKj%2Fuploads%2FQkmJGuZCpj9ivOMQoPzp%2Fimage.png?alt=media\&token=836f86ad-a1e9-4667-a4c2-9982f579b339)

***

## Get Block Number  <a href="#get-block-number" id="get-block-number"></a>

To retrieve latest block number for all supported networks&#x20;

### **Request**

<mark style="color:green;">`POST`</mark> `/v1/blockNumberGet`<br>

<table data-full-width="false"><thead><tr><th width="121.59375">Parameter</th><th width="118.66796875">Required</th><th width="86.55859375">Type</th><th>Description</th></tr></thead><tbody><tr><td>apiKey</td><td>Yes</td><td>String</td><td>API Key</td></tr><tr><td>timestamp</td><td>Yes</td><td>Integer</td><td>Timestamp (in seconds or milliseconds)</td></tr></tbody></table>

```json
{
    "data": "{\"apiKey\":\"aa465953d55641b3\",\"timestamp\":\"2847982343622\"}",
    "sign": "7639a6a58d8ae74db48db3841f71a21b92e68131529c5e4d72ef4baa6234146b"
}
```

* Data content

<table data-full-width="false"><thead><tr><th width="121.59375">Parameter</th><th width="118.66796875">Required</th><th width="86.55859375">Type</th><th>Description</th></tr></thead><tbody><tr><td>apiKey</td><td>Yes</td><td>String</td><td>API Key</td></tr><tr><td>timestamp</td><td>Yes</td><td>Integer</td><td>Timestamp (in seconds or milliseconds)</td></tr></tbody></table>

### **Response**

**Response example**

```json
{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": {
        "blockNumberList": [
            {
                "currency": "ADA",
                "latestNumber": "4369683",
                "scanNumber": "4369683",
                "active": true,
                "lastScanTime": 1769655690644,
                "safeRange": "60"
            },
            {
                "currency": "ALGO",
                "latestNumber": "55887257",
                "scanNumber": "42367464",
                "active": true,
                "lastScanTime": 1758329493326,
                "safeRange": "60"
            },
            {
                "currency": "ARB1",
                "latestNumber": "237774612",
                "scanNumber": "55797388",
                "active": true,
                "lastScanTime": -1,
                "safeRange": "60"
            },
            {
                "currency": "ARB1_ERC20",
                "latestNumber": "237774612",
                "scanNumber": "55554107",
                "active": true,
                "lastScanTime": -1,
                "safeRange": "60"
            },
            {
                "currency": "ATOM",
                "latestNumber": "15751831",
                "scanNumber": "22760797",
                "active": true,
                "lastScanTime": -1,
                "safeRange": "60"
            },
            {
                "currency": "AVAXC",
                "latestNumber": "51237230",
                "scanNumber": "51237221",
                "active": true,
                "lastScanTime": 1769655722436,
                "safeRange": "60"
            },
            {
                "currency": "AVAXC_ERC20",
                "latestNumber": "51237230",
                "scanNumber": "51237222",
                "active": true,
                "lastScanTime": 1769655723546,
                "safeRange": "60"
            },
            {
                "currency": "BCH",
                "latestNumber": "1695283",
                "scanNumber": "1695283",
                "active": true,
                "lastScanTime": 1769655361665,
                "safeRange": "60"
            },
            {
                "currency": "BNB",
                "latestNumber": "87175235",
                "scanNumber": "72655277",
                "active": true,
                "lastScanTime": 1769655725450,
                "safeRange": "60"
            },
            {
                "currency": "BEP20",
                "latestNumber": "87175235",
                "scanNumber": "69815464",
                "active": true,
                "lastScanTime": 1769655735952,
                "safeRange": "60"
            },
            {
                "currency": "BSV",
                "latestNumber": null,
                "scanNumber": null,
                "active": false,
                "lastScanTime": null,
                "safeRange": null
            },
            {
                "currency": "BTC",
                "latestNumber": "4325100",
                "scanNumber": "4325100",
                "active": true,
                "lastScanTime": 1769655122180,
                "safeRange": "3"
            },
            {
                "currency": "OMNI",
                "latestNumber": null,
                "scanNumber": null,
                "active": false,
                "lastScanTime": null,
                "safeRange": null
            },
            {
                "currency": "DASH",
                "latestNumber": "1410759",
                "scanNumber": "1410759",
                "active": true,
                "lastScanTime": 1769655480937,
                "safeRange": "60"
            },
            {
                "currency": "DOGE",
                "latestNumber": "31944480",
                "scanNumber": "31944306",
                "active": true,
                "lastScanTime": 1769655736382,
                "safeRange": "60"
            }
        ],
        "timestamp": "2026-01-29T03:02:16.407+00:00"
    }
}
```

* Data content

<table data-full-width="false"><thead><tr><th width="121.59375">Parameter</th><th width="118.66796875">Required</th><th width="86.55859375">Type</th><th>Description</th></tr></thead><tbody><tr><td>blockNumberList</td><td>Yes</td><td>Array</td><td>Block height list</td></tr><tr><td>timestamp</td><td>Yes</td><td>String</td><td>Timestamp (in seconds or milliseconds)</td></tr></tbody></table>

* Data content

<table data-full-width="false"><thead><tr><th width="121.59375">Parameter</th><th width="118.66796875">Required</th><th width="86.55859375">Type</th><th>Description</th></tr></thead><tbody><tr><td>currency</td><td>Yes</td><td>String</td><td>Coin name/protocol</td></tr><tr><td>latestNumber</td><td>No</td><td>String</td><td>Latest network block height</td></tr><tr><td>scanNumber</td><td>No</td><td>String</td><td>Block height scanned by CoinsDo</td></tr><tr><td>active</td><td>No</td><td>Boolean</td><td>true - This network is currently being scanned by CoinsDo.<br>false - This network is not currently being scanned by CoinsDo.</td></tr><tr><td>lastScanTime</td><td>No</td><td>Integer</td><td>CoinsDo last scan time</td></tr><tr><td>safeRange</td><td>No</td><td>String</td><td>Safe Range (if the difference between latestNumber and scanNumber is within the safe range value, block scanning is considered normal.)</td></tr></tbody></table>

### **Status code**

{% hint style="info" %}
Below is a general list of status codes, and each API endpoint may have its own differences.
{% endhint %}

<table><thead><tr><th width="114.82421875">Status code</th><th>Description</th></tr></thead><tbody><tr><td>4099</td><td>Too many requests</td></tr></tbody></table>

***

## How to make API request  <a href="#request-api" id="request-api"></a>

Below are the standard rules for making an API request with the CoinsDo Open API.

### **Request parameters**

* Header

<table><thead><tr><th width="129.83723958333331">Parameter</th><th width="90.23046875">Required</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td>Yes</td><td>application/json</td></tr></tbody></table>

* Body&#x20;

<table><thead><tr><th width="110.36328125">Parameter</th><th width="89.98046875">Required</th><th width="79.6796875">Type</th><th>Description</th></tr></thead><tbody><tr><td>sign</td><td>Yes</td><td>string</td><td>Signature</td></tr><tr><td>data</td><td>Yes</td><td>string</td><td>Content（JSON string, depends on each API）</td></tr></tbody></table>

### Signing

Generate the signature by hashing the data using HMAC-SHA256 with the Secret-KEY linked to your API-KEY or merchant account. The resulting hash is the signature.

```
{
        "data": "{\"apiKey\":\"cd384rt80f5575dc\",\"mainnet\":\"TRX\",\"targetDeviceUuid\":\"085C28EC-0BD6-442B-8232-D23BC8F4D58E\",\"timestamp\":\"1622775712229\",\"addressRemark\":\"trx address\"}",
        "sign": "852cd95d5045f3e41db0447cdde405b73cc03b8844b76da74bd0b498470cba75"
}
```

### **Response**

```
{
  "code": 200, // Status code
  "msg": "Success", // Remarks
  "data": null // Response 
}
```

### **Status code**

{% hint style="info" %}
Below is a general list of status codes, and each API endpoint may have its own differences.
{% endhint %}

<table><thead><tr><th width="114.82421875">Status code</th><th>Description</th></tr></thead><tbody><tr><td>-2</td><td>System error</td></tr><tr><td>200</td><td>Success</td></tr><tr><td>4001</td><td>API endpoints not found</td></tr><tr><td>4002</td><td>Parameters in wrong format</td></tr><tr><td>4003</td><td>JSON data conversion abnormal</td></tr><tr><td>4004</td><td>API Key does not exists</td></tr><tr><td>4005</td><td>IP Restricted</td></tr><tr><td>4007</td><td>Signature verification failed</td></tr><tr><td>4010</td><td>Request expired</td></tr><tr><td>4068</td><td>Failed to verify APIKEY</td></tr></tbody></table>

## Webhook notification <a href="#webhook-notification" id="webhook-notification"></a>

Below are the details of the webhook requests are sent from CoinsDo to webhook URL.

### **Request**

<mark style="color:green;">`POST`</mark> `/{webhookURL}`

* Header

<table><thead><tr><th width="130.11848958333331">Parameter</th><th width="99.93359375">Required</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td>Yes</td><td>application/json</td></tr></tbody></table>

* Body

<table><thead><tr><th width="104.9921875">Parameter</th><th width="99.6484375">Required</th><th width="79.89453125">Type</th><th>Description</th></tr></thead><tbody><tr><td>sign</td><td>Yes</td><td>string</td><td>Signature</td></tr><tr><td>data</td><td>Yes</td><td>string</td><td>Content（JSON string）</td></tr></tbody></table>

### **Response**

```
{
  "code": 200, // Status code
  "msg": "Success", // Remarks
  "data": null // Response
}
```

### How you should respond? <a href="#callback-scenario" id="callback-scenario"></a>

This section suggests whether you should respond to the callback.

When you execute, the return code should display 200 if the callback is successful. Once it is successful, there will be no further callbacks.

If you choose to ignore, the return code should display 202 if it is successful. There will be no callbacks (Choosing to ignore is similar to the 200 status in terms of effect. The only difference is whether you want to handle the suggested display).

<table><thead><tr><th width="107.203125">Scenario</th><th width="405">Example</th><th>Suggestion</th></tr></thead><tbody><tr><td>Transfer</td><td>Transfer request on the in CoinSend (success/rejected/cancelled).</td><td>Respond with code 200</td></tr><tr><td>Receive (confirmed by 1 block)</td><td>Transaction confirmed by 1 block.</td><td>Respond with code 200 /ignore</td></tr><tr><td>Receive (confirm by specific number of blocks)</td><td>Target blockchain confirmations have been reached and verified successfully (final status) and credited.</td><td>Respond with code 200 and update </td></tr></tbody></table>