contract-populate

name	contract-populate
description	Populate smart contract addresses for a stablecoin using CoinGecko detail_platforms data. Uses only chain IDs already present in CHAIN_META and merges without overwriting existing curated data. Run per-coin or batch.
user_invocable	true

Contract Address Population

Fetch and merge contract addresses from CoinGecko into the matching shared/data/stablecoins/coins/*.json entry. Unknown chains are reported, not added; chain-support expansion is a separate explicit task.

Input

The user provides either:

• A stablecoin name, symbol, or ID (single coin)
• "top N" or "batch" (processes multiple coins by market cap order)

CG Platform → Chain ID Mapping

Use this mapping to translate CoinGecko platform names to our chain IDs. This is the authoritative map — unmapped platforms should be logged and skipped.

CG Platform Name         → Our Chain ID
──────────────────────────────────────────
ethereum                 → ethereum
arbitrum-one             → arbitrum
base                     → base
optimistic-ethereum      → optimism
polygon-pos              → polygon
avalanche                → avalanche
binance-smart-chain      → bsc
gnosis                   → gnosis
fantom                   → fantom
celo                     → celo
tron                     → tron
aptos                    → aptos
sui                      → sui
solana                   → solana
the-open-network         → ton
zksync                   → zksync
near-protocol            → near
algorand                 → algorand
stellar                  → stellar
starknet                 → starknet
hedera-hashgraph         → hedera
sonic                    → sonic
xdc-network              → xdc
sei-v2                   → sei
world-chain              → worldchain
unichain                 → unichain
ink                      → ink
polkadot                 → polkadot
xrp                      → xrpl
moonriver                → moonriver
klay-token               → klaytn
plume-network            → plume
hyperevm                 → hyperevm
monad                    → monad
mantle                   → mantle
linea                    → linea
scroll                   → scroll
blast                    → blast
mode-network             → mode
manta-pacific            → manta
ronin                    → ronin
bob-network              → bob
corn-network             → corn
berachain                → berachain
kava                     → kava
fraxtal                  → fraxtal
taiko                    → taiko
polygon-zkevm            → polygon-zkevm
aurora                   → aurora
moonbeam                 → moonbeam
boba                     → boba
soneium                  → soneium
zircuit                  → zircuit
metis-andromeda          → metis
astar                    → astar
plasma                   → plasma
morph-l2                 → morph-l2
swellchain               → swellchain
x-layer                  → xlayer
apechain                 → apechain
bittorrent               → bittorrent
tomochain                → viction
flare-network            → flare
songbird                 → songbird
bitlayer                 → bitlayer
tezos                    → tezos
cardano                  → cardano
internet-computer        → icp
noble                    → noble
osmosis                  → osmosis
mantra                   → mantra
provenance               → provenance
hydration                → hydration
xdai                     → gnosis
cronos                   → cronos
lisk                     → lisk
rootstock                → rootstock
eos                      → eos
flow                     → flow
iotex                    → iotex
multiversx               → multiversx
injective                → injective
zilliqa                  → zilliqa
conflux                  → conflux
pulsechain               → pulsechain

CG Platforms to Skip (dead/deprecated/legacy)

These CG platform names should be silently skipped — do not log them as unmapped:

harmony-shard-0          (Harmony — effectively dead)
evmos                    (Evmos — mostly dead)
terra                    (Terra Classic — dead)
terra-2                  (Terra 2 — dead)
q-mainnet                (Q — obscure, negligible activity)
binancecoin              (BNB Beacon Chain / BEP2 — legacy, not smart contract)

Process (Per Coin)

Step 1 — Read current state

1. Read shared/data/stablecoins/coins/*.json (or shared/data/stablecoins/coins.generated.json) and locate the coin's entry
2. Note the coin's geckoId — if missing, skip this coin and flag it
3. Note all existing chains in the coin's contracts array (these are curated and will NOT be overwritten)
4. Treat the runtime stablecoin re-export as import-only; contract metadata edits belong in the per-coin JSON registry and must match shared/lib/stablecoins/schema.ts

Step 2 — Fetch CoinGecko data

Fetch the CoinGecko coin detail API:

WebFetch https://api.coingecko.com/api/v3/coins/{geckoId}?localization=false&tickers=false&market_data=false&community_data=false&developer_data=false

Extract the detail_platforms field. This returns an object keyed by CG platform name, with values containing contract_address and decimal_place.

Step 3 — Map and merge

For each entry in detail_platforms:

1. Look up chain ID in the mapping table above
   • If not in the mapping → log as "unmapped: {cg_platform_name}" and skip
2. Check if chain already exists in the coin's contracts
   • If yes → skip (preserve curated data)
3. Check if chain exists in shared/lib/chains/index.ts (CHAIN_META)
   • If no → report it as "unsupported chain" and skip it unless the user explicitly requested a separate chain-support change
4. Add the contract to the coin's contracts array:
   • chain: our chain ID
   • address: from CG, lowercase for EVM chains, original case for non-EVM (Tron, Solana, Aptos, Sui, Near, Stellar, etc.)
   • decimals: from CG's decimal_place field. If null, try to determine from the token standard (most ERC-20s are 6 or 18). If truly unknown, flag and skip

Step 4 — Unsupported chains

When a mapped chain ID is not in CHAIN_META, do not modify shared/lib/chains/index.ts as part of this skill. Report the unsupported chain, the source platform name, supply or evidence if available, and whether a separate chain-support task is justified.

Step 5 — Write changes

1. Edit the coin's contracts array in the matching shared/data/stablecoins/coins/*.json entry using the Edit tool
2. Append new chains after the existing entries
3. Format new entries as JSON objects with chain, address, and decimals
4. For EVM addresses: lowercase hex (CoinGecko usually returns lowercase, verify)
5. For non-EVM: preserve original case from CoinGecko

Step 6 — Present summary

After each coin, report:

## {Symbol} — {Name}
- Existing chains kept: {list}
- New chains added: {list with addresses}
- Unmapped CG platforms skipped: {list}
- Null decimals flagged: {list}
- Unsupported chains skipped: {list}

Batch Mode

When processing multiple coins:

• Process sequentially (CoinGecko rate limit: ~30 req/min on free tier)
• After ALL coins are processed, present a single consolidated summary
• After the batch, regenerate shared/data/stablecoins/coins.generated.json and run npm run check:stablecoin-data; for full stablecoin additions, follow Phase 7 in docs/process/adding-a-stablecoin.md

Quality Standards

• Never overwrite existing contracts — curated data is trusted
• Lowercase EVM addresses — verify CG returns lowercase, force it if not
• Skip null decimals — unless the token standard makes it obvious (most ERC-20s are 6 or 18)
• Non-standard address formats are fine — Stellar, XRP, Polkadot, etc. have their own formats. Store as-is from CoinGecko
• Log unmapped platforms and unsupported chains — these are opportunities for separate mapping or chain-support work

What NOT to do

• Don't overwrite any existing contract entry
• Don't add the same chain twice for a coin
• Don't guess decimals — if CG returns null and it's unclear, skip
• Don't modify any fields other than contracts in the stablecoin JSON entry
• Don't modify shared/lib/chains/index.ts unless the user explicitly requested chain-support work outside this skill