Skip to main content

​
Overview

Receives a user-signed claim transaction from /claims/mint, adds the protocol’s mint authority signature, and submits the complete transaction to the Solana blockchain to finalize the token claim. 
curl -X POST https://api.zcombinator.io/claims/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "signedTransaction": "4MzR7dxJNJRVP1Q6k7Y3j8X...",
    "transactionKey": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v_9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM_1642248400000"
  }'

​
Request Parameters

​
signedTransaction
string
required
Base58 encoded transaction signed by the user’s wallet
​
transactionKey
string
required
Unique transaction identifier returned from /claims/mint

​
Response

​
success
boolean
Indicates if the operation was successful
​
transactionSignature
string
The Solana transaction signature/hash
​
tokenAddress
string
The token address that was claimed from
​
userTokenAccount
string
The user’s associated token account that received the tokens
​
claimAmount
string
The amount of tokens that were successfully claimed
​
confirmation
object
Blockchain confirmation details

​
Success Response

{
  "success": true,
  "transactionSignature": "5VfYiDvQMBSWxKJLa9NLPQ1x3...",
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "userTokenAccount": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
  "claimAmount": "1000000",
  "confirmation": {
    "value": {
      "err": null
    },
    "context": {
      "slot": 123456789
    }
  }
}

​
Error Responses

{
  "error": "Missing required fields: signedTransaction and transactionKey"
}

{
  "error": "Transaction data not found. Please call /claims/mint first."
}
This occurs when:
  • Invalid or expired transactionKey
  • Temporary storage was cleared
  • Transaction was already processed
{
  "error": "Claim eligibility has changed. Requested amount exceeds available claim amount."
}
Eligibility was re-validated and the user no longer has enough tokens available.
{
  "error": "No tokens available to claim anymore"
}

{
  "error": "Server configuration error"
}
Required environment variables (RPC_URL, PROTOCOL_PRIVATE_KEY) are missing.
{
  "error": "Failed to confirm claim"
}
This can occur due to:
  • Network congestion
  • Insufficient funds for transaction fees
  • Invalid transaction signature
  • Blockchain errors

​
Process Flow

This endpoint completes the two-phase claim process:
1

Validate Parameters

Ensures both required fields are provided
2

Retrieve Transaction Data

Fetches stored transaction details using the transactionKey
3

Re-validate Eligibility

Performs a security check to ensure claim eligibility hasn’t changed
4

Deserialize Transaction

Converts the Base58 signed transaction back to a Solana Transaction object
5

Add Protocol Signature

Signs the transaction with the protocol’s keypair (mint authority)
6

Submit to Blockchain

Sends the fully signed transaction to the Solana network
7

Wait for Confirmation

Monitors the transaction until it’s confirmed on-chain
8

Cleanup

Removes the temporary transaction data

​
Security Re-validation

Important Security Check: The API re-validates claim eligibility before processing to prevent race conditions where:
  • Other users claimed tokens in the meantime
  • Inflation periods advanced
  • User’s eligibility changed for any reason
This prevents users from claiming more than they’re entitled to, even if they hold onto signed transactions.

​
Rate Limiting

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

​
Transaction Lifecycle

The claim transaction follows this lifecycle:
  1. Creation: /claims/mint creates unsigned transaction
  2. Storage: Transaction data stored temporarily (10min max)
  3. Signing: User signs transaction with their wallet
  4. Confirmation: This endpoint adds protocol signature and submits
  5. Cleanup: Transaction data removed
  6. Finality: Tokens are permanently transferred to user

​
Transaction Data Cleanup

Cleanup Policy:
  • Successful transactions: Immediately cleaned up
  • Failed transactions: Remain until expiration
  • Expired transactions: Automatically removed after 10 minutes

​
After Successful Claim

Once tokens are successfully claimed:
  1. Verify Balance: Check user’s token account balance
  2. Update UI: Refresh claim eligibility for next period
  3. Transaction Proof: Use transactionSignature for verification

​
Transaction Signature

The returned transactionSignature can be used to:
  • View the transaction on Solana explorers
  • Verify the token claim on-chain
  • Provide proof of claim to users
  • Track transaction status
Example Solana Explorer URL: 
https://explorer.solana.com/tx/${transactionSignature}

​
Integration Notes

Best Practice: Always handle both success and error cases gracefully. Failed claims may be retryable if the issue was network-related rather than eligibility-related.
Multi-instance Deployments: If running multiple API instances, consider using Redis or similar for shared transaction state instead of in-memory storage.
⌘I