# 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.

![](/files/19WRTHGXZzq0veAyrjJ1)

***

## 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`

```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)</td></tr></tbody></table>

### **Response**

**Response example**

```json
{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": {
        "blockNumberList": [
            {
                "currency": "ETH",
                "latestNumber": "7054237",
                "scanNumber": "6800272",
                "active": true,
                "lastScanTime": 1679497593762,
                "safeRange": "10"
            },
            {
                "currency": "VET",
                "latestNumber": "0",
                "scanNumber": "0",
                "active": false,
                "lastScanTime": -1,
                "safeRange": "0"
            }
        ],
        "timestamp": "2024-11-11T08:06:04.455+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)</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>Yes</td><td>string</td><td>Latest network block height:<br>1. A long integer in string format<br>2. If the currency is inactive, latestNumber = "0"</td></tr><tr><td>scanNumber</td><td>Yes</td><td>string</td><td>CoinsDo block scan height:<br>1. A long integer in string format<br>2. If the currency is inactive, scanNumber = "0"</td></tr><tr><td>active</td><td>Yes</td><td>boolean</td><td>Used to indicate whether the currency is still active. Inactive or deprecated coins, such as those not participating in CoinsDo block scan, can be excluded from monitoring.<br>true: Active currency<br>false: Inactive currency</td></tr><tr><td>lastScanTime</td><td>Yes</td><td>integer</td><td>Latest block scan time (timestamp in milliseconds):<br>1. If the currency is inactive, lastScanTime = -1<br>2. If the difference between the current time and the latest block scan time is 30 minutes or more, it may be considered abnormal.</td></tr><tr><td>safeRange</td><td>Yes</td><td>string</td><td>Recommended safe gap between the latest block height and the CoinsDo block scan height. If the gap exceeds this safe range, the block scanning process may be considered abnormal.<br>1. A long integer in string format<br>2. If the currency is inactive, safeRange = "0"<br>2. Used together with latestNumber and scanNumber to determine whether block scanning is within the safe range, based on the expression: <code>latestNumber - scanNumber &#x3C;= safeRange</code></td></tr></tbody></table>

### **Abnormal example**

```json
{
  "currency": "BTC",
  "latestNumber": "947123",
  "scanNumber": "947100",
  "active": true,
  "lastScanTime": 1777450338768,
  "safeRange": "3"
}
```

The latest block height is 947123, while the CoinsDo block scan height is 947100, resulting in a gap of 23 blocks. This significantly exceeds the configured safeRange of 3 blocks and should therefore be considered an abnormal condition.

### **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>

***

## Address format validation API  <a href="#get-block-number" id="get-block-number"></a>

Check whether an address is valid and whether it is a contract address.

### **Request**

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

<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)</td></tr><tr><td>address</td><td>Yes</td><td>String</td><td>Address</td></tr><tr><td>chain</td><td>Yes</td><td>String</td><td>Mainnet (for example: BTC, ETH or SOL)</td></tr><tr><td>needContractCheck</td><td>Yes</td><td>Boolean</td><td>true = Checks whether the address is a contract address<br>false = Does not check whether the address is a contract address</td></tr></tbody></table>

```json
{
    "apiKey": "7bb52d79e46e47ab",
    "timestamp": "1744697998",
    "address": "0xdb54c0fe721154a7577321f043ff292711365142",
    "chain": "MATIC",
    "needContractCheck": true
}
```

* 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>address</td><td>Yes</td><td>String</td><td>Coin name/protocol</td></tr><tr><td>isValid</td><td>Yes</td><td>boolean</td><td>true = valid address<br>false = invalid address</td></tr><tr><td>isContract</td><td>Yes</td><td>boolean</td><td>true = contract address<br>false = non-contract address<br>null = Does not check whether the address is a contract address</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>4002</td><td>API key cannot be empty<br>Timestamp cannot be empty<br>Address to be checked cannot be empty<br>Chain cannot be empty<br>needContractCheck cannot be empty<br>Timestamp must be a numeric value<br>needContractCheck must be either true or false</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>HmacSHA256 signature verification failed</td></tr><tr><td>4010</td><td>Request expired</td></tr><tr><td>4050</td><td>Mainnet is not supported at the moment</td></tr><tr><td>4099</td><td>Too many requests</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://coinsdo.gitbook.io/docs/general/coinsdo-open-api/general.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.