# WPoints Public API

### Overview

The Points API provides comprehensive access to user points data within the W-Chain ecosystem. These endpoints allow you to retrieve points information for individual users, leaderboards, and comparative analytics across different time periods and categories.

### Base URL

`https://oracle.w-chain.com/api/points`

### Authentication

All Points API endpoints are publicly accessible and do not require authentication.

### Common Parameters

#### Month Format

When specifying months in API calls, use the format: `YYYY-MM`

* Example: `2024-01` for January 2024
* Example: `2024-12` for December 2024

#### User Parameter

User addresses should be provided as Ethereum-compatible addresses (0x prefixed hex strings).

***

### Endpoints

#### 1. Monthly Leaderboard

**Endpoint:** `GET /leaderboard`\
**Cache:** 5 minutes\
**Description:** Retrieves the points leaderboard for a specific month, showing all users ranked by their total points.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/leaderboard?month=2024-01
```

**Example Response**

```json
[
  {
    "user": "0x1234567890123456789012345678901234567890",
    "points": 15750
  },
  {
    "user": "0x0987654321098765432109876543210987654321",
    "points": 12300
  },
  {
    "user": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "points": 8900
  }
]
```

**Response Fields**

* `user`: Ethereum address of the user
* `points`: Total points earned by the user in the specified month

**Notes**

* Results are automatically sorted by points in descending order (highest first)
* Only includes users who earned points during the specified month

***

#### 2. User Points Details

**Endpoint:** `GET /user`\
**Cache:** 5 minutes\
**Description:** Retrieves detailed points information for a specific user in a given month, including individual point entries with categories and transaction hashes.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user?month=2024-01&user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
[
  {
    "category": "trading",
    "points": 500,
    "created_at": "2024-01-15T14:30:00.000Z",
    "hash": "0xabc123def456789..."
  },
  {
    "category": "staking",
    "points": 250,
    "created_at": "2024-01-14T09:15:00.000Z",
    "hash": "0xdef789abc123456..."
  },
  {
    "category": "liquidity_provision",
    "points": 1000,
    "created_at": "2024-01-13T16:45:00.000Z",
    "hash": "0x123456789abcdef..."
  }
]
```

**Response Fields**

* `category`: The category/type of activity that earned the points
* `points`: Number of points earned for this specific activity
* `created_at`: ISO timestamp when the points were awarded
* `hash`: Transaction hash associated with the point-earning activity

**Notes**

* Results are ordered by creation date (most recent first)
* Provides granular view of all point-earning activities

***

#### 3. User Points by Category

**Endpoint:** `GET /user-by-category`\
**Cache:** 30 seconds\
**Description:** Retrieves aggregated points for a specific user grouped by category for a given month.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `month`   | string | Yes      | Month in YYYY-MM format |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user-by-category?month=2024-01&user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
[
  {
    "category": "trading",
    "points": 5500
  },
  {
    "category": "liquidity_provision",
    "points": 3200
  },
  {
    "category": "staking",
    "points": 1800
  },
  {
    "category": "referral",
    "points": 750
  }
]
```

**Response Fields**

* `category`: The category/type of activity
* `points`: Total points earned in this category for the specified month

**Notes**

* Results are sorted by points in descending order (highest category first)
* Provides a summary view of user's point distribution across activities

***

#### 4. Current Month User Points

**Endpoint:** `GET /user-by-current-month`\
**Cache:** 1 minute\
**Description:** Retrieves the total points for a specific user in the current month.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/user-by-current-month?user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
{
  "points": 8750
}
```

**Response Fields**

* `points`: Total points earned by the user in the current month

**Notes**

* Automatically uses the current month (no month parameter needed)
* Useful for real-time dashboards and current progress tracking

***

#### 5. Points Comparison vs Last Month

**Endpoint:** `GET /vs-last-month`\
**Cache:** 1 minute\
**Description:** Compares a user's points between the current period and the corresponding period in the previous month, with intelligent date range handling.

**Parameters**

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `user`    | string | Yes      | User's Ethereum address |

**Example Request**

```
GET https://oracle.w-chain.com/api/points/vs-last-month?user=0x1234567890123456789012345678901234567890
```

**Example Response**

