> For the complete documentation index, see [llms.txt](https://support.marscat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.marscat.io/development-guide/frontend-development/api-interface/interface-specification.md).

# Interface Specification

## Permission Level Description

MarsApp API interfaces are divided into levels from Level 0 to Level 8 based on different permission levels. Users at different levels can call different functions. Please note that except for Level 0, access to other levels requires corresponding level official authorization signature authentication. Currently available levels are Level 0 and Level 8, with other level APIs to be continuously iterated.

| Level | Description                                                       | Authentication Requirements                |
| ----- | ----------------------------------------------------------------- | ------------------------------------------ |
| 0     | Public interfaces, no authentication required                     | None                                       |
| 1-8   | Advanced interfaces, require certificate signature authentication | Requires official signature authentication |

API Certificate Description

When accessing Level 1 and above API interfaces, an official authorization certificate must be obtained for signature authentication. The certificate includes:

* MarsApp address
* Validity period
* Authorization level
* API version number

Certificate data must be transmitted in Base64 encoded format.

***

## Request and Response Specifications

Request Parameters

Request parameters are in JSON object format, including the following fields:

| Field     | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| payload   | String | Yes      | Parameter data for calling the API, the specific data structure varies based on the API interface's `cmd`.                                                                                                                                                                                                                                                                                                                                                     |
| messageId | String | Yes      | Message ID, used to distinguish API calls, corresponding to the return parameter. When using `relayx-api`, no need to pay attention to this value.                                                                                                                                                                                                                                                                                                             |
| sign      | Object | No       | <p>Certificate data for specific message certificate authentication. Contains the following fields:<br>- <code>content</code>: Original certificate data, including MarsApp address, validity period, level, version number information, in JSON string format.<br>- <code>signature</code>: Certificate data in Base64 encoded format. For Level 0, the request parameters will not validate the sign, and the sign parameter does not need to be passed.</p> |

Complete request structure:

{% code title="Request example" %}

```json
{
  "payload": { xxxxxx },
  "messageId": "string",
  "sign": {
    "content": "base64-string",
    "signature": "base64-string"
  }
}
```

{% endcode %}

Response Parameters

Response parameters are in JSON object format, including the following fields:

| Field     | Type   | Description                                                                                                                             |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| code      | Int    | Response status code, please refer to the status code table below for details.                                                          |
| cmd       | String | Corresponding API interface method name.                                                                                                |
| messageId | String | Message ID, corresponding to the `messageId` in the request parameters.                                                                 |
| result    | Object | Received callback data, different `methodName` return different data formats. When code is not 200, the `result` field is not returned. |

Complete response structure:

{% code title="Response example" %}

```json
{
    "code": 200,
    "cmd": "",
    "messageId": "0",
    "result": {}
}
```

{% endcode %}

***

## Status Code Table

The following is the status code table for interpreting the status code in the response:

| Code  | Description                                    | Typical Scenarios/Handling Suggestions                |
| ----- | ---------------------------------------------- | ----------------------------------------------------- |
| 200   | Request successful                             | -                                                     |
| 30001 | Request format incorrect or parameters invalid | Check parameter structure and required fields         |
| 30002 | Certificate not provided                       | Level 1+ must pass sign field                         |
| 30003 | Certificate validation abnormal                | Certificate content mismatch/expired/signature error  |
| 30004 | API method does not exist                      | Check cmd name                                        |
| 30005 | Resource not found                             | Check business resources (e.g., account, data)        |
| 30006 | chainId abnormal                               | Check chainList, wallet connection parameters         |
| 30007 | Download failed                                | Check network or target resource availability         |
| 30008 | Self Service already registered                | Cannot register repeatedly                            |
| 30009 | Self Service not registered                    | Need to complete registerService first or in progress |
| 30010 | Exceeds resource limit                         | Reduce data volume, transmit in batches               |
| 30011 | Request timeout                                | Check timeout time                                    |
| 30100 | Abnormal error                                 | Abnormal error, refresh and retry if necessary        |
