assets-logo

Cryptocurrency logo repository with hash-based naming for unlimited caching.

Features

Content-hash naming: Logo files are named by their content hash, enabling unlimited CDN caching
TrustWallet integration: Automatically syncs logos from TrustWallet assets repository
Override system: Custom logos can override default ones via GitHub Issues
Symbol mapping: Complete symbol-to-address mapping for easy token lookup
GitHub Actions: Automated workflows for syncing and override management

Architecture

assets-logo/
├── default.json              # Raw logo data from TrustWallet (no overrides)
├── symbols.json             # Symbol → chain+address mapping (9539 symbols)
├── overrides/              # Custom override rules and files
│   ├── common/            # Common logos (shared across chains)
│   ├── blockchains/       # Chain-specific override logos
│   └── override.json     # Override rules configuration
├── .metadata/
│   └── manifests/
│       └── latest.json   # Final manifest with full paths (for frontend)
├── blockchains/           # Actual logo files (synced from TrustWallet)
│   └── {chain}/
│       └── {hash}.png
└── .trustwallet/         # Cloned Trust Wallet repository (auto-managed)

Core Concepts

Default Logos

Default logos are synced from the TrustWallet/assets repository. These are the source of truth for all token logos.

Overrides System

The override system allows you to replace default logos with custom ones. There are two types:

Type	Location	Purpose
Common	`overrides/common/`	Shared logos for cross-chain tokens (e.g., USDT on all chains)
Blockchains	`overrides/blockchains/{chain}/`	Chain-specific overrides

Override Resolution Order

When resolving a logo, the system checks in this order:

overrides/common/ (symbol-based cross-chain)
overrides/blockchains/ (specific chain+address)
blockchains/ (default from TrustWallet)

Files

default.json

Raw logo data from TrustWallet without any overrides. This file maps chains and token addresses to their logo hashes.

Format:

{
  "version": "2026-02-06-03",
  "updatedAt": "2026-02-06T14:36:23.613Z",
  "logos": {
    "ethereum": {
      "logo": "356942065ff36a87.png",
      "native": "356942065ff36a87.png",
      "0xdac17f958d2ee523a2206206994597c13d831ec7": "1c2ecfc8c08a821a.png"
    }
  }
}

symbols.json

Complete mapping from token symbols to their chain+address combinations. Generated from TrustWallet's token lists.

Format:

