Skip to content

openscan-explorer/explorer-metadata

BranchesTags

Repository files navigation

OpenScan Metadata

Open, community-driven metadata repository for the OpenScan blockchain explorer.

This repository contains verified metadata for tokens, networks, apps, organizations, addresses, events, supporters, and donations displayed on OpenScan.

Structure

explorer-metadata/
├── data/
│   ├── tokens/{chainId}/{address}.json    # Token metadata
│   ├── addresses/{chainId}/{address}.json # Verified addresses per chain
│   ├── events/{chainId}/common.json       # Common events (ERC20, etc.)
│   ├── events/{chainId}/{address}.json    # Address-specific events
│   ├── networks.json                      # All networks
│   ├── apps/{id}.json                     # App metadata
│   ├── orgs/{id}.json                     # Organization metadata
│   └── donations.json                     # Donations list
├── profiles/
│   ├── tokens/{chainId}/{address}.md      # Token profiles
│   ├── apps/{id}.md                       # App profiles
│   └── organizations/{id}.md              # Organization profiles
├── assets/
│   ├── tokens/{chainId}/{address}.png     # Token logos (128x128)
│   ├── networks/{chainId}.svg             # Network logos
│   ├── apps/{id}.svg                      # App logos
│   └── organizations/{id}.svg             # Organization logos
└── schemas/                               # JSON Schema definitions

Adding Metadata

Quick Start: Add a Token

npm install
npm run add-token

Follow the interactive prompts to add a new token.

Manual Submission

  1. Fork this repository
  2. Add your data file to the appropriate data/ folder
  3. Add logo to assets/ (see image requirements below)
  4. (Optional) Add profile markdown to profiles/
  5. Run npm run validate to check your submission
  6. Submit a Pull Request using the appropriate template

Data Schemas

Token

Tokens support ERC20, ERC721 (NFTs), and ERC1155 (Multi-Token) standards. All token types support free listings and paid subscriptions.

Free Listing (verified contract required)

{
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chainId": 1,
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 6
}

NFT Collection (ERC721)

{
  "address": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
  "chainId": 1,
  "type": "ERC721",
  "name": "Bored Ape Yacht Club",
  "symbol": "BAYC",
  "decimals": 0,
  "totalSupply": 10000
}

Paid Subscription (additional features)

{
  "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "chainId": 1,
  "name": "USD Coin",
  "symbol": "USDC",
  "decimals": 6,
  "subscription": {
    "tier": 2,
    "expiresAt": "2026-01-01"
  },
  "verified": true,
  "logo": "assets/tokens/1/0x....png",
  "profile": "profiles/tokens/1/0x....md",
  "project": {
    "name": "Circle",
    "description": "USDC is a fully reserved stablecoin"
  },
  "links": [
    { "name": "Website", "url": "https://circle.com/usdc", "description": "Official website" },
    { "name": "Twitter", "url": "https://twitter.com/circle" }
  ],
  "networks": [
    { "chainId": 42161, "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" },
    { "chainId": 10, "address": "0x0b2c639c533813f4aa9d7837caf62653d097ff85" }
  ],
  "tags": ["stablecoin", "defi"]
}

Network

{
  "chainId": 42161,
  "name": "Arbitrum One",
  "shortName": "Arbitrum",
  "description": "Ethereum Layer 2 scaling solution",
  "currency": "ETH",
  "color": "#28A0F0",
  "isTestnet": false,
  "subscription": {
    "tier": 2,
    "expiresAt": "2026-01-01"
  },
  "logo": "assets/networks/42161.svg",
  "profile": "profiles/networks/42161.md",
  "rpc": {
    "public": ["https://arb1.arbitrum.io/rpc"]
  },
  "links": [
    { "name": "Website", "url": "https://arbitrum.io", "description": "Official website" },
    { "name": "Bridge", "url": "https://bridge.arbitrum.io" },
    { "name": "Docs", "url": "https://docs.arbitrum.io" }
  ]
}

App

