Skip to main content

​
Overview

Creates an unsigned mint transaction for claiming available tokens. The API validates eligibility, creates the user’s associated token account if needed, and returns a transaction ready for user signing. 
curl -X POST https://api.zcombinator.io/claims/mint \
  -H "Content-Type: application/json" \
  -d '{
    "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "userWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "claimAmount": "1000000"
  }'

​
Request Parameters

​
tokenAddress
string
required
The Solana token mint address to claim from
​
userWallet
string
required
Base58 encoded public key of the user’s wallet
​
claimAmount
string
required
Amount of tokens to claim (as string to handle large numbers)

​
Response

​
success
boolean
Indicates if the operation was successful
​
transaction
string
Base58 encoded unsigned transaction that needs to be signed by the user
​
transactionKey
string
Unique identifier for this transaction (needed for confirmation)
​
claimAmount
string
The amount of tokens that will be claimed
​
splitRecipients
array
Array of recipients who will receive tokens from this claim, each containing:
  • wallet (string): The recipient’s wallet address
  • amount (string): The amount allocated to this recipient
  • label (string, optional): Description of the recipient (e.g., “Developer”)
​
adminAmount
string
The amount allocated to protocol fees (10% of total claim)
​
mintDecimals
number
Number of decimal places for the token
​
message
string
Instructions for the next step in the process

​
Success Response

{
  "success": true,
  "transaction": "4MzR7dxJNJRVP1Q6k7Y3j8X...",
  "transactionKey": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v_1642248400000_a1b2c3d4e5f6g7h8",
  "claimAmount": "1000000",
  "splitRecipients": [
    {
      "wallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "amount": "900000",
      "label": "Developer"
    }
  ],
  "adminAmount": "100000",
  "mintDecimals": 9,
  "message": "Sign this transaction and submit to /claims/confirm"
}

​
Error Responses

{
  "error": "Missing required parameters"
}

{
  "error": "Requested amount exceeds available claim amount"
}
The user is trying to claim more than they’re eligible for.
{
  "error": "No tokens available to claim yet",
  "nextInflationTime": "2024-01-16T10:30:00.000Z"
}
The user has no tokens available to claim at this time.
{
  "error": "Protocol does not have mint authority for this token"
}
The protocol has lost mint authority or the token wasn’t launched through this API.
{
  "error": "Token not found"
}

{
  "error": "RPC_URL not configured"
}
Or:
{
  "error": "PROTOCOL_PRIVATE_KEY not configured"
}

{
  "error": "Failed to create mint transaction",
  "details": "Specific error message"
}

​
Process Flow

This endpoint performs several validations and setup steps:
1

Validate Environment

Checks that required environment variables (RPC_URL, PROTOCOL_PRIVATE_KEY) are configured
2

Validate Parameters

Ensures all required parameters are provided and valid
3

Check Token Existence

Verifies the token was launched through this API
4

Validate Eligibility

Re-calculates claim eligibility to ensure the request is valid
5

Verify Mint Authority

Confirms the protocol still has mint authority for the token
6

Get/Create Token Account

Gets or creates the user’s associated token account for this token
7

Create Mint Instruction

Builds the mint instruction with the correct decimal amount
8

Build Transaction

Creates a complete transaction with recent blockhash and user as fee payer
9

Store Transaction Data

Temporarily stores transaction details for confirmation step
10

Return Unsigned Transaction

Returns the Base58 encoded transaction for user signing

​
Transaction Key

The transactionKey is essential for the confirmation step:
  • Format: {tokenAddress}_{userWallet}_{timestamp}
  • Expiration: Automatically cleaned up after 10 minutes
  • Required: Must be provided to /claims/confirm

​
Associated Token Account

The API automatically handles associated token account (ATA) creation:
  • If exists: Uses the existing ATA
  • If missing: Creates a new ATA (protocol pays rent)
  • Address: Deterministic based on wallet + token mint

​
Decimal Handling

Token amounts are handled with proper decimal precision:
  • Input: Raw token amount (e.g., 1000000 for 1M tokens)
  • Processing: Multiplied by 10^decimals for blockchain
  • Most tokens: Use 9 decimal places
  • Returned: mintDecimals field shows the actual decimal count

​
Rate Limiting

This endpoint is subject to rate limiting:
  • 8 requests per IP per 2-minute window
  • Returns HTTP 429 when limit exceeded

​
Security Validations

Real-time Validations:
  • Eligibility is re-calculated at request time
  • Mint authority is verified before transaction creation
  • Token existence is confirmed
  • User cannot claim more than eligible amount

​
Next Steps

After receiving the unsigned transaction:
  1. Deserialize the transaction using @solana/web3.js
  2. Sign the transaction with your wallet
  3. Submit the signed transaction to /claims/confirm

​
Transaction Storage

Transaction data is stored temporarily:
  • Storage Duration: 10 minutes maximum
  • Cleanup: Automatic cleanup of expired transactions
  • Expiration: You must call /claims/confirm within the time window