Token Vector Search API - Documentation

Overview

The Token Vector Search API provides a production-ready endpoint for searching cryptocurrency tokens by name and image similarity. The API uses vector similarity search (CLIP embeddings) combined with database name matching to find the most relevant tokens.

Base URL: https://truip4.brettevanson.com

Authentication

All API endpoints (except health check) require authentication using an API key.

X-API-Key: your_api_key_here

Or using Authorization header:

Authorization: Bearer your_api_key_here

Rate Limiting

Each API key has configurable rate limits:

Per-minute limit: Default 60 requests/minute
Per-day limit: Default 10,000 requests/day

When rate limits are exceeded, the API returns a 429 Too Many Requests response.

Endpoints

GET `/health`

Description: Check if the API is running.

Authentication: Not required

Example:

curl https://truip4.brettevanson.com/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000000"
}
                    

POST `/api/v1/search`

Description: Search for tokens by name and image similarity.

Authentication: Required

Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
`token_name`	string	Required	Token name to search for in the database
`logo`	file	Required	Image file (PNG, JPG, WEBP, etc.) to search for similar tokens
`limit`	integer	Optional	Maximum total results to return (default: 20)
`vector_search_limit`	integer	Optional	Number of vector search results (default: 10)
`name_search_limit`	integer	Optional	Number of name search results (default: 10)

Example Request (cURL)

curl -X POST https://truip4.brettevanson.com/api/v1/search \
  -H "X-API-Key: your_api_key_here" \
  -F "token_name=USDT" \
  -F "logo=@/path/to/token_logo.png" \
  -F "limit=20"
                    

Example Request (Python)

import requests

url = "https://truip4.brettevanson.com/api/v1/search"
headers = {"X-API-Key": "your_api_key_here"}

files = {
    'logo': ('token_logo.png', open('token_logo.png', 'rb'), 'image/png')
}
data = {
    'token_name': 'USDT',
    'limit': 20
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
                    

Response Format

{
  "success": true,
  "query": {
    "token_name": "USDT",
    "image_provided": true
  },
  "results": [
    {
      "token_id": 123,
      "token_name": "Tether USD",
      "token_symbol": "USDT",
      "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "chain": "ethereum",
      "logo_url": "https://example.com/usdt.png",
      "similarity_score": 95.23,
      "match_type": "vector_similarity"
    }
  ],
  "count": 1,
  "metadata": {
    "vector_search_performed": true,
    "db_search_performed": true,
    "response_time_ms": 245
  }
}
                    

GET `/api/v1/stats`

Description: Get usage statistics for your API key.

Authentication: Required

Example:

curl -X GET https://truip4.brettevanson.com/api/v1/stats \
  -H "X-API-Key: your_api_key_here"
                    

Error Responses

All errors follow a consistent format:

{
  "error": "Error type",
  "message": "Human-readable error message"
}
                

Common HTTP status codes:

200 - Success
400 - Bad Request (invalid input)
401 - Unauthorized (invalid/missing API key)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

How It Works

The search endpoint performs two types of searches:

Database Name Search: Searches the database for tokens matching the provided token_name using SQL LIKE queries.
Vector Similarity Search: Uses CLIP (Contrastive Language-Image Pre-Training) to generate embeddings from the provided image and searches for similar token images using FAISS vector index.
Result Combination: Results from both searches are combined, deduplicated by token ID, and sorted by relevance.

🧪 Test the API

Try the health check endpoint to verify the API is running: