Create Claim Transaction

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"
  }'

const response = await fetch('https://api.zcombinator.io/claims/mint', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tokenAddress: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    userWallet: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    claimAmount: "1000000"
  })
});

const result = await response.json();

import requests

data = {
    "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "userWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "claimAmount": "1000000"
}

response = requests.post(
    'https://api.zcombinator.io/claims/mint',
    json=data,
    headers={'Content-Type': 'application/json'}
)

result = response.json()

Request Parameters

string

required

The Solana token mint address to claim from

string

required

Base58 encoded public key of the user’s wallet

string

required

Amount of tokens to claim (as string to handle large numbers)

Response

boolean

Indicates if the operation was successful

string

Base58 encoded unsigned transaction that needs to be signed by the user

string

Unique identifier for this transaction (needed for confirmation)

string

The amount of tokens that will be claimed

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

string

The amount allocated to protocol fees (10% of total claim)

number

Number of decimal places for the token

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

400 - Missing Parameters

{
  "error": "Missing required parameters"
}

400 - Amount Exceeds Available

{
  "error": "Requested amount exceeds available claim amount"
}

The user is trying to claim more than they’re eligible for.

400 - No Tokens Available

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

400 - No Mint Authority

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

404 - Token Not Found

{
  "error": "Token not found"
}

500 - Configuration Error

{
  "error": "RPC_URL not configured"
}

Or:

{
  "error": "PROTOCOL_PRIVATE_KEY not configured"
}

500 - Transaction Creation Failed

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

Process Flow

This endpoint performs several validations and setup steps:

Validate Environment

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

Validate Parameters

Ensures all required parameters are provided and valid

Check Token Existence

Verifies the token was launched through this API

Validate Eligibility

Re-calculates claim eligibility to ensure the request is valid

Verify Mint Authority

Confirms the protocol still has mint authority for the token

Get/Create Token Account

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

Create Mint Instruction

Builds the mint instruction with the correct decimal amount

Build Transaction

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

Store Transaction Data

Temporarily stores transaction details for confirmation step

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:

Deserialize the transaction using @solana/web3.js
Sign the transaction with your wallet
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

Launch

Claim token emissions (dev)

Claim LP fees

Manage AMM liquidity

Utility

Overview

Request Parameters

Response

Success Response

Error Responses

Process Flow

Transaction Key

Associated Token Account

Decimal Handling

Rate Limiting

Security Validations

Next Steps

Transaction Storage

​Overview

​Request Parameters

​Response

​Success Response

​Error Responses

​Process Flow

​Transaction Key

​Associated Token Account

​Decimal Handling

​Rate Limiting

​Security Validations

​Next Steps

​Transaction Storage

Overview

Request Parameters

Response

Success Response

Error Responses

Process Flow

Transaction Key

Associated Token Account

Decimal Handling

Rate Limiting

Security Validations

Next Steps

Transaction Storage