# API Reference

This page documents the DataDID HTTP APIs directly, including user login & authentication APIs, and DID creation related APIs. If you'd rather not call these endpoints yourself, the [SDK](https://memolabs.gitbook.io/datadid-developer-platform-v2/en/sdk) wraps them for you in JavaScript, TypeScript, and Python.

## User Login & Authentication API

**Base URL**

* **Production**: `https://data-api.memolabs.net` — all examples use this, e.g. `POST https://data-api.memolabs.net/v2/login/email`
* **Test**: `https://testdata-api.memolabs.net` — for integration/testing only; data may be reset

***

### 1. Send Email Verification Code

#### POST /v2/login/email/code

* **Description**: Send a login verification code to the given email.
* **Request body** (JSON):
  * `email` (string): User email
* **Response** (JSON):
  * `result` (int): 1 for success, otherwise failure
  * `message` (string): Message
* **Example**:

```json
POST /v2/login/email/code
{
  "email": "user@example.com"
}
```

***

### 2. Email Verification Code Login

#### POST /v2/login/email

* **Description**: Log in with email and verification code.
* **Request body** (JSON):
  * `email` (string): User email
  * `code` (string): Email verification code
  * `source` (string): Source identifier (e.g. Web, App)
  * `useragent` (string, optional): Client User-Agent
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token
* **Example**:

```json
POST /v2/login/email
{
  "email": "user@example.com",
  "code": "123456",
  "source": "Web"
}
```

***

### 3. Telegram Login

#### POST /v2/login/telegram

* **Description**: Log in with Telegram init data.
* **Request body** (JSON):
  * `initdata` (string): Telegram init data
  * `source` (string): Source identifier
  * `useragent` (string, optional): Client User-Agent
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token

***

### 4. Pi Login

#### POST /v2/login/pi

* **Description**: Log in with Pi browser access token.
* **Headers**:
  * `Authorization: <Pi Access Token>`
* **Request body** (JSON):
  * `source` (string): Source identifier
  * `useragent` (string, optional): Client User-Agent
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token

***

### 5. Refresh Token

#### POST /v2/login/refresh

* **Description**: Get a new access token using the refresh token.
* **Headers**:
  * `Authorization: <Refresh Token>`
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `accessToken` (string): New access token

***

### Verify Current User / Get Current User Info

#### GET /v2/auth/me

* **Description**: Validates the request's access token and returns the current user's basic info. Use this to confirm login state and get user UID, email, username, and role. `role` is derived server-side from `ADMIN_ADDRESSES`: if set (comma-separated addresses) and the user's `uid` (address) is in the list, returns `role: "admin"`, otherwise `"user"`. If `ADMIN_ADDRESSES` is not set, all users are `"user"`.
* **Headers**:
  * `Authorization: Bearer <access_token>` (preferred)
  * Or query parameter `?token=<access_token>` (for clients that cannot send Bearer header)
* **Response** (JSON):
  * `success` (bool): true if token is valid and user data is returned
  * `data` (object):
    * `uid` (string): User unique id (e.g. address or DID)
    * `email` (string): User email (if any)
    * `username` (string): Display name (if any)
    * `role` (string): e.g. `user` / `admin`
  * `error` (string, optional): Error message when `success` is false
* **Example request**:

