Confirm Claim Transaction

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

const response = await fetch('https://api.zcombinator.io/claims/confirm', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signedTransaction: signedTransactionBase58,
    transactionKey: result.transactionKey
  })
});

const confirmResult = await response.json();

import requests

data = {
    "signedTransaction": signed_transaction_base58,
    "transactionKey": result["transactionKey"]
}

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

result = response.json()

Request Parameters

string

required

Base58 encoded transaction signed by the user’s wallet

string

required

Unique transaction identifier returned from /claims/mint

Response

boolean

Indicates if the operation was successful

string

The Solana transaction signature/hash

string

The token address that was claimed from

string

The amount of tokens that were successfully claimed

array

Array of recipients who received 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”)

object

Blockchain confirmation details

Success Response

{
  "success": true,
  "transactionSignature": "5VfYiDvQMBSWxKJLa9NLPQ1x3...",
  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "claimAmount": "1000000",
  "splitRecipients": [
    {
      "wallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "amount": "900000",
      "label": "Developer"
    }
  ],
  "confirmation": {
    "value": {
      "err": null
    },
    "context": {
      "slot": 123456789
    }
  }
}

Error Responses

400 - Missing Parameters

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

400 - Transaction Data Not Found

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

400 - Eligibility Changed

{
  "error": "Claim eligibility has changed. Requested amount exceeds available claim amount."
}

Eligibility was re-validated and the user no longer has enough tokens available.

400 - No Tokens Available

{
  "error": "No tokens available to claim anymore"
}

500 - Configuration Error

{
  "error": "Server configuration error"
}

Required environment variables (RPC_URL, PROTOCOL_PRIVATE_KEY) are missing.

500 - Transaction Failed

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

Validate Parameters

Ensures both required fields are provided

Retrieve Transaction Data

Fetches stored transaction details using the transactionKey

Re-validate Eligibility

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

Deserialize Transaction

Converts the Base58 signed transaction back to a Solana Transaction object

Add Protocol Signature

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

Submit to Blockchain

Sends the fully signed transaction to the Solana network

Wait for Confirmation

Monitors the transaction until it’s confirmed on-chain

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:

Creation: /claims/mint creates unsigned transaction
Storage: Transaction data stored temporarily (10min max)
Signing: User signs transaction with their wallet
Confirmation: This endpoint adds protocol signature and submits
Cleanup: Transaction data removed
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:

Verify Balance: Check user’s token account balance
Update UI: Refresh claim eligibility for next period
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.

Launch

Claim token emissions (dev)

Claim LP fees

Manage AMM liquidity

Utility

Overview

Request Parameters

Response

Success Response

Error Responses

Process Flow

Security Re-validation

Rate Limiting

Transaction Lifecycle

Transaction Data Cleanup

After Successful Claim

Transaction Signature

Integration Notes

​Overview

​Request Parameters

​Response

​Success Response

​Error Responses

​Process Flow

​Security Re-validation

​Rate Limiting

​Transaction Lifecycle

​Transaction Data Cleanup

​After Successful Claim

​Transaction Signature

​Integration Notes

Overview

Request Parameters

Response

Success Response

Error Responses

Process Flow

Security Re-validation

Rate Limiting

Transaction Lifecycle

Transaction Data Cleanup

After Successful Claim

Transaction Signature

Integration Notes