crypto-balanced-portolio-builder

Crypto Portfolio by Market Cap

Build a market-cap-weighted crypto portfolio with per-asset caps, then get an exact buy/sell list to rebalance. Built with CoinStats users in mind, but any holdings CSV works.

---

Who this is for

CoinStats users who want to rebalance quickly. CoinStats tells you what you own, but not what to buy or sell to reach a target allocation. Export your Balances CSV, set a target, upload the file, and you get a per-coin BUY / SELL / HOLD list with exact units and dollar amounts. The export steps are documented below with screenshots.

Anyone who wants a market-cap-weighted portfolio. You don't need CoinStats, or any holdings file at all. Set a portfolio size, a number of coins and a maximum weight per coin, and the tool builds the allocation from live market data. If you track holdings somewhere else, any CSV with a Symbol column and an Amount column gives you the same rebalancing list.

Either way, the whole thing is one HTML file that runs in your browser. No accounts, no servers, no API keys, no install. Your holdings never leave your machine.

Quick start

1. Download crypto_portfolio_capped_v4.html.
2. Open it in any modern browser (double-click it).
3. Set your inputs and click Build Portfolio. This fetches live market caps from CoinGecko and builds your target allocation.
4. Optional: under Rebalance from CoinStats, upload your holdings CSV and click Compare Holdings.
5. Read the Portfolio Adjustments Needed table, or click Download Adjustments CSV.

Want to try step 4 before exporting anything? Upload docs/sample-coinstats-balances.csv.

---

Exporting your balances from CoinStats

If you use CoinStats, this is the file to upload in step 4. CoinStats currently marks CSV export as a Premium feature.

Web (coinstats.app)

1. Go to the Portfolio Tracker page and select the portfolio you want to rebalance.
2. Open the Assets tab.
3. Click the Export button (the download icon at the top right of the assets table).
4. Choose Balances. Save the CSV file.

Mobile app (iOS / Android)

1. Open the Portfolio tab and pick the portfolio you want to rebalance.
2. Tap the three-dot button below the chart.
3. Tap Portfolio Settings.
4. Scroll down and tap Export Data.
5. Choose Balances and save or share the CSV file, then get it onto the computer where you'll open the tool.

Steps and screenshots are from the CoinStats help article How to Export Transactions to CSV. If the CoinStats interface changes, that article is the source of truth.

Export Balances rather than Transaction History. The transaction export lists individual trades, not what you currently hold.

Using a CSV from somewhere else

The tool only needs two columns: Symbol and Amount (column names are matched case-insensitively, and an Amount or Total column both work). Extra columns are ignored. Multiple rows for the same symbol are summed, so a coin held on several exchanges or wallets is treated as one position. Exports from most other trackers and exchanges will work as-is or after renaming a header.

---

What the tool does

Builds a target allocation

• Pulls the top N coins by market cap from CoinGecko (live, paginated, deduplicated by symbol).
• Weights each coin by market cap, clips anything over your per-coin cap, and redistributes the excess proportionally until every dollar is allocated.
• Lets you pin specific coins to exact percentages with custom targets. Whatever remains is spread across the market-cap-weighted coins.
• Excludes stablecoins by default, plus a default exclusion list you can edit.

Compares it against your current holdings

• Every coin you hold or should hold gets an action: BUY, SELL or HOLD.
• Shows current units, target units, the delta, and the same in USD.
• Coins you hold that are not in the target get a SELL row so nothing is silently ignored.
• Summary chips: current value, target value, number of buys and sells, net adjustment.

Exports

• Target allocation as CSV or JSON, respecting the current sort order.
• Adjustments list as a separate CSV once you've compared holdings.

Interface

• Sortable results table with inline weight bars showing the cap and any clipped portion.
• Donut chart with hover highlighting synced to the legend.
• Dark, responsive, keyboard accessible. Coin names link to CoinGecko.

---

How the allocation maths works

1. Fetch the top N coins by market cap from CoinGecko.
2. Compute baseline weights as coin market cap / total market cap.
3. Apply the per-coin cap and redistribute clipped weight proportionally until fully allocated.
4. Subtract any custom targets first; the rest of the portfolio is allocated by market cap.
5. Convert weights to target USD and target units using your portfolio value.
6. If you uploaded holdings, compare target units against what you hold to produce the buy/sell list.

---

Development

• Stack: HTML + CSS + vanilla JS, no dependencies
• Single file: edit crypto_portfolio_capped_v4.html directly
• Testing: open the file in a browser; there is no build

---

Notes & limitations

• Uses CoinGecko's free public API for market data. Rate limits (HTTP 429) are handled with retry/backoff, but heavy refreshing will still get throttled.
• Prices come from CoinGecko, not from your holdings export, so values can differ slightly from what your tracker shows.
• All calculations are client-side. Verify the numbers before you trade on them.
• Not financial advice.

Privacy

100% client-side. The only network request the page makes is to CoinGecko's public API for market data. Your portfolio size, holdings CSV, and allocations never leave your machine.

---

Attribution

• Market data from the CoinGecko Public API
• CoinStats export screenshots from the CoinStats Help Center. CoinStats is a trademark of its owner; this project is not affiliated with or endorsed by CoinStats.

License

MIT — free to use, modify, and distribute, including commercially.