Market Data - API

The API access documentation for real-time market data for Lillo framework.

Overview

The Market Data API provides access to real-time cryptocurrency market data through a combination of DexScreener and CoinGecko integrations. All requests are proxied through our webapp endpoint for rate limiting and error handling.

Endpoints

Market Data Endpoint

GET ${WEBAPP_URL}/api/market/dex

Query Parameters

• type: The type of data to fetch

  • ticker - Token lookup by symbol

  • ca - Token lookup by contract address

  • trending - Trending Solana tokens

  • latest - Latest Solana pairs

  • boosted - Boosted Solana tokens

• address: Token symbol or address (required for ticker/ca types)

Response Format

interface MarketResponse {
  content: string;  // Formatted market data
  error?: string;   // Error message if any
}

Data Types

TokenData

interface TokenData {
  baseToken: {
    address: string;
    name: string;
    symbol: string;
  };
  quoteToken: {
    name: string;
    symbol: string;
  };
  priceUsd: string;
  volume: {
    h24: number;
    h6: number;
    h1: number;
  };
  priceChange: {
    h24: string;
    h6: string;
    h1: string;
  };
  liquidity: {
    usd: number;
  };
  marketCap: number;
  fdv: number;
  txns: {
    h24: {
      buys: number;
      sells: number;
    };
  };
  profile?: {
    icon?: string;
    description?: string;
    links?: Array<{
      type: string;
      label: string;
      url: string;
    }>;
  };
}

Error Handling

All endpoints follow a consistent error response format:

{
  error: string;      // Error message
  content: string;    // User-friendly error message
}

Common error codes:

• 400 - Missing or invalid parameters

• 404 - Token not found

• 500 - Server error

Retry Logic

• Maximum 3 retry attempts

• Exponential backoff (1s, 2s, 3s)

• Clear error messages on failure

Best Practices

1. Error Handling

   • Implement proper error catching

   • Handle network failures gracefully

   • Provide meaningful error messages

2. Rate Limiting

   • Respect API rate limits

   • Implement backoff strategies

   • Handle rate limit errors appropriately

3. Data Processing

   • Filter by Solana chain where applicable

   • Sort by appropriate metrics (volume, liquidity)

   • Format numbers for display

Related Documentation

• Market Data Overview

• Command Reference

• Integration Guide

CoinGecko Market Data

GET /api/market/gecko

Fetches market data from CoinGecko for major cryptocurrencies.

Query Parameters

• type (optional): Data type to fetch

  • market (default) - Top 50 by market cap

  • trending - Trending coins

Response Format

interface GeckoResponse {
  content: string;  // Formatted market data
  error?: string;   // Error message if any
}

Example Requests

1. Top Market Cap

GET /api/market/gecko

1. Trending Coins

GET /api/market/gecko?type=trending

Error Codes

• 500 - Server error or CoinGecko API error

TradingView Chart Data

GET /api/market/tradingview

Processes trading pair symbols for TradingView chart integration.

Query Parameters

• symbol (required): Trading pair symbol (e.g., "BTCUSD")

Response Format

interface ChartResponse {
  content: string;  // Formatted chart command
  symbol: string;   // Processed trading pair symbol
}

Example Request

GET /api/market/tradingview?symbol=BTCUSD

Error Codes

• 400 - Missing or invalid symbol

• 500 - Processing error

Data Types

Token Data

interface TokenData {
  name: string;
  symbol: string;
  address?: string;
  price: number;
  price_change_24h: number;
  price_change_1h?: number;
  price_change_6h?: number;
  market_cap: number;
  total_volume: number;
  liquidity?: number;
  links?: Array<{ type: string; url: string; }>;
}

DEX Pair Data

interface DexScreenerPair {
  chainId: string;
  dexId: string;
  pairAddress: string;
  baseToken: {
    address: string;
    name: string;
    symbol: string;
    profile?: {
      icon?: string;
      description?: string;
      links?: Array<{
        type: string;
        label: string;
        url: string;
      }>;
    };
  };
  quoteToken: TokenInfo;
  priceUsd: string;
  volume: { h24: number; h6: number; h1: number; };
  priceChange: { h24: string; h6: string; h1: string; };
  liquidity: { usd: number; };
  marketCap: number;
  txns: { h24: { buys: number; sells: number; }; };
}

Rate Limiting

• DexScreener: Standard rate limits apply

• CoinGecko: Free tier rate limits apply

• Cache implemented for frequent requests

Error Handling

All endpoints follow a consistent error response format:

{
  error: string;      // Error message
  content: string;    // User-friendly error message
}

Common error scenarios:

1. Invalid parameters

2. Token not found

3. Rate limit exceeded

4. External API errors

5. Network issues

Best Practices

1. Caching

   • Cache responses when possible

   • Respect cache headers

   • Implement retry logic

2. Rate Limiting

   • Implement backoff strategies

   • Cache frequently accessed data

   • Monitor usage limits

3. Error Handling

   • Implement proper error catching

   • Provide meaningful error messages

   • Log errors appropriately

4. Security

   • Validate input parameters

   • Sanitize responses

   • Monitor for abuse

Related Documentation

• Market Data Overview

• Command Reference

• Integration Guide