Tokens

The tokens system provides information about supported tokens, including their current prices in USD and BRL, as well as historical price data. This guide covers how to retrieve token lists, check current prices, and view historical price charts.

Overview

The tokens system provides:

  • Token Lists - View all supported tokens across different chains
  • Current Prices - Get real-time token prices in USD and BRL
  • Historical Prices - View historical price data (OHLC - Open, High, Low, Close)
  • Price Changes - See 24-hour price changes

Prerequisites

Before using token endpoints, ensure you have:

  • Completed authentication and have a valid access token (for some endpoints)

Get Tokens List

Retrieve a list of all supported tokens, including both regular tokens and aTokens (yield tokens).

Get tokens list

curl -X GET https://api.example.com/api/tokens \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Tokens list retrieved successfully",
  "data": {
    "tokens": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "chain": {
          "id": 137,
          "name": "Polygon",
          "cg_id": "polygon-pos",
          "logo": "https://..."
        },
        "decimals": 6,
        "logo": "https://...",
        "cg_id": "usd-coin",
        "underlyingTokenAddress": null
      },
      {
        "symbol": "aPolUSDC",
        "name": "Aave USDC",
        "address": "0x625e7708f30ca75bfd92586e17077590c60eb4cd",
        "chain": {
          "id": 137,
          "name": "Polygon",
          "cg_id": "polygon-pos",
          "logo": "https://..."
        },
        "decimals": 6,
        "logo": "https://...",
        "cg_id": "aave-usdc",
        "underlyingTokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    ]
  }
}

Response Fields:

  • tokens - Array of token objects
    • symbol - Token symbol (e.g., "USDC", "ETH")
    • name - Token full name
    • address - Token contract address
    • chain - Blockchain information
      • id - Chain ID
      • name - Chain name
      • cg_id - CoinGecko chain identifier
      • logo - Chain logo URL
    • decimals - Token decimals
    • logo - Token logo URL
    • cg_id - CoinGecko token identifier
    • underlyingTokenAddress - Address of underlying token (for aTokens/yield tokens)

Get Token Price

Retrieve the current price of a specific token in USD and BRL, along with 24-hour price changes.

Get token price

curl -X GET https://api.example.com/api/tokens/chain/{chainId}/address/{address}/price \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Path Parameters:

  • chainId - Chain ID where the token is located (e.g., 137 for Polygon)
  • address - Token contract address

Example:

curl -X GET https://api.example.com/api/tokens/chain/137/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/price \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Token price retrieved successfully",
  "data": {
    "price": {
      "usd": 1.0,
      "brl": 5.0,
      "usd_24h_change": 0.0,
      "brl_24h_change": 0.0
    }
  }
}

Response Fields:

  • price - Price information
    • usd - Current price in USD
    • brl - Current price in BRL (Brazilian Real)
    • usd_24h_change - 24-hour price change percentage in USD
    • brl_24h_change - 24-hour price change percentage in BRL

Get Historical Price

Retrieve historical price data (OHLC - Open, High, Low, Close) for a token over a specified time period.

Get historical price

curl -X GET "https://api.example.com/api/tokens/chain/{chainId}/address/{address}/historical-price?days=30" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Path Parameters:

  • chainId - Chain ID where the token is located
  • address - Token contract address

Query Parameters:

  • days - Number of days of historical data (optional, default: 30)
    • Supported values: 30, 90, 180, 365

Example:

curl -X GET "https://api.example.com/api/tokens/chain/137/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/historical-price?days=90" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Historical price retrieved successfully",
  "data": {
    "ohlcToken": [
      [1704067200000, 1.0, 1.01, 0.99, 1.0],
      [1704153600000, 1.0, 1.02, 0.98, 1.01],
      ...
    ]
  }
}

Response Fields:

  • ohlcToken - Array of OHLC data points
    • Each array contains: [timestamp, open, high, low, close]
    • timestamp - Unix timestamp in milliseconds
    • open - Opening price
    • high - Highest price in the period
    • low - Lowest price in the period
    • close - Closing price

Note: Results are cached for 60 minutes to improve performance.

Token Types

The system supports two types of tokens:

