# 質押 API

## 準備 <a href="#preparation" id="preparation"></a>

如需使用API，請先登錄網頁端，完成API key的申請，再據此文檔詳情進行開發。

您可以點擊 [这里](https://www.xhash.com/usercenter) 創建API key。

創建成功後，請務必記住以下信息：

* Access Key: API訪問祕鑰
* Private Key: 簽名認證加密所使用的祕鑰（僅申請時可見）

{% hint style="info" %}
每個用戶可以創建20個API key，每個API key可以綁定10個ip地址
{% endhint %}

## 接口地址

<https://stakingapi.xhash.com:18000>

## 簽名認證 <a href="#id-138a6766" id="id-138a6766"></a>

* 所有接口採用私鑰簽名，公鑰驗籤的方式請求
* 請求頭header中攜帶簽名信息，包含如下信息：

```
access_key: 您申請的 API Key 中的 Access Key
sign: 簽名信息，使用MD5withRSA簽名，MD5withRSA(requestBody+timestamp),沒有請求參數，requestBody爲""。
timestamp: 請求時間戳（毫秒）
```

* 所有接口採用post請求，請求參數放入requestBody

<pre><code>如訪問/api/v1/xhash/getUserDailyIncome接口
<strong>header：
</strong>"access_key"："50CEA00402A84BFF9B47CF44A947DA0B"
"sign"："sEm3E4qD8fD7mb54SxJLKajf28gItAkHNjk44QJgrjRqh9XQX6xNMdhsKXSAabcfQ77Mpp/PI6i9hW1XPnfkrLKDlAeaTMXKWxQaRKryzB99p782Re0mRoWFW1iZcvaUFzgb3aY3Oj7/xD0Qz6Y+cg/SZGM6KcTC2IL3PosoWPk="
"timestamp"："1666854104527"

<strong>requestBody：
</strong><strong>{
</strong>    "pageNum": 1,
    "pageSetNum": 10
}
</code></pre>

* 統一返回格式

```
  {
      "code": "",
      "data": object,
      "msg": ""
  }
  
  code="200" 爲操作成功，其餘失敗
```

## Example

{% tabs %}
{% tab title="Java" %}
{% file src="/files/s9UUXFSxNho5erd79bgE" %}

```
String accessKey = "A95B2CFA7B1940B799EFCE792AD...";
String privateKey = "MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAMQzb3GI8fTGUUXaZsZxnLBWnihO9iSua4z7v9tY...";
String url = "https://stakingapi.xhash.com:18000/api/v1/xhash/getUserDailyIncome";

Map<String, Object> requestBody = new HashMap<>();
requestBody.put("pageNum", 1);
requestBody.put("pageSetNum", 10);

String content = new GsonBuilder().serializeNulls().create().toJson(requestBody);

long timestamp = System.currentTimeMillis();
System.out.println(content + timestamp);
String sign = RSACoder.sign((content + timestamp).getBytes(), privateKey);

HttpHeaders httpHeaders = new HttpHeaders();
httpHeaders.add("access_key",accessKey);
httpHeaders.add("timestamp",timestamp + "");
httpHeaders.add("sign",sign);

HttpEntity<String> httpEntity = new HttpEntity<>(content, httpHeaders);
RestTemplate restTemplate = new RestTemplate();
ResponseEntity<String> result = restTemplate.postForEntity(url, httpEntity, String.class);
System.out.println(result);
```

{% endtab %}

{% tab title="Python" %}

```
import requests
from Crypto.PublicKey import RSA
from Crypto.Signature import PKCS1_v1_5
from Crypto.Hash import MD5
import base64
import time
import calendar

url = "https://stakingapi.xhash.com:18000/api/v1/xhash/getUserDailyIncome"
accessKey = "0EDF9F7653344B10808972B287832727..."
privatekey="MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAN7ALyd..."
datajson = '{"pageNum":1,"pageSetNum":10}'
timestamp = str(int(round(calendar.timegm(time.gmtime())*1000)))
data = datajson + (timestamp)

private_keyBytes = base64.b64decode(privatekey)
prikey = RSA.importKey(private_keyBytes)
signer = PKCS1_v1_5.new(prikey)
hash_obj = MD5.new(data.encode('utf-8'))
signtrue = base64.b64encode(signer.sign(hash_obj))
sign = str(signtrue)[2:-1]

headers = {
  'access_key': accessKey,
  'sign': sign,
  'timestamp': timestamp
}
result = requests.post(url, headers=headers, data=datajson)
print(result.text)
```

{% endtab %}

{% tab title="Node" %}

```
const https = require('https');
const crypto = require('crypto');
const accessKey = "0EDF9F7653344B10808972B28C..."
const privateKey = "MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAN7ALyd8Bkx..."

const signer = (json) => {
    const privateKeys = "-----BEGIN PRIVATE KEY-----\n" + privateKey + "\n-----END PRIVATE KEY-----"
    const sign = crypto.createSign('md5');
    sign.update(json);
    return sign.sign(privateKeys, 'base64');
}

const postData = JSON.stringify({
    "pageNum": 1,
    "pageSetNum": 10
})

const timestamp = new Date().valueOf()
const dataJsonStr = `${postData}${timestamp}`
const sign = signer(dataJsonStr)
const options = {
    method: 'POST',
    host: 'stakingapi.xhash.com',
    port: 18000,
    path: '/api/v1/xhash/getUserDailyIncome',
    headers: {
        'access_key': accessKey,
        'sign': sign,
        'timestamp': timestamp
    }
};

var req = https.request(options, (res) => {
    res.setEncoding('utf8');
    res.on('data', (chunk) => {
        console.log(`${chunk}`);
    });
});

req.write(postData);
req.end();
```

{% endtab %}
{% endtabs %}

## 接口詳情

### 獲取用戶餘額和未支付金額

**HTTP request**

`POST /api/v1/xhash/getUserStatus`

**Body 请求参数**\
無

**返回參數**

<table><thead><tr><th></th><th width="108"></th><th width="252"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>clBalance</td><td>number</td><td>共識層餘額</td><td>Gwei</td></tr><tr><td>waitPayment</td><td>number</td><td>執行層待支付餘額</td><td>Gwei</td></tr></tbody></table>

**返回示例**

```
{
  "code": "200",
  "data": {
    "clBalance": 1446286721091,
    "waitPayment": 1596525011
  },
  "msg": "Success"
}
```

### 獲取用戶詳情

**HTTP request**

`POST /api/v1/xhash/getUserDetailStatus`

**Body 请求参数**\
無

**返回參數**

<table><thead><tr><th width="241"></th><th width="108"></th><th width="252"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>validatorsOnline</td><td>int</td><td>驗證者在線數量</td><td></td></tr><tr><td>validatorsOffline</td><td>int</td><td>驗證者離線數量</td><td></td></tr><tr><td>totalBalance</td><td>string</td><td>共識層總餘額</td><td>Gwei</td></tr><tr><td>totalChange</td><td>string</td><td>執行層+共識層 總收益</td><td>Gwei</td></tr><tr><td>hoursIncome24</td><td>string</td><td>執行層+共識層 24小時收益</td><td>Gwei</td></tr><tr><td>partailWithdrawalsAmount</td><td>number</td><td>共識層總提取</td><td>Gwei</td></tr><tr><td>waitPayment</td><td>string</td><td>執行層待支付</td><td>Gwei</td></tr><tr><td>pendingPayment</td><td>string</td><td>執行層支付中</td><td>Gwei</td></tr><tr><td>paid</td><td>string</td><td>執行層已支付</td><td>Gwei</td></tr><tr><td>avgRealApr</td><td>float</td><td>所有驗證者平均年化</td><td></td></tr></tbody></table>

**返回示例**

```
{
    "code": "200",
    "data": {
        "validatorsOnline": 45,
        "validatorsOffline": 0,
        "totalBalance": "1440081374281",
        "totalChange": "48615375055.435027176",
        "hoursIncome24": "236051566.84745468",
        "partailWithdrawalsAmount": 35685091263,
        "waitPayment": "400428103.199571345",
        "pendingPayment": "0",
        "paid": "13441757945.295420862",
        "avgRealApr": 0.05681605041
    },
    "msg": "Success"
}
```

### 獲取用戶每日收益

**HTTP request**

`POST /api/v1/xhash/getUserDailyIncome`

**Body 请求参数**

<table><thead><tr><th width="149"></th><th width="124"></th><th></th><th width="117"></th><th width="192"></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>是否必填</strong></td><td><strong>默認值</strong></td><td><strong>描述</strong></td></tr><tr><td>pageNum</td><td>int</td><td>true</td><td>-</td><td>頁數</td></tr><tr><td>pageSetNum</td><td>int</td><td>true</td><td>-</td><td>每頁條數</td></tr></tbody></table>

**返回參數**

<table><thead><tr><th></th><th width="116"></th><th width="296"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>userId</td><td>int</td><td>用戶id</td><td></td></tr><tr><td>totalReward</td><td>float</td><td>總收益</td><td>Eth</td></tr><tr><td>clReward</td><td>float</td><td>共識層收益</td><td>Eth</td></tr><tr><td>elReward</td><td>float</td><td>執行層收益</td><td>Eth</td></tr><tr><td>mevReward</td><td>float</td><td>執行層MEV收益</td><td>Eth</td></tr><tr><td>txReward</td><td>float</td><td>執行層手續費收益</td><td>Eth</td></tr><tr><td>rewardDay</td><td>int</td><td>收益日期</td><td>second</td></tr><tr><td>validatorNum</td><td>int</td><td>當日產生收益的驗證者數量</td><td></td></tr><tr><td>total</td><td>int</td><td>記錄總條數</td><td></td></tr></tbody></table>

**返回示例**

```
{
  "code": "200",
  "data": {
    "pageNum": 1,
    "pageData": [
      {
        "userId": 123456,
        "totalReward": 0.15852195658793655,
        "clReward": 0.142707974,
        "elReward": 0.01581398258793658,
        "mevReward": 0.001352162267224239,
        "txReward": 0.014461820320712356,
        "rewardDay": 1666569600,
        "validatorNum": 2
      },
      ...
      ...
    ],
    "total": 27
  },
  "msg": "Success"
}
```

### 獲取用戶支付歷史記錄

**HTTP Request**

`POST /api/v1/xhash/getUserPaymentHistory`

**Body 请求参数**

<table><thead><tr><th width="149"></th><th width="124"></th><th></th><th width="117"></th><th width="192"></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>是否必填</strong></td><td><strong>默認值</strong></td><td><strong>描述</strong></td></tr><tr><td>pageNum</td><td>int</td><td>true</td><td>-</td><td>頁數</td></tr><tr><td>pageSetNum</td><td>int</td><td>true</td><td>-</td><td>每頁條數</td></tr></tbody></table>

**返回參數**

<table><thead><tr><th></th><th width="116"></th><th width="296"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>userId</td><td>int</td><td>user ID</td><td></td></tr><tr><td>realAmount</td><td>float</td><td>payment amount</td><td>Eth</td></tr><tr><td>chainAmount</td><td>float</td><td>execution-layer amount on chain</td><td>Eth</td></tr><tr><td>withHoldTxFee</td><td>float</td><td>tx fee withholding</td><td>Eth</td></tr><tr><td>realTxFee</td><td>float</td><td>tx fee on chain</td><td>Eth</td></tr><tr><td>retained</td><td>float</td><td>tx feen retained</td><td>Eth</td></tr><tr><td>txHash</td><td>string</td><td>tx hash on chain</td><td></td></tr><tr><td>status</td><td>int</td><td>payment status</td><td>0:paying, 1:finished</td></tr><tr><td>chainTime</td><td>int </td><td>the time on chain</td><td></td></tr><tr><td>updateTime</td><td>int </td><td>payment update time</td><td></td></tr><tr><td>total</td><td>int</td><td>number of all rewards</td><td></td></tr></tbody></table>

**返回示例**

```
{
  "code": "200",
  "data": {
    "pageNum": 1,
    "pageData": [
      {
        "userId": 123456,
        "realAmount": 0.148897612,
        "chainAmount": 0,
        "withHoldTxFee": 0.148897612,
        "realTxFee": 0,
        "retained": 0,
        "txHash": "",
        "status": 0,
        "chainTime": 0,
        "updateTime": 1666842847
      }
    ],
    "total": 1
  },
  "msg": "Success"
}
```

### 獲取用戶驗證者列表

**HTTP Request**

`POST /api/v1/xhash/getUserValidatorList`

**Body 请求参数**

<table><thead><tr><th width="149"></th><th width="124"></th><th></th><th width="117"></th><th width="192"></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>是否必填</strong></td><td><strong>默認值</strong></td><td><strong>描述</strong></td></tr><tr><td>pageNum</td><td>int</td><td>true</td><td>-</td><td>頁數 [1,...]</td></tr><tr><td>pageSetNum</td><td>int</td><td>true</td><td>-</td><td>每頁條數 [10,100]</td></tr></tbody></table>

**返回參數**

<table><thead><tr><th width="211"></th><th width="116"></th><th width="296"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>id</td><td>int</td><td>sequence id</td><td></td></tr><tr><td>userId</td><td>int</td><td>user ID</td><td></td></tr><tr><td>validatorIndex</td><td>int</td><td>validator index</td><td></td></tr><tr><td>validatorPublicKey</td><td>string</td><td>validator publicKey</td><td></td></tr><tr><td>totalIncome</td><td>int</td><td>consensus-layer income</td><td>Gwei</td></tr><tr><td>effectiveBalance</td><td>int</td><td>consensus-layer effective balance</td><td>Gwei</td></tr><tr><td>finalizedBalance</td><td>int</td><td>consensus-layer finalized balance </td><td>Gwei</td></tr><tr><td>currentBalance</td><td>int</td><td>consensus-layer balance </td><td>Gwei</td></tr><tr><td>currentEffectiveness</td><td>string</td><td>effectiveness</td><td></td></tr><tr><td>apr</td><td>float</td><td>apr by 7 day</td><td></td></tr><tr><td>node_status</td><td>string</td><td>validator status in xhash</td><td></td></tr><tr><td>chain_status</td><td>string</td><td>consensus-layer status</td><td></td></tr><tr><td>created_time</td><td></td><td>timestamp in xhash</td><td>second</td></tr><tr><td>total</td><td>int</td><td>number of all rewards</td><td></td></tr></tbody></table>

**返回示例**

```
{
  "code": "200",
  "data": {
    "pageNum": 1,
    "pageData": [
      {
        "id": 45,
        "userId": 123456,
        "validatorIndex": 429489,
        "validatorPublicKey": "0x827b58e886b0024022120a549a7a50bc2b44b51e0d09663d5f543c17fba3f2ec3faf30126979241d0fd1297838de74d8",
        "totalIncome": 118681206,
        "effectiveBalance": 32000000000,
        "finalizedBalance": 32118648446,
        "currentBalance": 32118648446,
        "currentEffectiveness": 99.01,
        "apr": 0.03623521,
        "node_status": "Active",
        "chain_status": "Active",
        "created_time": 1663310642
      },
      ...
      ...
    ],
    "total": 45
  },
  "msg": "Success"
}
```

### 獲取共識層提幣歷史記錄

**HTTP Request**

`POST /api/v1/xhash/getUserPartailWithdrawals`

**Body 请求参数**

<table><thead><tr><th width="149"></th><th width="124"></th><th></th><th width="117"></th><th width="192"></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>是否必填</strong></td><td><strong>默認值</strong></td><td><strong>描述</strong></td></tr><tr><td>pageNum</td><td>int</td><td>true</td><td>-</td><td>頁數 [1,...]</td></tr><tr><td>pageSetNum</td><td>int</td><td>true</td><td>-</td><td>每頁條數 [10,100]</td></tr></tbody></table>

**返回參數**

<table><thead><tr><th width="211"></th><th width="116"></th><th width="296"></th><th></th></tr></thead><tbody><tr><td><strong>參數名</strong></td><td><strong>数据類型</strong></td><td><strong>描述</strong></td><td><strong>備註</strong></td></tr><tr><td>id</td><td>int</td><td></td><td></td></tr><tr><td>userId</td><td>int</td><td>用戶id</td><td></td></tr><tr><td>validatorIndex</td><td>int</td><td>validator index</td><td></td></tr><tr><td>validatorPublicKey</td><td>string</td><td>validator publicKey</td><td></td></tr><tr><td>blockSlot</td><td>int</td><td>slot</td><td></td></tr><tr><td>withdrawalIndex</td><td>int</td><td>withdrawal Index</td><td></td></tr><tr><td>address</td><td>string</td><td>共识层提取地址 </td><td></td></tr><tr><td>amount</td><td>float</td><td>共识层提取金额</td><td>eth</td></tr><tr><td>createdTime</td><td>long</td><td>时间戳，秒</td><td></td></tr></tbody></table>

**返回示例**

```
{
    "code": "200",
    "data": {
        "pageNum": 1,
        "pageData": [
            {
                "id": 0,
                "userId": 101527,
                "validatorIndex": 429481,
                "validatorPublicKey": "0xac34188ca2c6ec29e40534229698d38fc733908c34eeecd77df0f477481344b10fcebbabbb9cc233a09390d1afb6121d",
                "blockSlot": 6281691,
                "withdrawalIndex": 1122084,
                "address": "0x0708f87a089a91c65d48721aa941084648562287",
                "amount": "0.012279707",
                "createdTime": 1682204315
            },
            ...
            ...
        ],
        "total": 135
    },
    "msg": "Success"
}
```

## 錯誤碼

<table><thead><tr><th width="284"></th><th></th></tr></thead><tbody><tr><td><strong>code</strong></td><td><strong>message</strong></td></tr><tr><td>200</td><td>Success</td></tr><tr><td>400</td><td>Param error</td></tr><tr><td>401</td><td>Authentication failed</td></tr><tr><td>403</td><td>Ip not on whitelist</td></tr><tr><td>404</td><td>Path Not Found</td></tr><tr><td>405</td><td>Request timestamp expire</td></tr><tr><td>429</td><td>Requests has exceeded the per second limit</td></tr><tr><td>500</td><td>Server error</td></tr><tr><td>4001</td><td>Select user balance failed</td></tr><tr><td>4002</td><td>Page invalid</td></tr><tr><td>4003</td><td>Select user reward failed</td></tr><tr><td>4004</td><td>Select user payments history failed</td></tr><tr><td>4005</td><td>Select validator list failed</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://docs.xhash.com/cn/staking/zhi-ya-api.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.