# How AutoHedge Performs Token Discovery with Jupiter: API Integration Guide

> Learn how AutoHedge performs token discovery using the Jupiter API. This guide details symbol searches, mint address lookups, and batch queries for Solana tokens. Explore the AutoHedge repository for code.

- Repository: [Swarms/AutoHedge](https://github.com/The-Swarm-Corporation/AutoHedge)
- Tags: how-to-guide
- Published: 2026-09-09

---

**AutoHedge discovers Solana-based tokens by querying the Jupiter Tokens API V2 through the `search_tokens` function in [`autohedge/tools/jupiter_search.py`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/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`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/jupiter_search.py)

The token discovery logic lives in [`autohedge/tools/jupiter_search.py`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/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`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/autohedge/tools/__init__.py)** for convenient package-level imports. Additionally, **[`autohedge/tools/tools_registry.py`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/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:

```python

# 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`](https://github.com/The-Swarm-Corporation/AutoHedge/blob/main/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.