{
  "id": "uniswap",
  "name": "Uniswap",
  "type": "dapp",
  "description": "Decentralized trading protocol",
  "subscription": {
    "tier": 2,
    "expiresAt": "2026-01-01"
  },
  "verified": true,
  "logo": "assets/apps/uniswap.svg",
  "profile": "profiles/apps/uniswap.md",
  "contracts": [
    { "chainId": 1, "address": "0x...", "label": "SwapRouter02" }
  ],
  "networks": [1, 42161, 10, 137],
  "links": [
    { "name": "Website", "url": "https://uniswap.org" },
    { "name": "App", "url": "https://app.uniswap.org" },
    { "name": "Docs", "url": "https://docs.uniswap.org" }
  ],
  "tags": ["defi", "dex", "amm"]
}

Organization

{
  "id": "ethereum-foundation",
  "name": "Ethereum Foundation",
  "type": "foundation",
  "description": "Supporting Ethereum development",
  "subscription": {
    "tier": 3,
    "expiresAt": "2026-01-01"
  },
  "logo": "assets/organizations/ethereum-foundation.svg",
  "profile": "profiles/organizations/ethereum-foundation.md",
  "links": [
    { "name": "Website", "url": "https://ethereum.foundation" },
    { "name": "Blog", "url": "https://blog.ethereum.org" },
    { "name": "Twitter", "url": "https://twitter.com/ethereum" }
  ]
}

Supporter

{
  "id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "type": "token",
  "chainId": 1,
  "name": "USD Coin (USDC)",
  "startedAt": "2025-01-01",
  "currentTier": 2,
  "expiresAt": "2026-01-01",
  "history": [
    { "tier": 2, "from": "2025-01-01", "to": "2026-01-01" }
  ]
}

Donation

{
  "from": "vitalik.eth",
  "amount": "1 ETH",
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "chainId": 1,
  "message": "Keep building the open web!",
  "date": "2025-12-01"
}

Event

Events are stored per chain with common events in data/events/{chainId}/common.json and address-specific events in data/events/{chainId}/{address}.json.

Common Events (common.json)

Standard events like ERC20 Transfer, Approval, etc:

{
  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef": {
    "event": "Transfer(address,address,uint256)",
    "description": "ERC20/ERC721 token transfer."
  },
  "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925": {
    "event": "Approval(address,address,uint256)",
    "description": "ERC20/ERC721 approval granted."
  }
}

Address-Specific Events ({address}.json)

Custom events for specific contracts (e.g., Uniswap V2 Router):

{
  "0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822": {
    "event": "Swap(address,uint256,uint256,uint256,uint256,address)",
    "description": "Token swap executed."
  },
  "0x4c209b5fc8ad50758f13e2e1088ba56a560dff690a1c6fef26394f4c03821c4f": {
    "event": "Mint(address,uint256,uint256)",
    "description": "Liquidity added to pool."
  }
}

Address

Verified addresses for apps and organizations are stored per chain in data/addresses/{chainId}/{address}.json.

{
  "address": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
  "chainId": 1,
  "supporter": "uniswap",
  "label": "Router V2"
}
  • address: Checksummed contract address
  • chainId: Chain ID where this address is deployed
  • supporter: ID of the app or organization
  • label: Optional human-readable label for the address

Subscription Tiers

Tiers are represented as integers:

  • 1 = Backer: Entry-level support (base price)
  • 2 = Partner: Enhanced benefits and visibility (3x Backer price)
  • 3 = Ally: Full partnership with direct team access (6x Backer price)

Tokens

Verified contracts tags, metadata integration, logo display, official links, and token balance fetcher integration.

Tier Monthly Rate Key Benefits
Backer (Tier 1) $500 Token page with ERC20 details, project name, custom URLs. Verified and tagged contracts.
Partner (Tier 2) $1,500 (3x) Token balance shown on main explorer. Simple profile page.
Ally (Tier 3) $3,000 (6x) Complete profile page with markdown description. Direct communication with technical team.

Networks

Full RPC methods support, dedicated technical maintenance, subdomain availability, and prominent branding.

