@vinitech-pkg/easy-cripto-logos

Resolve logo URLs for blockchains and ERC-20 tokens using the TrustWallet Assets repository served via jsDelivr CDN, pinned to a fixed commit hash — never @master.

Installation

npm install @vinitech-pkg/easy-cripto-logos

pnpm add @vinitech-pkg/easy-cripto-logos

yarn add @vinitech-pkg/easy-cripto-logos

Peer dependency: ethers v6 is required for EIP-55 address checksumming.

npm install ethers@^6

Supported Chains

| Canonical name | Accepted aliases | TrustWallet directory | |----------------|-------------------------------|-----------------------| | ethereum | eth | ethereum | | polygon | matic | polygon | | bsc | bnb, binance-smart-chain | smartchain | | arbitrum | arbitrum-one | arbitrum | | avalanche | avax | avalanchec | | optimism | op | optimism | | tron | trx | tron |

All aliases are case-insensitive. An unsupported value throws an error with the full list of valid options.

Usage

Native token logo

import { getNativeLogoUrl } from "@vinitech-pkg/easy-cripto-logos";

const ethLogo = getNativeLogoUrl({ chain: "ethereum" });
// https://cdn.jsdelivr.net/gh/trustwallet/assets@4eb147bf.../blockchains/ethereum/info/logo.png

const maticLogo = getNativeLogoUrl({ chain: "matic" }); // alias for polygon

ERC-20 token logo

import { getTokenLogoUrl } from "@vinitech-pkg/easy-cripto-logos";

const usdtLogo = getTokenLogoUrl({
  chain: "ethereum",
  address: "0xdac17f958d2ee523a2206206994597c13d831ec7",
});
// Address is automatically converted to EIP-55 checksum format.
// https://cdn.jsdelivr.net/gh/trustwallet/assets@.../blockchains/ethereum/assets/0xdAC17F958D2ee523a2206206994597C13D831ec7/logo.png

resolveLogo — unified resolver

import { resolveLogo } from "@vinitech-pkg/easy-cripto-logos";

// No address → native token logo
resolveLogo({ chain: "ethereum" });

// Address provided → token logo with checksummed address
resolveLogo({
  chain: "polygon",
  address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
});

// customLogoUrl provided → returned as-is, takes priority over everything
resolveLogo({
  chain: "bsc",
  address: "0x55d398326f99059fF775485246999027B3197955",
  customLogoUrl: "https://my-cdn.example.com/usdt.png",
});
// → "https://my-cdn.example.com/usdt.png"

Priority: customLogoUrl > token (address) > native chain logo.

API Reference

getNativeLogoUrl(options: NativeOptions): string

Returns the CDN URL for a chain's native token logo.

| Parameter | Type | Description | |-----------|----------|------------------------------------------| | chain | string | Chain name or alias (e.g. "eth", "matic") |

getTokenLogoUrl(options: TokenOptions): string

Returns the CDN URL for an ERC-20 token logo. The address is automatically converted to EIP-55 checksum format.

| Parameter | Type | Description | |-----------|----------|--------------------------------------------------| | chain | string | Chain name or alias | | address | string | Token contract address (any casing accepted) |

resolveLogo(input: LogoInput): string

Unified resolver that selects the correct URL based on available inputs.

| Parameter | Type | Description | |-----------------|-----------|------------------------------------------------------------------| | chain | string | Chain name or alias | | address | string? | Token contract address — if provided, returns token logo | | customLogoUrl | string? | Override URL — returned as-is when provided, highest priority |

normalizeChain(chain: string): SupportedChain

Converts any chain name or alias to its canonical SupportedChain value. Throws if the chain is not supported.

toChecksum(address: string): string

Converts an Ethereum address to its EIP-55 checksummed form using ethers.getAddress.

React Example with Fallback

import { resolveLogo } from "@vinitech-pkg/easy-cripto-logos";

interface TokenLogoProps {
  chain: string;
  address?: string;
  customLogoUrl?: string;
  alt: string;
  size?: number;
}

export function TokenLogo({ chain, address, customLogoUrl, alt, size = 32 }: TokenLogoProps) {
  const src = resolveLogo({ chain, address, customLogoUrl });

  return (
    <img
      src={src}
      alt={alt}
      width={size}
      height={size}
      onError={(e) => {
        (e.currentTarget as HTMLImageElement).src = "/fallback-token.png";
      }}
    />
  );
}

// Native token
<TokenLogo chain="ethereum" alt="ETH" />

// ERC-20 token
<TokenLogo chain="polygon" address="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" alt="USDC" />

// Custom override
<TokenLogo chain="bsc" customLogoUrl="https://my-cdn.example.com/usdt.png" alt="USDT" />

Updating the TrustWallet Commit

All CDN URLs are pinned to a fixed commit hash from the TrustWallet Assets repository. This guarantees URL stability across builds and deployments.

To update to a newer snapshot:

1. Open https://github.com/trustwallet/assets/commits/master
2. Click the commit you want to pin and copy the full SHA (40 characters)
3. Open src/constants.ts and replace the value of TRUSTWALLET_COMMIT:

// src/constants.ts
export const TRUSTWALLET_COMMIT = "YOUR_NEW_COMMIT_SHA_HERE";

4. Rebuild the package:

npm run build

5. Publish the new version:

npm publish --access public

Build

npm install
npm run build

Output in dist/:

| File | Format | |-------------------|------------| | index.mjs | ESM | | index.js | CommonJS | | index.d.mts | TS types (ESM) | | index.d.ts | TS types (CJS) |

Publish

npm publish --access public

License

MIT