{
  "updatedAt": "2026-02-06T14:36:42.400Z",
  "symbols": [
    {
      "symbol": "USDT",
      "chains": [
        { "chain": "ethereum", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7" },
        { "chain": "tron", "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" }
      ]
    }
  ]
}

override.json

Configuration file that defines override rules. This is where you specify which logos to override.

Format:

{
  "common": {
    "token": [
      {
        "symbol": "USDT",
        "chains": ["ethereum", "tron", "binance"],
        "logo": "a1b2c3d4e5f6g7h8.png"
      }
    ],
    "logo": {
      "ethereum": "x1y2z3a4b5c6d7e8.png",
      "binance": "c6d7e8f9a0b1c2d3.png"
    }
  },
  "blockchains": {
    "ethereum": {
      "native": "p2o3i4u5y6t7r8e9.png",
      "0xdac17f958d2ee523a2206206994597c13d831ec7": "w3e4r5t6y7u8i9o0.png"
    }
  }
}

Sections:

Section	Field	Description
`common.token`	`symbol`	Token symbol (e.g., "USDT")
	`chains`	Array of chains or `["ALL"]` for all chains
	`logo`	Filename in `overrides/common/`
`common.logo`	`{chain}`	Chain branding logo → filename in `overrides/common/`
`blockchains`	`{chain}`	Chain-specific overrides
	`{address}`	Token address → logo filename

.metadata/manifests/latest.json

The final manifest used by frontends. Contains full paths and combines defaults with overrides.

Format:

{
  "version": "2026-02-06-03",
  "updatedAt": "2026-02-06T14:41:25.453Z",
  "logos": {
    "ethereum": {
      "logo": "blockchains/ethereum/356942065ff36a87.png",
      "native": "blockchains/ethereum/356942065ff36a87.png",
      "0xdac17f958d2ee523a2206206994597c13d831ec7": "overrides/common/usdt-custom.png"
    }
  }
}

GitHub Issue Override

You can submit logo overrides via GitHub Issues using one of two templates:

Templates

Template	Purpose	Label
Token Logo Override	Override a token's logo on specific chains	`token-override`
Chain Logo Override	Override a chain's branding logo	`chain-override`

Token Override Fields

Field	Type	Description
`Input Type`	dropdown	"Token Symbol" or "Token Address"
`Token Symbol`	input	Token symbol (e.g., USDT) - for Symbol mode
`Token Address`	input	Contract address - for Address mode
`Chain Names`	input	`[ethereum]` (single), `[ethereum,binance]` (multiple), or `[ALL]` (all)
`Description`	textarea	Optional description

Chain Override Fields

Field	Type	Description
`Chain Name`	input	Chain name (e.g., ethereum, binance, solana)
`Description`	textarea	Optional description

How It Works

Create Issue → Select template, fill form, upload custom logo
Add Label → Template auto-adds token-override or chain-override label
Comment → Comment /process token-override or /process chain-override
Processing → Workflow downloads image, calculates hash
PR Created → Pull request is created with override rules
Merge → When PR is merged, manifest is updated automatically

Commands

Generate Default Manifest

Generate default.json from TrustWallet data:

bun run generate:default

Generate Symbol Mapping

Generate symbols.json from TrustWallet data:

bun run generate:symbols

Apply Overrides

Apply override rules and generate final manifest:

bun run apply:overrides

Sync All

Run all generation steps:

bun run sync:all

Type Check

Run TypeScript type checking:

bun run typecheck

GitHub Actions Workflows

on-issue-comment.yml

Listens for /process token-override or /process chain-override comments on issues.

Triggers:

Comment on issue starting with /process token-override
Comment on issue starting with /process chain-override

Steps:

Verify issue has correct label
Trigger respective workflow
Comment result on issue

process-token-override.yml

Processes token logo override requests. Triggered via workflow_dispatch from on-issue-comment.yml.

Trigger: workflow_dispatch with issue_number input

Steps:

Parse issue form data
Download attached image
Calculate content hash
Update override.json
Create PR

process-chain-override.yml

Processes chain logo override requests. Triggered via workflow_dispatch from on-issue-comment.yml.

Trigger: workflow_dispatch with issue_number input

Steps:

Parse issue form data
Download attached image
Calculate content hash
Update override.json → common.logo[chain]
Create PR

on-merge-override.yml

Triggers on PR merge when overrides/, default.json, or symbols.json changes.

Steps:

Check if TrustWallet has updates
Regenerate default.json and symbols.json (if needed)
Apply overrides
Update final manifest

CDN Usage

Base URL

https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest/

Logo URL Format

{baseUrl}{path}

Examples:

Type	URL
Ethereum native	`https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest/blockchains/ethereum/a1b2c3d4e5f6g7h8.png`
Ethereum USDT	`https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest/blockchains/ethereum/1c2ecfc8c08a821a.png`
Override common	`https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest/common/usdt-custom.png`

Frontend Integration

const CDN_BASE = 'https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest';

interface ChainManifest {
  logo?: string;
  native?: string;
  [address: string]: string | undefined;
}

interface LogoManifest {
  version: string;
  updatedAt: string;
  logos: Record<string, ChainManifest>;
}

async function getLogoUrl(chain: string, address: string): Promise<string | null> {
  const manifest = await fetch(`${CDN_BASE}/.metadata/manifests/latest.json`)
    .then(r => r.json()) as LogoManifest;
  
  const chainData = manifest.logos[chain];
  if (!chainData) return null;
  
  const path = chainData[address.toLowerCase()] || chainData.native;
  if (!path) return null;
  
  return `${CDN_BASE}/${path}`;
}

// Usage
const url = await getLogoUrl('ethereum', '0xdac17f958d2ee523a2206206994597c13d831ec7');
// Returns: "https://cdn.jsdmirror.com/gh/GMwalletApp/assets-logo@latest/blockchains/ethereum/1c2ecfc8c08a821a.png"

Adding a New Override via GitHub Issue

Step 1: Create Issue

Go to repository Issues → New Issue
Select Token Logo Override or Chain Logo Override template
Fill in the form:
- Token Override: Input Type, Symbol/Address, Chain Names
- Chain Override: Chain Name
Upload your logo image (PNG, JPG, GIF, WebP; max 256KB)
Submit Issue

Step 2: Trigger Processing

Template auto-adds label (token-override or chain-override)
Comment on the issue:
- For token: /process token-override
- For chain: /process chain-override
Workflow will process and create a PR

Step 3: Review & Merge

Review the created PR
Merge when ready
Final manifest will be updated automatically

Supported Chains

This repository includes logos for 184+ chains including:

Ethereum, Arbitrum, Optimism, Base
BSC, Polygon, Avalanche
Solana, Tron, Ton
And many more...

Environment Variables (GitHub Actions)

Variable	Description
`GITHUB_TOKEN`	GitHub API token for creating PRs
`GITHUB_OWNER`	Repository owner
`GITHUB_REPO`	Repository name

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.deprecations		.deprecations
.github		.github
.metadata		.metadata
blockchains		blockchains
overrides		overrides
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
OVERRIDE.md		OVERRIDE.md
README.md		README.md
bun.lock		bun.lock
default.json		default.json
package.json		package.json
symbols.json		symbols.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

assets-logo

Features

Architecture

Core Concepts

Default Logos

Overrides System

Override Resolution Order

Files

default.json

symbols.json

override.json

.metadata/manifests/latest.json

GitHub Issue Override

Templates

Token Override Fields

Chain Override Fields

How It Works

Commands

Generate Default Manifest

Generate Symbol Mapping

Apply Overrides

Sync All

Type Check

GitHub Actions Workflows

on-issue-comment.yml

process-token-override.yml

process-chain-override.yml

on-merge-override.yml

CDN Usage

Base URL

Logo URL Format

Frontend Integration

Adding a New Override via GitHub Issue

Step 1: Create Issue

Step 2: Trigger Processing

Step 3: Review & Merge

Supported Chains

Environment Variables (GitHub Actions)

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages