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):

{
  "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

  {
    "status": "error",
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  }

• 400 Bad Request: Invalid Solana address

  {
    "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):

{
  "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

  {
    "status": "error",
    "code": "TOKEN_NOT_FOUND",
    "message": "Token not found"
  }

• 400 Bad Request: Invalid parameters

  {
    "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):

{
  "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

  {
    "status": "error",
    "code": "CLAIM_NOT_FOUND",
    "message": "Claim not found"
  }

• 400 Bad Request: Invalid signature

  {
    "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:

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

Response

Success Response (200 OK):

{
  "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

  {
    "status": "error",
    "code": "CLAIM_ERROR",
    "message": "SOL amount to claim is zero"
  }

• 401 Unauthorized: Invalid signature

  {
    "status": "error",
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  }

• 409 Conflict: A claim is already in progress

  {
    "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:

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