# Endpoints

## Base URL

All API requests should be prefixed with the base URL:

**Coming Soon**

> ⚠️ Note: The final production URL will be announced soon.

## Endpoints Overview

| Endpoint                                 | Method | Authentication Required | Description                                |
| ---------------------------------------- | ------ | ----------------------- | ------------------------------------------ |
| `/rewards/:address`                      | GET    | Yes                     | Get all claimable rewards for a wallet     |
| `/rewards/:address/tokens/:tokenAddress` | GET    | Yes                     | Get claimable rewards for a specific token |
| `/rewards/:signature/status`             | GET    | No                      | Check status of a claim transaction        |
| `/rewards/:address/initiate`             | POST   | Yes                     | Initiate a claim transaction               |

***

## Get All Claimable Rewards

Retrieves all claimable reward amounts for a specified wallet address. Requires signature verification to prove wallet ownership.

### Request

**URL**: `/rewards/:address`

**Method**: `GET`

**URL Parameters**:

* `address`: Solana wallet address to check rewards for

**Headers**:

* `X-Signature`: The base58-encoded signature of the timestamp
* `X-Timestamp`: The Unix timestamp in milliseconds that was signed

### Response

**Success Response (200 OK)**:

```json
{
  "status": "success",
  "data": [
    {
      "unclaimedRewards": {
        "sol": 5100000000,
        "solUi": "5.1",
        "token": 1000000020000,
        "tokenUi": "1000000.02"
      },
      "allTimeRewards": {
        "sol": 6230000000,
        "solUi": "6.23",
        "token": 5000000020000,
        "tokenUi": "5000000.02"
      },
      "tokenInfo": {
        "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        "symbol": "TKN",
        "name": "Example Token",
        "image": "https://example.com/token.png",
        "price": 0.42
      }
    }
    // Additional tokens...
  ]
}
```

**Error Responses**:

* `401 Unauthorized`: Invalid signature

  ```json
  {
    "status": "error",
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  }
  ```
* `400 Bad Request`: Invalid Solana address

  ```json
  {
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": [
      {
        "field": "address",
        "message": "Invalid Solana address"
      }
    ]
  }
  ```

***

## Get Specific Token Claimable Rewards

Retrieves claimable reward amounts for a specific wallet address and token. Requires signature verification to prove wallet ownership.

### Request

**URL**: `/rewards/:address/tokens/:tokenAddress`

**Method**: `GET`

**URL Parameters**:

* `address`: Solana wallet address to check rewards for
* `tokenAddress`: Solana token address to check rewards for

**Headers**:

* `X-Signature`: The base58-encoded signature of the timestamp
* `X-Timestamp`: The Unix timestamp in milliseconds that was signed

### Response

**Success Response (200 OK)**:

```json
{
  "status": "success",
  "data": {
    "unclaimedRewards": {
      "sol": 5100000000,
      "solUi": "5.1",
      "token": 1000000020000,
      "tokenUi": "1000000.02"
    },
    "allTimeRewards": {
      "sol": 6230000000,
      "solUi": "6.23",
      "token": 5000000020000,
      "tokenUi": "5000000.02"
    }
  }
}
```

**Error Responses**:

* `404 Not Found`: Token not found

  ```json
  {
    "status": "error",
    "code": "TOKEN_NOT_FOUND",
    "message": "Token not found"
  }
  ```
* `400 Bad Request`: Invalid parameters

  ```json
  {
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": [
      {
        "field": "tokenAddress",
        "message": "Invalid Solana token address"
      }
    ]
  }
  ```

***

## Check Claim Transaction Status

Checks the status of a claim transaction by signature. Requires signature verification to prove wallet ownership.

### Request

**URL**: `/rewards/:signature/status`

**Method**: `GET`

**URL Parameters**:

* `signature`: The transaction signature to check

### Response

**Success Response (200 OK)**:

```json
{
  "status": "success",
  "data": {
    "status": "COMPLETED",
    "message": "Claim completed"
  }
}
```

The `status` field in the response data can be one of:

* `COMPLETED`: The claim transaction was successful.
* `IN_PROGRESS`: The claim transaction is still being processed.
* `FAILED`: The claim transaction failed, you can inititate a new one.
* `EXPIRED`: The claim transaction expired, you can initiate a new one.

**Error Responses**:

* `404 Not Found`: Claim not found

  ```json
  {
    "status": "error",
    "code": "CLAIM_NOT_FOUND",
    "message": "Claim not found"
  }
  ```
* `400 Bad Request`: Invalid signature

  ```json
  {
    "status": "error",
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "errors": [
      {
        "field": "signature",
        "message": "Invalid signature length"
      }
    ]
  }
  ```

***

## Initiate Claim

Initiates a claim for rewards. Requires signature verification to prove wallet ownership.

### Request

**URL**: `/rewards/:address/initiate`

**Method**: `POST`

**URL Parameters**:

* `address`: The Solana wallet address initiating the claim

**Headers**:

* `X-Signature`: The base58-encoded signature of the timestamp
* `X-Timestamp`: The Unix timestamp in milliseconds that was signed

**Request Body**:

```json
{
  "tokenAddress": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "claimType": "SOL", // or "TOKEN"
  "burnToken": false // Optional, defaults to false
}
```

### Response

**Success Response (200 OK)**:

```json
{
  "status": "success",
  "data": {
    "tx": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAIFXWWy5rWLJXXdYR/e3TNGihD8OfE1jKf8QX9JJ7ztCRfBV2HdGaTI8QQiVn5cjgecLLrtPWWyPftsYCq1jQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAxJaxjh4N/v8IUBQYKlOgN2ndOGE/TJVvdT0xChhQvwgGp9UXGSxcUSGMyUw9SvF/WNPHDlZ0CqpPcJpjbjAAAAAAjJclj04TfbV4PUmaYD9PjzBRUTWBhf36dUjpqF/JAQAAAAEDAgAAAQAAAAAAAAA="
  }
}
```

This response contains a partially signed transaction in Base64 format. This transaction must be:

1. Deserialized
2. Signed by the wallet owner
3. Submitted to the Solana network

**Error Responses**:

* `400 Bad Request`: Invalid parameters or zero claim amount

  ```json
  {
    "status": "error",
    "code": "CLAIM_ERROR",
    "message": "SOL amount to claim is zero"
  }
  ```
* `401 Unauthorized`: Invalid signature

  ```json
  {
    "status": "error",
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  }
  ```
* `409 Conflict`: A claim is already in progress

  ```json
  {
    "status": "error",
    "code": "CLAIM_IN_PROGRESS",
    "message": "A claim for this token is already in progress"
  }
  ```

## Rate Limits

All endpoints are subject to rate limiting:

* **Limit**: 100 requests per 15-minute window per IP address
* **Response when exceeded**:

  ```json
  {
    "status": "error",
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later"
  }
  ```


---

# 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.something.cool/rewards-claiming/endpoints.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.