> ## Documentation Index
> Fetch the complete documentation index at: https://v1-docs.zcombinator.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Claim Eligibility

> GET /claims/:tokenAddress - Get claim eligibility info for a wallet and token

## Overview

Retrieves detailed claim eligibility information for a specific wallet and token, including available claim amounts, claim periods, and timing information.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.zcombinator.io/claims/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?wallet=9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
  ```

  ```javascript fetch theme={null}
  const tokenAddress = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
  const walletAddress = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM";

  const response = await fetch(
    `https://api.zcombinator.io/claims/${tokenAddress}?wallet=${walletAddress}`
  );

  const claimInfo = await response.json();
  ```

  ```python requests theme={null}
  import requests

  token_address = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  wallet_address = "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"

  response = requests.get(
      f'https://api.zcombinator.io/claims/{token_address}',
      params={'wallet': wallet_address}
  )

  claim_info = response.json()
  ```
</CodeGroup>

## URL Parameters

<ParamField path="tokenAddress" type="string" required>
  The Solana token mint address to check claims for
</ParamField>

## Query Parameters

<ParamField query="wallet" type="string" required>
  Base58 encoded public key of the wallet to check eligibility for
</ParamField>

## Response

<ResponseField name="walletAddress" type="string">
  The wallet address that was queried
</ResponseField>

<ResponseField name="tokenAddress" type="string">
  The token address that was queried
</ResponseField>

<ResponseField name="totalClaimed" type="string">
  Total amount of tokens already claimed by this wallet (as string to handle large numbers)
</ResponseField>

<ResponseField name="availableToClaim" type="string">
  Amount of tokens currently available to claim
</ResponseField>

<ResponseField name="maxClaimableNow" type="string">
  Maximum amount that can be claimed in the current transaction
</ResponseField>

<ResponseField name="tokensPerPeriod" type="string">
  Amount of tokens that become available each inflation period (1,000,000)
</ResponseField>

<ResponseField name="inflationPeriods" type="number">
  Number of complete inflation periods that have passed since token launch
</ResponseField>

<ResponseField name="tokenLaunchTime" type="string">
  ISO 8601 timestamp of when the token was launched
</ResponseField>

<ResponseField name="nextInflationTime" type="string">
  ISO 8601 timestamp of when the next inflation period begins
</ResponseField>

<ResponseField name="canClaimNow" type="boolean">
  Whether the wallet can claim tokens immediately
</ResponseField>

<ResponseField name="timeUntilNextClaim" type="number">
  Milliseconds until the next claim period (0 if can claim now)
</ResponseField>

### Success Response

```json theme={null}
{
  "walletAddress": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "totalClaimed": "0",
  "availableToClaim": "1000000",
  "maxClaimableNow": "1000000",
  "tokensPerPeriod": "1000000",
  "inflationPeriods": 1,
  "tokenLaunchTime": "2024-01-15T10:30:00.000Z",
  "nextInflationTime": "2024-01-16T10:30:00.000Z",
  "canClaimNow": true,
  "timeUntilNextClaim": 0
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="400 - Missing Wallet Parameter">
    ```json theme={null}
    {
      "error": "Wallet address is required"
    }
    ```
  </Accordion>

  <Accordion title="404 - Token Not Found">
    ```json theme={null}
    {
      "error": "Token not found"
    }
    ```

    This occurs when the token was never launched through this API.
  </Accordion>

  <Accordion title="500 - Server Error">
    ```json theme={null}
    {
      "error": "Failed to fetch claim information"
    }
    ```
  </Accordion>
</AccordionGroup>

## Claims System Mechanics

The claims system operates on a periodic inflation model:

### Inflation Periods

* **Duration**: 24 hours per period
* **Amount**: 1,000,000 tokens per period
* **Start**: Begins at token launch time

### Eligibility Calculation

* Tokens become available every 24 hours after launch
* Users can claim up to 1,000,000 tokens per period
* Unclaimed tokens from previous periods accumulate
* Claims are tracked on-chain to prevent double spending

### Timing Examples

<AccordionGroup>
  <Accordion title="Token just launched (0-24 hours)">
    ```json theme={null}
    {
      "inflationPeriods": 0,
      "availableToClaim": "0",
      "canClaimNow": false,
      "timeUntilNextClaim": 86400000
    }
    ```
  </Accordion>

  <Accordion title="One day after launch (24-48 hours)">
    ```json theme={null}
    {
      "inflationPeriods": 1,
      "availableToClaim": "1000000",
      "canClaimNow": true,
      "timeUntilNextClaim": 0
    }
    ```
  </Accordion>

  <Accordion title="User already claimed once">
    ```json theme={null}
    {
      "totalClaimed": "500000",
      "availableToClaim": "500000",
      "canClaimNow": true,
      "timeUntilNextClaim": 0
    }
    ```
  </Accordion>
</AccordionGroup>

## Rate Limiting

This endpoint is subject to rate limiting:

* **8 requests per IP** per 2-minute window
* Returns HTTP 429 when limit exceeded

## Integration Tips

<Tip>
  **Polling Strategy**: Check eligibility before showing claim UI to users. The `timeUntilNextClaim` field helps you determine when to check again.
</Tip>

<Warning>
  **Important**: Always verify eligibility immediately before creating claim transactions, as availability can change if other users claim tokens or if time periods advance.
</Warning>

## Next Steps

After checking eligibility:

1. **If `canClaimNow` is `true`**: Proceed to [`/claims/mint`](/api-reference/claims/mint)
2. **If `canClaimNow` is `false`**: Wait until `nextInflationTime` or show countdown to user
3. **For partial claims**: Use any amount up to `availableToClaim`

## On-Chain Data

The eligibility calculation is based on:

* **Database**: Token launch timestamp
* **Blockchain**: Actual claim transactions and token account balances
* **Real-time**: Current block time for period calculations

This ensures accuracy and prevents manipulation of claim eligibility.