Skip to main content

​
Overview

Retrieves detailed claim eligibility information for a specific wallet and token, including available claim amounts, claim periods, and timing information. 
curl -X GET "https://api.zcombinator.io/claims/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v?wallet=9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"

​
URL Parameters

​
tokenAddress
string
required
The Solana token mint address to check claims for

​
Query Parameters

​
wallet
string
required
Base58 encoded public key of the wallet to check eligibility for

​
Response

​
walletAddress
string
The wallet address that was queried
​
tokenAddress
string
The token address that was queried
​
totalClaimed
string
Total amount of tokens already claimed by this wallet (as string to handle large numbers)
​
availableToClaim
string
Amount of tokens currently available to claim
​
maxClaimableNow
string
Maximum amount that can be claimed in the current transaction
​
tokensPerPeriod
string
Amount of tokens that become available each inflation period (1,000,000)
​
inflationPeriods
number
Number of complete inflation periods that have passed since token launch
​
tokenLaunchTime
string
ISO 8601 timestamp of when the token was launched
​
nextInflationTime
string
ISO 8601 timestamp of when the next inflation period begins
​
canClaimNow
boolean
Whether the wallet can claim tokens immediately
​
timeUntilNextClaim
number
Milliseconds until the next claim period (0 if can claim now)

​
Success Response

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

{
  "error": "Wallet address is required"
}

{
  "error": "Token not found"
}
This occurs when the token was never launched through this API.
{
  "error": "Failed to fetch claim information"
}

​
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

{
  "inflationPeriods": 0,
  "availableToClaim": "0",
  "canClaimNow": false,
  "timeUntilNextClaim": 86400000
}

{
  "inflationPeriods": 1,
  "availableToClaim": "1000000",
  "canClaimNow": true,
  "timeUntilNextClaim": 0
}

{
  "totalClaimed": "500000",
  "availableToClaim": "500000",
  "canClaimNow": true,
  "timeUntilNextClaim": 0
}

​
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

Polling Strategy: Check eligibility before showing claim UI to users. The timeUntilNextClaim field helps you determine when to check again.
Important: Always verify eligibility immediately before creating claim transactions, as availability can change if other users claim tokens or if time periods advance.

​
Next Steps

After checking eligibility:
  1. If canClaimNow is true: Proceed to /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.
⌘I