Verify Token

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

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');
}

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')

URL Parameters

string

required

The Solana token mint address to verify

Response

boolean

Whether the token exists on-chain

string

The token address that was checked (echoed back)

object

Full asset information from Helius API (only present if token exists)

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

200 - OK

Request processed successfully. Check the exists field to determine if token was found.

400 - Bad Request

{
  "error": "Token address is required"
}

This occurs when the address parameter is missing or empty.

500 - Server Error

{
  "error": "Helius API key not configured"
}

The server is missing required configuration to verify tokens.

Caching Behavior

This endpoint implements permanent caching for performance:

Cache Strategy

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

Cache Performance

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:

RecordNotFound (-32000)

Helius Response: Token definitively doesn’t exist

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

This result is cached permanently.

API Errors

Helius Response: Network, rate limiting, or service issues

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

This result is NOT cached, allowing retries.

Unexpected Format

Helius Response: Valid response but unexpected structure

{
  "exists": false,
  "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "error": "Unexpected response format"
}

This result is NOT cached.

Network Errors

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

Pre-validation

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
}

Token Discovery

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;
}

Claims Validation

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:

Token Metadata

Name, symbol, description
Image/logo URLs
JSON metadata URI
Creator information

Token Program Info

Total supply
Decimal places
Token program (Token Program vs Token-2022)
Mint authority status

Additional Data

Compression status
NFT collection info (if applicable)
Transfer restrictions
Extensions (if Token-2022)

/health - Check if Helius API key is configured
/claims/:tokenAddress - Check claims for verified tokens
/launch - Launch new tokens (verify they don’t exist first)

Launch

Claim token emissions (dev)

Claim LP fees

Manage AMM liquidity

Utility

Overview

URL Parameters

Response

Token Exists Response

Token Not Found Response

API Error Response

HTTP Status Codes

Caching Behavior

Error Handling

Rate Limiting

Use Cases

Asset Information

​Overview

​URL Parameters

​Response

​Token Exists Response

​Token Not Found Response

​API Error Response

​HTTP Status Codes

​Caching Behavior

​Error Handling

​Rate Limiting

​Use Cases

​Asset Information

​Related Endpoints

Overview

URL Parameters

Response

Token Exists Response

Token Not Found Response

API Error Response

HTTP Status Codes

Caching Behavior

Error Handling

Rate Limiting

Use Cases

Asset Information

Related Endpoints