Skip to main content

​
Overview

Verifies whether a token exists on Solana. This endpoint is useful for validating token addresses before attempting operations. 
curl -X GET https://api.zcombinator.io/verify-token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

​
URL Parameters

​
address
string
required
The Solana token mint address to verify

​
Response

​
exists
boolean
Whether the token exists on-chain
​
address
string
The token address that was checked (echoed back)
​
asset
object
Full asset information from Helius API (only present if token exists)
​
error
string
Error message if verification failed (optional)

​
Token Exists Response

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

{
  "exists": false,
  "address": "InvalidTokenAddressExample123456789"
}

​
API Error Response

{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "error": "API error occurred"
}

​
HTTP Status Codes

Request processed successfully. Check the exists field to determine if token was found.
{
  "error": "Token address is required"
}
This occurs when the address parameter is missing or empty.
{
  "error": "Helius API key not configured"
}
The server is missing required configuration to verify tokens.

​
Caching Behavior

This endpoint implements permanent caching for performance:
  • 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
  • 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

​
Error Handling

The endpoint handles various error scenarios:
Helius Response: Token definitively doesn’t exist
{
  "exists": false,
  "address": "NonExistentTokenAddress123"
}
This result is cached permanently.
Helius Response: Network, rate limiting, or service issues
{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "error": "API error occurred"
}
This result is NOT cached, allowing retries.
Helius Response: Valid response but unexpected structure
{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "error": "Unexpected response format"
}
This result is NOT cached.
Client/Network: Connection issues, timeouts
{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
Internal errors are not exposed to prevent information disclosure.

​
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

Verify tokens before attempting operations:
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
}
Check if user-provided addresses are valid:
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;
}
Verify tokens before checking claim eligibility:
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}`);
}

​
Asset Information

When a token exists, the response includes rich metadata:
  • Name, symbol, description
  • Image/logo URLs
  • JSON metadata URI
  • Creator information
  • Total supply
  • Decimal places
  • Token program (Token Program vs Token-2022)
  • Mint authority status
  • Compression status
  • NFT collection info (if applicable)
  • Transfer restrictions
  • Extensions (if Token-2022)
⌘I