# Token Logo Fetcher API

> Free API for cryptocurrency token logos. No auth required. CORS enabled.

Base URL: https://logo.octav.fi

## GET /api/icon/{token}.png

Returns raw image bytes. Use as an `<img>` src or download directly.

`{token}` accepts: CoinGecko coin ID (`bitcoin`, `usd-coin`), ticker symbol (`btc`, `eth`), contract address (`0xa0b8...`), or Pendle PT/YT/SY derivative address.

The `.png` extension is optional.

Response: image/png or image/jpeg, cached 24h.

Examples:
- /api/icon/btc.png — Bitcoin logo
- /api/icon/ethereum.png — Ethereum logo
- /api/icon/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png — USDC by address

## GET /api/search?q={query}

Instant token search (in-memory, no rate limit). Returns up to 8 matches.

Parameters:
- q (required): search string (name or symbol)

Response: JSON array
```json
[{"id": "ethereum", "name": "Ethereum", "symbol": "ETH"}]
```

## GET /api/lookup-id?id={coinId}

Full token details by CoinGecko coin ID.

Parameters:
- id (required): CoinGecko coin ID

Response: JSON
```json
{
  "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..."},
    {"chain": "Base", "address": "0x8335..."}
  ]
}
```

## GET /api/lookup?address={contractAddress}

Look up token by contract address (any chain). Also resolves Pendle PT/YT/SY derivative addresses to the underlying token.

Parameters:
- address (required): contract address (including Pendle derivatives)

Response: same format as /api/lookup-id. For Pendle derivatives, includes a `pendle` field:
```json
{
  "pendle": {
    "type": "PT",
    "symbol": "PT-stETH-30MAR2023",
    "chain": "Ethereum",
    "note": "This is a Pendle PT token. Showing logo for underlying asset: Lido Staked Ether"
  }
}
```

## GET /api/proxy-image?url={imageUrl}&format={fmt}&size={px}

Download and convert token logo images. Proxies through server (avoids CORS).

Parameters:
- url (required): source image URL
- format (optional): png, webp, jpeg, ico
- size (optional): resize to NxN pixels (max 1024)
- filename (optional): download filename

## GET /api/status

Health check. Returns index readiness.

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

## Rate Limits

- /api/search: no limit (in-memory)
- /api/icon/: cached 24h on CDN, then proxies CoinGecko (30 calls/min free tier)
- /api/lookup-id, /api/lookup: proxies CoinGecko (30 calls/min)

## Common Patterns

Embed logo in HTML:
```html
<img src="https://logo.octav.fi/api/icon/btc.png" width="32" height="32" />
```

Embed in Markdown:
```markdown
![BTC](https://logo.octav.fi/api/icon/btc.png)
```

Fetch token data then display logo:
```javascript
const res = await fetch("https://logo.octav.fi/api/lookup-id?id=bitcoin");
const data = await res.json();
// data.image — direct CDN URL (highest quality)
// data.chains — all chains with contract addresses
```

Get logo as WebP at 64px for performance:
```
/api/proxy-image?url={data.image}&format=webp&size=64
```

## Pendle Finance Support

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

If the underlying token isn't on CoinGecko, the logo is served from Pendle's own CDN.

```javascript
// PT-stETH resolves to Lido Staked Ether
const res = await fetch("https://logo.octav.fi/api/lookup?address=0xcf44e8402a99db82d2acccc4d9354657be2121db");
const data = await res.json();
// data.name === "Lido Staked Ether"
// data.pendle.type === "PT"
```