```json
{
  "current": {
    "points": 8750,
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-19T23:59:59.999Z"
    }
  },
  "lastMonth": {
    "points": 6200,
    "period": {
      "start": "2023-12-01T00:00:00.000Z",
      "end": "2023-12-19T23:59:59.999Z"
    }
  },
  "comparison": {
    "difference": 2550,
    "percentageChange": 41.13,
    "isFullMonthComparison": false
  }
}
```

**Response Fields**

**Current Period:**

* `current.points`: Points earned in the current period
* `current.period.start`: Start date of current comparison period
* `current.period.end`: End date of current comparison period

**Last Month Period:**

* `lastMonth.points`: Points earned in the corresponding previous period
* `lastMonth.period.start`: Start date of previous comparison period
* `lastMonth.period.end`: End date of previous comparison period

**Comparison Analytics:**

* `comparison.difference`: Absolute difference in points (current - last month)
* `comparison.percentageChange`: Percentage change from last month (rounded to 2 decimal places)
* `comparison.isFullMonthComparison`: Boolean indicating if comparing full months or partial periods

**Intelligent Date Range Logic**

The endpoint uses smart date range comparison:

1. **Late in Month (Day >= 28)**: Compares full months
   * Current: Full current month
   * Previous: Full previous month
2. **Early/Mid Month (Day < 28)**: Compares equivalent date ranges
   * Current: Month start to current date
   * Previous: Same date range in previous month
   * Example: If today is Jan 19, compares Jan 1-19 vs Dec 1-19

**Use Cases**

* **Progress Tracking**: Monitor user engagement trends
* **Gamification**: Show improvement or decline in user activity
* **Analytics**: Understand user behavior patterns over time

***

### Error Handling

All endpoints return appropriate HTTP status codes and error messages:

#### 400 Bad Request

Returned when required parameters are missing or invalid.

```json
{
  "statusCode": 400,
  "statusMessage": "Missing month parameter"
}
```

#### 404 Not Found

Returned when no points data is found for the specified criteria.

```json
{
  "statusCode": 404,
  "statusMessage": "Points not found"
}
```

### Caching Strategy

Each endpoint implements intelligent caching to balance data freshness with performance:

| Endpoint                 | Cache Duration | Reasoning                                     |
| ------------------------ | -------------- | --------------------------------------------- |
| `/leaderboard`           | 5 minutes      | Leaderboard changes relatively slowly         |
| `/user`                  | 5 minutes      | Detailed history is relatively stable         |
| `/user-by-category`      | 30 seconds     | Category summaries may update more frequently |
| `/user-by-current-month` | 1 minute       | Current month data changes more frequently    |
| `/vs-last-month`         | 1 minute       | Comparison data needs to be relatively fresh  |

### Rate Limiting

No explicit rate limiting is enforced, but clients should respect the cache durations to optimize performance and reduce server load.

### Data Categories

Common point categories include:

* `trading`: Points earned from trading activities
* `staking`: Points from staking WCO tokens
* `liquidity_provision`: Points from providing liquidity to pools
* `referral`: Points from referring new users
* `governance`: Points from participating in governance
* `bridge`: Points from using cross-chain bridge functionality

### Best Practices

#### For Developers

1. **Cache Awareness**: Respect cache durations in your application logic
2. **Error Handling**: Implement proper error handling for 400/404 responses
3. **Date Formatting**: Always use YYYY-MM format for month parameters
4. **Address Validation**: Validate Ethereum addresses before making API calls

#### For Analytics

1. **Trend Analysis**: Use `/vs-last-month` for growth tracking
2. **Category Insights**: Use `/user-by-category` to understand user behavior
3. **Leaderboard Tracking**: Monitor `/leaderboard` for competitive analysis

#### For User Interfaces

1. **Real-time Updates**: Use `/user-by-current-month` for live progress displays
2. **Historical Data**: Use `/user` for detailed activity timelines
3. **Comparative Views**: Use `/vs-last-month` for progress indicators

### Support

For technical support or questions about the Points API:

* Verify parameter formats match the documentation
* Check error messages for specific guidance
* Ensure user addresses are valid Ethereum addresses
* Consult the caching information for data freshness expectations


---

# 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.w-chain.com/advanced-features/wpoints-public-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.