Regular Tokens

Standard tokens like USDC, ETH, BRZ, etc.

  • Have a contract address
  • Can be traded and transferred
  • May have yield opportunities

aTokens (Yield Tokens)

Tokens representing yield positions (e.g., Aave tokens)

  • Have an underlying token address
  • Represent deposits in yield protocols
  • Accrue interest over time
  • Can be redeemed for underlying tokens

Supported Time Periods

Historical price data supports the following time periods:

  • 30 days - Last month of data
  • 90 days - Last 3 months of data
  • 180 days - Last 6 months of data
  • 365 days - Last year of data

Price Data Sources

Token prices are fetched from:

  • CoinGecko API - Primary source for price data
  • Real-time Updates - Prices are updated regularly
  • Multi-currency - Supports USD and BRL prices

Error Handling

Token Not Found

{
  "status": 404,
  "message": "Token not found"
}

This error occurs when the token address or chain ID combination doesn't exist in the supported tokens list.

Error Getting Token Price

{
  "status": 500,
  "message": "Error getting token price"
}

This error occurs when there's an issue fetching price data from the price provider.

Error Getting Historical Price

{
  "status": 500,
  "message": "Error getting historical price"
}

This error occurs when there's an issue fetching historical price data.

Complete Flow Example

Here's a complete example of using token endpoints:

# 1. Get all supported tokens
curl -X GET https://api.example.com/api/tokens \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Get current price of a specific token
curl -X GET https://api.example.com/api/tokens/chain/137/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/price \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Get historical price data (30 days)
curl -X GET "https://api.example.com/api/tokens/chain/137/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/historical-price?days=30" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 4. Get historical price data (90 days)
curl -X GET "https://api.example.com/api/tokens/chain/137/address/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/historical-price?days=90" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Important Notes

  1. Token Address Format: Token addresses are case-insensitive. Both uppercase and lowercase addresses work.

  2. Chain ID: Make sure to use the correct chain ID for the token. The same token may exist on multiple chains with different addresses.

  3. Price Updates: Prices are updated regularly but may have slight delays. For real-time trading, consider using other price sources.

  4. Historical Data: Historical price data is provided in OHLC (Open, High, Low, Close) format, suitable for creating price charts.

  5. Caching: Historical price data is cached for 60 minutes. Current prices are fetched in real-time.

  6. Supported Tokens: Only tokens in the supported tokens list have price data available. Check the tokens list first.

  7. aTokens: Yield tokens (aTokens) have price data based on their underlying token, adjusted for accrued interest.

  8. Price Changes: 24-hour price changes are calculated as percentage changes from 24 hours ago.

  9. Multi-chain Support: Tokens can exist on multiple chains. Use the correct chain ID and address combination.

  10. CoinGecko Integration: Price data comes from CoinGecko. Some tokens may not have price data if they're not listed on CoinGecko.

  11. BRL Conversion: BRL prices are calculated based on USD prices and current exchange rates.

  12. Data Granularity: Historical data granularity depends on the time period:

    • 30 days: Daily data
    • 90 days: Daily data
    • 180 days: Daily data
    • 365 days: Daily data

Use Cases

Token endpoints are useful for:

  • Portfolio Tracking - Get current prices for all tokens in your portfolio
  • Price Charts - Use historical data to create price charts
  • Price Alerts - Monitor price changes and set up alerts
  • Token Discovery - Discover available tokens and their properties
  • Yield Analysis - Compare prices between regular tokens and their aToken equivalents
  • Multi-currency Support - Get prices in both USD and BRL

Security Considerations

  1. Price Verification: Always verify prices from multiple sources for critical operations.

  2. Cache Awareness: Be aware that historical data is cached. For real-time data, use current price endpoints.

  3. Token Validation: Verify token addresses before using them in transactions to avoid scams.

  4. Chain Verification: Always verify the chain ID matches the token address to avoid using wrong tokens.

  5. Price Impact: Large trades may affect token prices. Consider price impact when making large transactions.

  6. Data Accuracy: While prices are updated regularly, there may be brief delays. For high-frequency trading, use dedicated price feeds.

Was this page helpful?