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

# Verify Token

> GET /verify-token/:address - Verify token exists on-chain

## Overview

Verifies whether a token exists on Solana. This endpoint is useful for validating token addresses before attempting operations.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://api.zcombinator.io/verify-token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
  ```

  ```javascript fetch theme={null}
  const tokenAddress = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

  const response = await fetch(`https://api.zcombinator.io/verify-token/${tokenAddress}`);
  const verification = await response.json();

  if (verification.exists) {
    console.log('Token exists:', verification.asset);
  } else {
    console.log('Token not found');
  }
  ```

  ```python requests theme={null}
  import requests

  token_address = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

  response = requests.get(f'https://api.zcombinator.io/verify-token/{token_address}')
  verification = response.json()

  if verification.get('exists'):
      print('Token exists:', verification.get('asset'))
  else:
      print('Token not found')
  ```
</CodeGroup>

## URL Parameters

<ParamField path="address" type="string" required>
  The Solana token mint address to verify
</ParamField>

## Response

<ResponseField name="exists" type="boolean">
  Whether the token exists on-chain
</ResponseField>

<ResponseField name="address" type="string">
  The token address that was checked (echoed back)
</ResponseField>

<ResponseField name="asset" type="object">
  Full asset information from Helius API (only present if token exists)
</ResponseField>

<ResponseField name="error" type="string">
  Error message if verification failed (optional)
</ResponseField>

### Token Exists Response

```json theme={null}
{
  "exists": true,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "asset": {
    "id": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "content": {
      "metadata": {
        "name": "USD Coin",
        "symbol": "USDC",
        "description": "USDC is a fully collateralized US dollar stablecoin"
      },
      "json_uri": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png"
    },
    "token_info": {
      "supply": "41006516283836080",
      "decimals": 6,
      "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
    }
  }
}
```

### Token Not Found Response

```json theme={null}
{
  "exists": false,
  "address": "InvalidTokenAddressExample123456789"
}
```

### API Error Response

```json theme={null}
{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "error": "API error occurred"
}
```

## HTTP Status Codes

<AccordionGroup>
  <Accordion title="200 - OK">
    Request processed successfully. Check the `exists` field to determine if token was found.
  </Accordion>

  <Accordion title="400 - Bad Request">
    ```json theme={null}
    {
      "error": "Token address is required"
    }
    ```

    This occurs when the address parameter is missing or empty.
  </Accordion>

  <Accordion title="500 - Server Error">
    ```json theme={null}
    {
      "error": "Helius API key not configured"
    }
    ```

    The server is missing required configuration to verify tokens.
  </Accordion>
</AccordionGroup>

## Caching Behavior

This endpoint implements permanent caching for performance:

<AccordionGroup>
  <Accordion title="Cache Strategy" icon="database">
    * **Exists = true**: Cached permanently (tokens can't be "un-created")
    * **Exists = false**: Cached permanently only for confirmed "RecordNotFound" errors
    * **API errors**: Not cached, allowing retries for transient issues
    * **Cache key**: Token address
  </Accordion>

  <Accordion title="Cache Performance" icon="gauge">
    * **First request**: Calls Helius API (\~200-500ms)
    * **Subsequent requests**: Instant response from memory cache
    * **Cache hits**: Logged to server console for monitoring
    * **Memory usage**: Minimal overhead per cached token
  </Accordion>
</AccordionGroup>

## Error Handling

The endpoint handles various error scenarios:

<AccordionGroup>
  <Accordion title="RecordNotFound (-32000)" icon="search">
    **Helius Response**: Token definitively doesn't exist

    ```json theme={null}
    {
      "exists": false,
      "address": "NonExistentTokenAddress123"
    }
    ```

    This result is cached permanently.
  </Accordion>

  <Accordion title="API Errors" icon="exclamation-triangle">
    **Helius Response**: Network, rate limiting, or service issues

    ```json theme={null}
    {
      "exists": false,
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "error": "API error occurred"
    }
    ```

    This result is NOT cached, allowing retries.
  </Accordion>

  <Accordion title="Unexpected Format" icon="question">
    **Helius Response**: Valid response but unexpected structure

    ```json theme={null}
    {
      "exists": false,
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "error": "Unexpected response format"
    }
    ```

    This result is NOT cached.
  </Accordion>

  <Accordion title="Network Errors" icon="wifi">
    **Client/Network**: Connection issues, timeouts

    ```json theme={null}
    {
      "exists": false,
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
    ```

    Internal errors are not exposed to prevent information disclosure.
  </Accordion>
</AccordionGroup>

## Rate Limiting

This endpoint is subject to rate limiting:

* **8 requests per IP** per 2-minute window
* Returns HTTP 429 when limit exceeded
* **Note**: Cached responses don't count against rate limits

## Use Cases

<AccordionGroup>
  <Accordion title="Pre-validation" icon="check-circle">
    Verify tokens before attempting operations:

    ```javascript theme={null}
    async function validateTokenBeforeLaunch(address) {
      const verification = await fetch(`/verify-token/${address}`);
      const result = await verification.json();

      if (result.exists) {
        throw new Error('Token already exists!');
      }

      // Proceed with launch
    }
    ```
  </Accordion>

  <Accordion title="Token Discovery" icon="magnifying-glass">
    Check if user-provided addresses are valid:

    ```javascript theme={null}
    async function findToken(userInput) {
      const verification = await fetch(`/verify-token/${userInput}`);
      const result = await verification.json();

      if (result.exists) {
        return {
          name: result.asset.content.metadata.name,
          symbol: result.asset.content.metadata.symbol,
          decimals: result.asset.token_info.decimals
        };
      }

      return null;
    }
    ```
  </Accordion>

  <Accordion title="Claims Validation" icon="coins">
    Verify tokens before checking claim eligibility:

    ```javascript theme={null}
    async function checkClaimsForToken(address, wallet) {
      // First verify token exists
      const verification = await fetch(`/verify-token/${address}`);
      const result = await verification.json();

      if (!result.exists) {
        throw new Error('Token not found on-chain');
      }

      // Then check claims
      return fetch(`/claims/${address}?wallet=${wallet}`);
    }
    ```
  </Accordion>
</AccordionGroup>

## Asset Information

When a token exists, the response includes rich metadata:

<AccordionGroup>
  <Accordion title="Token Metadata" icon="tag">
    * Name, symbol, description
    * Image/logo URLs
    * JSON metadata URI
    * Creator information
  </Accordion>

  <Accordion title="Token Program Info" icon="code">
    * Total supply
    * Decimal places
    * Token program (Token Program vs Token-2022)
    * Mint authority status
  </Accordion>

  <Accordion title="Additional Data" icon="info">
    * Compression status
    * NFT collection info (if applicable)
    * Transfer restrictions
    * Extensions (if Token-2022)
  </Accordion>
</AccordionGroup>

## Related Endpoints

* [`/health`](/api-reference/utility/health) - Check if Helius API key is configured
* [`/claims/:tokenAddress`](/api-reference/claims/eligibility) - Check claims for verified tokens
* [`/launch`](/api-reference/launch/create) - Launch new tokens (verify they don't exist first)