ChipaDocs

Trending Tokens

Trending Tokens

Guide to the trending tokens endpoint, its normalized response format, fallback behavior, and troubleshooting for get_trending_tokens() in AxiomTradeAPI-py.

Usage

Overview

AxiomTradeAPI-py uses the Axiom trending-v2 endpoint:

  • Endpoint: https://api3.axiom.trade/new-trending-v2
  • Supported periods commonly include 5m, 1h, 6h, 24h, and 7d
  • The SDK normalizes the raw array response into a dictionary-based token list for easier use

Basic usage

from axiomtradeapi import AxiomTradeClient
import os

client = AxiomTradeClient(
    auth_token=os.getenv("AXIOM_ACCESS_TOKEN"),
    refresh_token=os.getenv("AXIOM_REFRESH_TOKEN")
)

trending = client.get_trending_tokens("1h")
print(f"Found {len(trending.get('tokens', []))} tokens")

Response format

The SDK returns a backward-compatible dictionary with these keys:

  • tokens - normalized list of token dictionaries
  • data - alias of the normalized token list
  • timePeriod - actual period returned by the server
  • requestedTimePeriod - the period you asked for
  • fallbackUsed - whether a safer fallback period was used
  • attemptedTimePeriods - the periods tried in order
  • endpoint - always set to new-trending-v2
result = client.get_trending_tokens("24h")

print(result["requestedTimePeriod"])
print(result["timePeriod"])
print(result["fallbackUsed"])
print(result["attemptedTimePeriods"])

Why fallback may happen

Axiom occasionally returns transient 500 errors for some time ranges even while authentication is valid. When that happens, the SDK:

  1. Retries the same request automatically
  2. Refreshes session state when needed
  3. Falls back to the nearest stable period

This makes the call more reliable for live bots and dashboards.

Common fields in each token

Normalized token entries may include fields such as:

  • pairAddress
  • tokenAddress
  • tokenName
  • tokenTicker
  • imageUrl
  • createdAt
  • website
  • twitter
  • liquidityUsd
  • priceUsd
  • priceChange5m
  • priceChange1h
  • priceChange24h
  • holderCount
  • marketCapUsd

Because the upstream payload is array-based and may evolve, the SDK also preserves the original row under raw.

Automatic session initialization

The client attempts a browser-style bootstrap automatically before trending calls. This reduces failures in environments where Axiom expects the caller to be registered as an active browser session. You can still call client.connect manually if you want to prewarm the session yourself.

Best practice

For production bots, check fallbackUsed before making timeframe-sensitive decisions:

result = client.get_trending_tokens("7d")

if result.get("fallbackUsed"):
    print("Using fallback data due to upstream instability")

Troubleshooting

500 Internal Server Error

You may see an error like this:

Exception: Failed to get trending tokens: 500 Server Error

This is usually caused by temporary instability in the upstream Axiom trending service for a specific time range.

The SDK mitigates this with:

  • Automatic retries
  • Session reinitialization when needed
  • Browser-style session bootstrap before trending requests
  • Fallback to a working time period
  • Structured diagnostic responses when the service is fully unavailable

404 Not Found

If you were using an older version of the package, the client may still be pointing to the retired trending endpoint.

Fix: upgrade to the latest version.

pip install -U axiomtradeapi
from axiomtradeapi import AxiomTradeClient
import os

client = AxiomTradeClient(
    auth_token=os.getenv("AXIOM_ACCESS_TOKEN"),
    refresh_token=os.getenv("AXIOM_REFRESH_TOKEN")
)

result = client.get_trending_tokens("1h")
print(result.get("count", len(result.get("tokens", []))))

Inspecting fallback behavior

result = client.get_trending_tokens("24h")

print("requested:", result.get("requestedTimePeriod"))
print("actual:", result.get("timePeriod"))
print("fallback:", result.get("fallbackUsed"))
print("attempted:", result.get("attemptedTimePeriods"))

Structured error handling

If the server remains unavailable even after retries and host failover, the SDK returns a safe result object instead of crashing by default. Example keys:

  • success
  • serviceAvailable
  • error
  • statusCode
  • failingUrl
  • attemptedTimePeriods
  • attemptedUrls

You can still opt into strict exceptions when needed:

result = client.get_trending_tokens("1h", raise_on_error=True)

If issues continue

  1. Verify your access token and refresh token are valid
  2. Upgrade to the latest package release
  3. Try 1h or 5m first to confirm upstream availability
  4. Retry after a short delay if the Axiom API is unstable
  5. Inspect the returned error and attemptedUrls fields for diagnostics

If your bot depends on strict timeframe fidelity, check fallbackUsed and handle that case explicitly.