API Documentation

Free API for fetching cryptocurrency token logos. No API key required. All responses include CORS headers.

Quick Start

Embed any token logo directly in your app:

<img src="https://logo.octav.fi/api/icon/btc.png" />
<img src="https://logo.octav.fi/api/icon/ethereum.png" />
<img src="https://logo.octav.fi/api/icon/sol.png" />

Pendle Support

Pendle PT, YT, and SY derivative addresses automatically resolve to the underlying token's logo. Supports 1,700+ derivatives across 8 chains: Ethereum, Arbitrum, Optimism, BSC, Base, Mantle, Sonic, and HyperEVM.

How it works: When you look up a Pendle derivative address, the API resolves it to the underlying asset and returns that token's logo from CoinGecko. If the underlying isn't on CoinGecko, the logo is served directly from Pendle's CDN. The Pendle index refreshes hourly, with a live on-demand fallback for brand new markets.

Examples

# PT-stETH on Ethereum resolves to Lido Staked Ether logo
/api/icon/0xcf44e8402a99db82d2acccc4d9354657be2121db.png

# PT-AVLT on HyperEVM (not on CoinGecko) — served from Pendle CDN
/api/lookup?address=0xd1c248248552e1d33afafd5893beded07da0ee95

# CLI works too
token-logo 0xcf44e8402a99db82d2acccc4d9354657be2121db
token-logo info 0xd1c248248552e1d33afafd5893beded07da0ee95

Responses for Pendle derivatives include a pendle field with the derivative type (PT/YT/SY), symbol, and chain.

CLI Tool

Download token logos directly from your terminal. Zero dependencies, works with Node.js 18+.

npm token-logo

Install

# Run without installing
npx token-logo btc

# Or install globally
npm install -g token-logo

Commands

# Download a logo (by symbol, ID, or contract address)
token-logo btc
token-logo ethereum
token-logo 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

# Choose format and size
token-logo eth -f webp -s 128
token-logo sol -f ico

# Save to a specific folder
token-logo usdc -o ./logos

# Search for tokens
token-logo search uniswap

# Show token details + all chain addresses
token-logo info usdc

# Pendle PT/YT/SY derivatives
token-logo 0xcf44e8402a99db82d2acccc4d9354657be2121db
token-logo info 0xd1c248248552e1d33afafd5893beded07da0ee95

# Pipe to file
token-logo btc --stdout > bitcoin.png

Options

Flag		Description
-f, --format	optional	Output format: `png`, `webp`, `jpeg`, `ico` (default: png)
-s, --size	optional	Resize to NxN pixels (default: original)
-o, --output	optional	Output directory (default: current dir)
--stdout	optional	Write image bytes to stdout for piping

Endpoints

GET /api/icon/:token

Returns the token logo image directly. Use this as an image source in your HTML, markdown, or app. Supports Pendle PT/YT/SY addresses (resolves to underlying token). Images are served at original quality and cached for 24 hours.

Param		Description
:token	required	CoinGecko coin ID, symbol, contract address, or Pendle PT/YT/SY address. Extension (.png) is optional.

Examples

# By symbol
/api/icon/btc.png
/api/icon/eth.png

# By CoinGecko ID
/api/icon/bitcoin.png
/api/icon/usd-coin.png

# By contract address
/api/icon/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png

Response

Raw image bytes with Content-Type: image/png (or jpeg) and Cache-Control: public, max-age=86400.

GET /api/search

Search tokens by name or symbol. Returns instantly from an in-memory index (no external API calls). Useful for building autocomplete.

Param		Description
q	required	Search query (name or symbol)

Example

/api/search?q=eth

{
  "id": "ethereum",
  "name": "Ethereum",
  "symbol": "ETH"
}

GET /api/lookup-id

Get full token details by CoinGecko coin ID. Returns logo URL, price, rank, and all chains with contract addresses.

Param		Description
id	required	CoinGecko coin ID (e.g. `bitcoin`, `usd-coin`)

Example

/api/lookup-id?id=usd-coin

{
  "name": "USDC",
  "symbol": "USDC",
  "image": "https://...original/USDC.png",
  "market_cap_rank": 6,
  "current_price": 1.0,
  "chain": "Ethereum",
  "address": "0xa0b8...",
  "chains": [
    { "chain": "Ethereum", "address": "0xa0b8..." },
    { "chain": "Solana", "address": "EPjF..." },
    ...
  ]
}

GET /api/lookup

Look up a token by contract address. Searches across all chains, including Pendle PT/YT/SY derivatives. Returns the same response format as /api/lookup-id, with an additional pendle field for derivatives.

