How AutoHedge Performs Token Discovery with Jupiter: API Integration Guide

AutoHedge discovers Solana-based tokens by querying the Jupiter Tokens API V2 through the search_tokens function in autohedge/tools/jupiter_search.py, supporting symbol-based searches, mint address lookups, and batch queries of up to 100 tokens with optional API key authentication.

AutoHedge leverages the Jupiter aggregator to locate Solana token metadata essential for automated hedging strategies. The repository implements a clean abstraction over Jupiter's REST API, handling authentication, query validation, and error management through a single utility function that integrates with the broader tool registry.

Core Implementation in jupiter_search.py

The token discovery logic lives in autohedge/tools/jupiter_search.py, which provides a synchronous interface to Jupiter's token database.

The search_tokens Function

The search_tokens(query: str) → str function serves as the primary entry point for token lookups. It accepts a string parameter representing either a token symbol, full name, or mint address, and returns a JSON-encoded string containing an array of matching token objects. Each response includes critical fields such as id, symbol, name, decimals, and usdPrice required for downstream trading calculations.

API Endpoint and Authentication

The function targets the Jupiter Tokens API V2 at https://api.jup.ag/tokens/v2/search. Authentication is optional but recommended for production workloads: if the JUPITER_API_KEY environment variable is set, the function injects it into the request headers as x-api-key to avoid rate limiting.

Request Execution and Timeouts

An httpx client executes a GET request with a strict 10-second timeout. The implementation validates inputs before making network calls, immediately returning "[]" for empty or whitespace-only queries while emitting a warning via loguru to prevent unnecessary API usage.

Query Types and Batch Processing

AutoHedge supports flexible search patterns through Jupiter's versatile query parameter.

Single Token Lookups

Users can search by token symbols like "USDC", full names, or specific mint addresses such as "So11111111111111111111111111111111111111112" (wrapped SOL). The function handles both exact matches and partial string matches against Jupiter's indexed token metadata.

Batch Token Discovery

The implementation supports comma-separated mint addresses for efficient batch retrieval, handling up to 100 addresses in a single request. This reduces network overhead when initializing portfolios or analyzing multiple assets simultaneously across complex hedging strategies.

Error Handling and Edge Cases

The module implements robust error management for production reliability.

Network-related exceptions are caught and re-raised as httpx.HTTPError instances, providing consistent exception handling across the codebase. The loguru logging framework tracks query attempts and failures, enabling observability without exposing sensitive API keys in log output.

Module Integration and Exports

The search_tokens utility integrates into AutoHedge's broader tool ecosystem through explicit module design.

The function is re-exported in autohedge/tools/__init__.py for convenient package-level imports. Additionally, autohedge/tools/tools_registry.py registers the function, making it available to CLI interfaces and automated worker modules that execute hedging strategies.

Implementation Examples

The following patterns demonstrate practical usage of the Jupiter token discovery system:

# Import the helper directly from the package

from autohedge.tools import search_tokens

# 1️⃣ Search by token symbol

usdc_json = search_tokens("USDC")
print(usdc_json)   # → JSON string with USDC metadata

# 2️⃣ Search by mint address (single or comma‑separated)

mint_json = search_tokens("So11111111111111111111111111111111111111112")
print(mint_json)

# 3️⃣ Batch lookup using multiple mint addresses

batch_json = search_tokens(
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v,"
    "So11111111111111111111111111111111111111112"
)
print(batch_json)

Summary

• Token discovery occurs through the Jupiter Tokens API V2 endpoint at https://api.jup.ag/tokens/v2/search.
• The search_tokens function in autohedge/tools/jupiter_search.py handles all query types including symbols, names, and mint addresses.
• Batch operations support up to 100 comma-separated mint addresses for efficient multi-token lookups.
• Optional authentication via the JUPITER_API_KEY environment variable prevents rate limiting by injecting the x-api-key header.
• Robust error handling converts network failures to httpx.HTTPError and validates empty inputs before API calls.

Frequently Asked Questions

What API does AutoHedge use for token discovery?

AutoHedge uses the Jupiter Tokens API V2, specifically the /tokens/v2/search endpoint. This API returns structured metadata including token symbols, decimals, current USD prices, and mint addresses necessary for Solana trading operations.

Do I need an API key to use the Jupiter token search?

No, an API key is optional. The Jupiter API works without authentication, but setting the JUPITER_API_KEY environment variable adds the x-api-key header to requests, which prevents rate limiting and ensures higher availability for production AutoHedge deployments.

How does AutoHedge handle empty or invalid search queries?

The search_tokens function validates input before making network requests. Empty or whitespace-only strings immediately return "[]" without hitting the API, and the system emits a warning via loguru to alert developers of the skipped call.

Can I search for multiple tokens at once?

Yes, the implementation supports batch lookups by passing comma-separated mint addresses in the query string. This allows retrieval of up to 100 token records in a single HTTP request, optimizing performance when initializing token lists or portfolio compositions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}