```http
GET /v2/auth/me HTTP/1.1
Host: data-be.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

* **Example success response**:

```json
{
  "success": true,
  "data": {
    "uid": "0x123...abc",
    "email": "alice@example.com",
    "username": "Alice",
    "role": "user"
  }
}
```

* **Example error response (invalid or expired token)**:

```json
{
  "success": false,
  "error": "address not found in context"
}
```

***

### 6. Email Registration

#### POST /v2/login/email/register

* **Description**: Register a new user with email, verification code, and password.
* **Request body** (JSON):
  * `email` (string): User email
  * `code` (string): Email verification code
  * `password` (string): Password
  * `source` (string): Source identifier
  * `useragent` (string, optional): Client User-Agent
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `uid` (string, optional): User UID
    * `number` (string, optional): Internal user number
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token
  * `error` (string): Empty on success, or error message on failure

***

### 7. Email Password Login

#### POST /v2/login/email/password

* **Description**: Log in with email and password.
* **Request body** (JSON):
  * `email` (string): User email
  * `password` (string): Password
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `uid` (string, optional): User UID
    * `number` (string, optional): Internal user number
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token
  * `error` (string): Empty on success, or error message on failure

***

### 8. Reset Email Password

#### POST /v2/login/email/password/reset

* **Description**: Reset password with email and verification code.
* **Request body** (JSON):
  * `email` (string): User email
  * `code` (string): Email verification code
  * `new_password` (string): New password
* **Response** (JSON):
  * `result` (int): 1 for success

***

### 9. EVM Wallet Login Challenge

#### GET /v2/login/evm/challenge

* **Description**: Get the sign-in challenge message for EVM wallet login.
* **Query parameters**:
  * `address` (string): Wallet address
  * `chainid` (int, optional): Chain ID, default 985 (Memo chain)
* **Headers**:
  * `Origin` (string): Origin domain
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (string): Message to sign

***

### 10. EVM Wallet Login

#### POST /v2/login/evm

* **Description**: Log in with EVM wallet signature (message + signature).
* **Request body** (JSON):
  * `message` (string): Challenge message
  * `signature` (string): Wallet signature
  * `source` (string): Source identifier
  * `useragent` (string, optional): Client User-Agent
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `did` (string): DID identifier
    * `number` (string): User number
    * `accessToken` (string): Access token
    * `refreshToken` (string): Refresh token

***

### 11. Get User Info

#### GET /v2/user/info

* **Description**: Get the current logged-in user's info.
* **Headers**:
  * `Authorization: Bearer <access_token>`
* **Response** (JSON):
  * `result` (int): 1 for success
  * `data` (object):
    * `name` (string): Nickname
    * `icon` (string): Avatar URL
    * `address` (string): Wallet address
    * `did` (string): DID identifier
    * `email` (string, optional): Email
    * `points` (int): total datadid's points
    * `pi_info` (object, optional): Pi account info
      * `pi_id`, `pi_username`, `pi_address`
    * `twitter_info` (object, optional): Twitter account info
      * `twitter_id`, `twitter_name`, `twitter_username`
    * `telegram_info` (object, optional): Telegram account info
      * `telegram_id`, `telegram_first_name`, `telegram_last_name`, `telegram_username`, `telegram_photo`
    * `discord_info` (object, optional): Discord account info
      * `discord_id`, `discord_name`, `discord_username`, `discord_email`
    * `wechat_info` (bool): Whether WeChat is followed
* **Example response**:

```json
{
  "result": 1,
  "data": {
    "name": "Alice",
    "icon": "https://data-api.memolabs.net/v2/user/avatar/xxxxxx.png",
    "address": "0x123...abc",
    "did": "did:meta:xxxx",
    "email": "alice@example.com",
    "points": 1000,
    "pi_info": {
      "pi_id": "pi_123",
      "pi_username": "alicepi",
      "pi_address": "pi_wallet_abc"
    },
    "twitter_info": {
      "twitter_id": "tw_123",
      "twitter_name": "AliceTW",
      "twitter_username": "alice_tw"
    },
    "telegram_info": {
      "telegram_id": "tg_123",
      "telegram_first_name": "Alice",
      "telegram_last_name": "Zhang",
      "telegram_username": "alice_tg",
      "telegram_photo": "https://telegram.org/avatar/xxxx.png"
    },
    "discord_info": {
      "discord_id": "dc_123",
      "discord_name": "AliceDC",
      "discord_username": "alice_dc",
      "discord_email": "alice@discord.com"
    },
    "wechat_info": true
  }
}
```

***

### Points / Action Records

The following endpoints are under `/v2/data` and require authentication (valid access token).

#### GET /v2/data/record/:actionID

* **Description**: Get the current user's completion record for the given action ID. If there is no record, returns success with empty/null `data`.
* **Headers**: Include auth token (same as other APIs).
* **Path parameters**:
  * `actionID` (int): Action ID (positive integer).
* **Response** (JSON):
  * `result` (int): 1 for success.
  * `data` (object, optional): Present when a record exists;
    * `action` (int): Action ID;
    * `points` (int): Points awarded;
    * `time` (int64): Completion time (Unix timestamp).
  * When no record: `result` is 1, `data` absent or null.
* **Errors**: Invalid `actionID` returns parameter error; query failure returns corresponding error code.

**AliveCheck subscription**:

* In `internal/database/action_info.go`: `actionID = 5` = first-time AliveCheck subscribe; `actionID = 6` = AliveCheck renewal.
* Use `GET /v2/data/record/5` to check if the user has ever subscribed and when; use `GET /v2/data/record/6` for latest renewal.

**Example**:

```http
GET /v2/data/record/61
```

With record:

```json
{
  "result": 1,
  "data": {
    "action": 61,
    "points": 100,
    "time": 1709123456
  }
}
```

Without record:

```json
{
  "result": 1
}
```

***

#### POST /v2/data/record/add

* **Description**: Add one action completion record for the current user. Server validates the action (e.g. conditions met), then writes the record and updates points.
* **Headers**: Include auth token.
* **Request body** (JSON):
  * `actionid` (number): Action ID (required).
  * `opts` (any, optional): Extra parameters for validation (depends on action type).
* **Response** (JSON):
  * `result` (int): 1 for success.
* **Errors**: Missing `actionid` returns parameter error; validation or write failure returns corresponding error (e.g. `VERIFY_ACTION_FAILED`, `USER_ADD_ACTION_FAILED`).

**AliveCheck**: Use `actionid: 5` for first subscribe, `actionid: 6` for each renewal. Then use `GET /v2/data/record/5` and `GET /v2/data/record/6` to query status.

**Example**:

```json
POST /v2/data/record/add
{
  "actionid": 61,
  "opts": {}
}
```

Success:

```json
{
  "result": 1
}
```

## DID Creation

For DID creation APIs, see: `https://prodidapi.memolabs.org/swagger/index.html`

## Sample Code

`https://github.com/memoio/call-datadid-demo`