Tier Monthly Rate Key Benefits
Backer (Tier 1) $2,000 Complete profile page. Priority placement on home page.
Partner (Tier 2) $6,000 (3x) Dedicated subdomain network explorer. Multiple network listing. Direct communication with technical team.
Ally (Tier 3) $12,000 (6x) Roadmap voting power. Network-specific features in dedicated explorer.

Apps

Dedicated listing and verified branding for wallets, dApps, supplementary explorer tools, and exchanges.

Tier Monthly Rate Key Benefits
Backer (Tier 1) $1,000 Simple profile page. Important contracts verified and tagged. Contract events listing.
Partner (Tier 2) $3,000 (3x) OpenScan subdomain. Complete profile.
Ally (Tier 3) $6,000 (6x) Roadmap voting power. Direct communication with technical team.

Organizations

Formal recognition and visibility for infrastructure providers, venture funds, and other supporting entities.

Tier Monthly Rate Key Benefits
Backer (Tier 1) $500 Simple profile page. Important contracts verified and tagged. Contract events listing.
Partner (Tier 2) $1,500 (3x) Complete profile. OpenScan subdomain.
Ally (Tier 3) $3,000 (6x) Roadmap voting power. Direct communication with technical team.

Profile Limits

Entity Type Simple Profile Complete Profile
Tokens ≤1,000 characters (Tier 2) Unlimited markdown (Tier 3)
Networks Unlimited markdown (all tiers) Unlimited markdown (all tiers)
Apps ≤1,000 characters (Tier 1) Unlimited markdown (Tier 2+)
Organizations ≤1,000 characters (Tier 1) Unlimited markdown (Tier 2+)

Donations

Individual donations are welcome! When you donate through the OpenScan payment contract, you can include a message that will be permanently recorded in this repository.

Donation records include:

  • from: Your address or ENS name
  • amount: Donation amount (e.g., "0.1 ETH")
  • transaction: Transaction hash for verification
  • message: Your optional message (max 500 characters)

Image Requirements

Type Format Size Max File Size
Tokens PNG 128x128px 50KB
Networks SVG (preferred) 256x256px 100KB
Apps SVG (preferred) 256x256px 100KB
Organizations SVG (preferred) 256x256px 100KB

Run npm run optimize-images to automatically optimize images.

Development

# Install dependencies
npm install

# Validate all metadata
npm run validate

# Optimize images
npm run optimize-images

# Build distribution
npm run build

# Add a token interactively
npm run add-token

API

The built metadata is available in the dist/ folder on the main branch.

Distribution Structure

dist/
├── tokens/{chainId}/
│   ├── all.json                    # List of all tokens (basic info)
│   └── {address}.json              # Individual token details
├── addresses/{chainId}/
│   ├── all.json                    # List of all addresses (basic info)
│   └── {address}.json              # Individual address details
├── events/{chainId}/
│   ├── common.json                 # Common events (ERC20, etc.)
│   └── {address}.json              # Address-specific events
├── networks.json                   # All networks
├── apps.json                       # All apps
├── organizations.json              # All organizations
├── supporters.json                 # All supporters
├── donations.json                  # All donations
├── manifest.json                   # Build metadata
├── profiles/                       # Markdown profiles
└── assets/                         # Images and logos

Endpoints

Base URL: https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist

# Get all networks
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/networks.json

# Get all apps
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/apps.json

# Get supporters list
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/supporters.json

# Get donations list
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/donations.json

# Tokens - list all tokens on a network (basic info)
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/tokens/1/all.json

# Tokens - get specific token details
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/tokens/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.json

# Addresses - list all addresses on a network
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/addresses/1/all.json

# Addresses - get specific address details
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/addresses/1/0x7a250d5630b4cf539739df2c5dacb4c659f2488d.json

# Events - get common events for a network
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/events/1/common.json

# Events - get address-specific events
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/events/1/0x7a250d5630b4cf539739df2c5dacb4c659f2488d.json

# Get a token profile
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/profiles/tokens/1/0x....md

# Get a token logo
curl https://raw.githubusercontent.com/openscan-org/explorer-metadata/main/dist/assets/tokens/1/0x....png

License

MIT

About

Metadata repository for openscan-explorer

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Languages