Param		Description
address	required	Contract address (EVM, Solana, etc.)

Example

/api/lookup?address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

GET /api/proxy-image

Download and optionally convert a token logo image. Proxies through the server to avoid CORS issues and supports format conversion.

Param		Description
url	required	Source image URL
format	optional	Output format: `png`, `webp`, `jpeg`, `ico`
size	optional	Resize to NxN pixels (max 1024)
filename	optional	Download filename

Supported Formats

pngLossless, transparency

webpSmaller size, transparency

jpegSmallest, no transparency

icoFavicons (64x64)

Example

# Convert to WebP at 128x128
/api/proxy-image?url=...&format=webp&size=128

# Download as ICO for favicon
/api/proxy-image?url=...&format=ico&filename=favicon.ico

GET /api/status

Health check. Returns whether the token index is ready.

Example

/api/status

{
  "ready": true,
  "error": null,
  "size": 22611,
  "pendle": { "ready": true, "size": 1785 }
}

Rate Limits

This API proxies CoinGecko's free tier which allows 30 calls/min. The /api/search endpoint is instant (in-memory) and has no rate limit. The /api/icon/ endpoint is cached for 24 hours on Vercel's CDN, so repeated requests for the same token are fast.

Image Quality

All images are served at original resolution from CoinGecko's CDN — the highest quality available. This is typically 500x500 for major tokens, though it varies by what was uploaded. Use the size parameter on /api/proxy-image to resize as needed.

GET /api/card/:token

Generates a 1200x630 OG social card image with the token's logo, name, symbol, price, 24h change, and rank. Drop it in a <meta og:image> tag for rich social previews. Cached for 1 hour.

Param		Description
:token	required	Symbol, CoinGecko ID, contract address, or Pendle derivative. Extension (.png) is optional.

Usage

<!-- Add to your HTML <head> for rich social previews -->
<meta property="og:image" content="https://logo.octav.fi/api/card/btc.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://logo.octav.fi/api/card/eth.png" />

# Works with any token
/api/card/bitcoin.png
/api/card/sol.png
/api/card/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png

Preview

Each card includes: token logo (200x200), name, symbol, current USD price, 24h change (green/red), market cap rank, and a subtle gradient background.

Try /api/card/bitcoin.png →

GET /api/favicon/:token

Returns a properly sized PNG favicon for any token. Drop it in a single <link> tag and your dApp's favicon is always the current token logo. Supports symbols, IDs, contract addresses, and Pendle derivatives.

Param		Description
:token	required	Symbol, CoinGecko ID, or contract address. Extension (.ico, .png) is optional.
size	optional	Icon size in pixels: 16, 32, 48, or 64 (default: 32)

Usage

<!-- One line in your HTML — that's it -->
<link rel="icon" href="https://logo.octav.fi/api/favicon/eth" />

<!-- Multiple sizes for best display -->
<link rel="icon" sizes="16x16" href=".../api/favicon/btc?size=16" />
<link rel="icon" sizes="32x32" href=".../api/favicon/btc?size=32" />

<!-- Works with any token -->
/api/favicon/sol
/api/favicon/usdc?size=48
/api/favicon/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

Browser Extension

Chrome extension for quick token logo lookups. Right-click any selected text to look it up, or click the toolbar icon to search manually.

Chrome Token Logo Fetcher Extension

Features: search by symbol, name, or contract address. Download logos directly. Supports Pendle PT/YT/SY derivatives. Right-click context menu for instant lookups.

Download Extension (.zip)

Install

# 1. Download and unzip the extension
# 2. Open chrome://extensions in Chrome
# 3. Enable "Developer mode" (top-right toggle)
# 4. Click "Load unpacked" and select the unzipped folder
# 5. Pin the extension to your toolbar

Usage

# Toolbar popup
Click the extension icon → type a token → click Go

# Right-click context menu
Select any text (address, symbol, etc.) → Right-click
→ "Look up token logo" → popup opens with results

# Actions
Download — save the logo image to your computer
Open — view the token on the web app
Copy URL — copy the direct API image URL

For AI Agents

Machine-readable versions of this documentation for use with AI coding assistants:

llms.txt Plain text API reference following the llms.txt standard. Works with any LLM. skill.md Claude Code skill file. Install in your project to give Claude access to this API.

Claude Code users: Download skill.md and place it in your .claude/skills/ directory. Claude will automatically use this API when you need token logos.

Other AI tools: Point your agent at https://logo.octav.fi/llms.txt as a context source.

Token Logo Fetcher | Data from CoinGecko