> ## Documentation Index
> Fetch the complete documentation index at: https://v1-docs.zcombinator.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Claim Transaction

> POST /claims/mint - Create unsigned mint transaction for claiming tokens

## 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.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.zcombinator.io/claims/mint \
    -H "Content-Type: application/json" \
    -d '{
      "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "userWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "claimAmount": "1000000"
    }'
  ```

  ```javascript fetch theme={null}
  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();
  ```

  ```python requests theme={null}
  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()
  ```
</CodeGroup>

## Request Parameters

<ParamField body="tokenAddress" type="string" required>
  The Solana token mint address to claim from
</ParamField>

<ParamField body="userWallet" type="string" required>
  Base58 encoded public key of the user's wallet
</ParamField>

<ParamField body="claimAmount" type="string" required>
  Amount of tokens to claim (as string to handle large numbers)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the operation was successful
</ResponseField>

<ResponseField name="transaction" type="string">
  Base58 encoded unsigned transaction that needs to be signed by the user
</ResponseField>

<ResponseField name="transactionKey" type="string">
  Unique identifier for this transaction (needed for confirmation)
</ResponseField>

<ResponseField name="claimAmount" type="string">
  The amount of tokens that will be claimed
</ResponseField>

<ResponseField name="splitRecipients" type="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")
</ResponseField>

<ResponseField name="adminAmount" type="string">
  The amount allocated to protocol fees (10% of total claim)
</ResponseField>

<ResponseField name="mintDecimals" type="number">
  Number of decimal places for the token
</ResponseField>

<ResponseField name="message" type="string">
  Instructions for the next step in the process
</ResponseField>

### Success Response

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="400 - Missing Parameters">
    ```json theme={null}
    {
      "error": "Missing required parameters"
    }
    ```
  </Accordion>

  <Accordion title="400 - Amount Exceeds Available">
    ```json theme={null}
    {
      "error": "Requested amount exceeds available claim amount"
    }
    ```

    The user is trying to claim more than they're eligible for.
  </Accordion>

  <Accordion title="400 - No Tokens Available">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="400 - No Mint Authority">
    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="404 - Token Not Found">
    ```json theme={null}
    {
      "error": "Token not found"
    }
    ```
  </Accordion>

  <Accordion title="500 - Configuration Error">
    ```json theme={null}
    {
      "error": "RPC_URL not configured"
    }
    ```

    Or:

    ```json theme={null}
    {
      "error": "PROTOCOL_PRIVATE_KEY not configured"
    }
    ```
  </Accordion>

  <Accordion title="500 - Transaction Creation Failed">
    ```json theme={null}
    {
      "error": "Failed to create mint transaction",
      "details": "Specific error message"
    }
    ```
  </Accordion>
</AccordionGroup>

## Process Flow

This endpoint performs several validations and setup steps:

<Steps>
  <Step title="Validate Environment">
    Checks that required environment variables (RPC\_URL, PROTOCOL\_PRIVATE\_KEY) are configured
  </Step>

  <Step title="Validate Parameters">
    Ensures all required parameters are provided and valid
  </Step>

  <Step title="Check Token Existence">
    Verifies the token was launched through this API
  </Step>

  <Step title="Validate Eligibility">
    Re-calculates claim eligibility to ensure the request is valid
  </Step>

  <Step title="Verify Mint Authority">
    Confirms the protocol still has mint authority for the token
  </Step>

  <Step title="Get/Create Token Account">
    Gets or creates the user's associated token account for this token
  </Step>

  <Step title="Create Mint Instruction">
    Builds the mint instruction with the correct decimal amount
  </Step>

  <Step title="Build Transaction">
    Creates a complete transaction with recent blockhash and user as fee payer
  </Step>

  <Step title="Store Transaction Data">
    Temporarily stores transaction details for confirmation step
  </Step>

  <Step title="Return Unsigned Transaction">
    Returns the Base58 encoded transaction for user signing
  </Step>
</Steps>

## 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`](/api-reference/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

<Warning>
  **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
</Warning>

## 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`](/api-reference/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