| name | holdings |
| description | Report your wallet holdings of the instance's token - amount held, % of total supply, and 7d/30d amount growth, via public RPC (no dollar value) |
| metadata | {"title":"Holdings","category":"crypto","var":"","tags":["crypto"],"mode":"write","requires":["BASE_RPC_URL?","SOLANA_RPC_URL?"],"capabilities":["external_api"]} |
${var} — Optional single wallet address to check (Base 0x… or Solana). If empty, uses every wallet in memory/holdings.json.
What this does
Reads a set of your wallets and the project tokens to track, then reports, per token:
- Amount held.
- % of total supply you hold (
amount ÷ total_supply).
- 7d and 30d holdings growth — the change in your token amount over the
window (did you accumulate or sell).
No dollar value / price is reported — this is a holdings tracker, not a
portfolio-value report. Amounts and supply share only.
On-chain balances come from public, keyless RPC (https://mainnet.base.org for
Base, https://api.mainnet-beta.solana.com for Solana); total supply comes from
GeckoTerminal. No API key required — override the RPC with BASE_RPC_URL /
SOLANA_RPC_URL if you have an authenticated node.
Each instance tracks its own token: this config holds one token — aeon on the
aeon instance, MiroShark on the MiroShark instance. Add a second tokens entry only
if an instance should report both.
Growth = amount, not price. 7d/30d growth is the change in how many tokens you
hold, measured against this skill's own prior snapshots (HOLDINGS_STATE: lines in
memory/logs). There is no price-history fetch — the skill builds its own history,
one snapshot per run. On the first runs the 7d/30d fields are simply absent (no
snapshot that far back yet) and fill in as the log accumulates: once a snapshot
~7 days back exists the 7d figure appears, ~30 days back the 30d figure. This skill
runs weekly, so 7d lands on the second run and 30d after ~4-5 runs.
Note: on-chain totalSupply() reverts on the DERC20 aeon contract, so total supply
comes from GeckoTerminal (total_supply, 100,000,000,000 aeon).
Config
Reads memory/holdings.json:
{
"wallets": [
{"address": "0x…", "label": "personal", "chain": "base"},
{"address": "8mjM…", "label": "sol", "chain": "solana"}
],
"tokens": [
{"symbol": "aeon", "contract": "0xbf8e8f0e8866a7052f948c16508644347c57aba3", "chain": "base", "decimals": 18}
]
}
A token is checked against every wallet on the same chain. Add the miroshark
token as a second tokens entry once its contract is known.
If ${var} is set, check only that one address (chain inferred: 0x-prefixed →
base, else solana) against every token on that chain, ignoring the wallet list.
If memory/holdings.json is missing and ${var} is empty, abort silently — no
notification, no article.
Steps
1. Fetch balances + prices
python3 skills/holdings/holdings.py memory/holdings.json
The helper (Python stdlib only, sandbox-safe) prints JSON:
rows[] — one per (token, wallet): symbol, chain, wallet, label,
amount (or error if a fetch failed).per_symbol — totals per token: amount, total_supply, pct_supply (% of
supply held).
pct_supply may be null if GeckoTerminal lacked supply for that token — render
—, do not abort. The helper reports the current snapshot only; 7d/30d growth is
computed in step 2 from prior snapshots. No dollar value is produced.
If ${var} is set, check that one wallet against this instance's own tokens (read
from memory/holdings.json) — only the wallet is overridden, the token list stays
instance-specific:
ADDR="${var}"
CHAIN=base; [ "${ADDR#0x}" = "$ADDR" ] && CHAIN=solana
python3 - "$ADDR" "$CHAIN" > /tmp/holdings-var.json <<'PY'
import json,sys
addr,chain=sys.argv[1],sys.argv[2]
cfg=json.load(open("memory/holdings.json"))
json.dump({"wallets":[{"address":addr,"label":"var","chain":chain}],
"tokens":[t for t in cfg["tokens"] if t["chain"]==chain]},sys.stdout)
PY
python3 skills/holdings/holdings.py /tmp/holdings-var.json
If a row has "error", retry holdings.py once. If it still errors on the RPC
(sandbox block / 403 / timeout), note rpc=fetch_fail in the footer for that wallet
and continue — a partial report still beats nothing. If pct_supply is null
(GeckoTerminal supply miss), report the raw amount and mark % Supply as —, do not
abort.
2. Compute holdings growth from prior snapshots
Read the last ~35 days of memory/logs/*.md for HOLDINGS_STATE: lines (written in
step 4), each carrying <symbol>_amount per tracked token with a date. Reconstruct a
per-token amount series, then pick:
- 24h — the most recent prior snapshot (yesterday's run).
- 7d — the snapshot closest to 7 days ago (accept ±2 days; note the actual gap).
- 30d — the snapshot closest to 30 days ago (accept ±4 days).
For each window compute the amount change:
amount_delta — amount_now − amount_then (in tokens; + = accumulated, − = sold).amount_delta_pct — amount_delta ÷ amount_then × 100.
Report growth as tokens and percent, e.g. 7d +1.20B (+10.3%) or 30d −0 (flat).
This is holdings movement only — it does not move with price.
If a window has no snapshot yet (early runs), OMIT that window — do not print +0
for "no data". +0 is reserved for a window that HAS a prior snapshot and the amount
genuinely did not change. USD value is still shown for the current snapshot; only the
growth columns wait on history.
3. Compile the report
Save to output/articles/holdings-${today}.md:
# Holdings — ${today}
| Token | Amount | % Supply | 7d | 30d |
|-------|--------|----------|-----|-----|
| aeon | 12.82B | 12.82% | +1.20B (+10.3%) | +2.10B (+19.6%) |
7d/30d are the change in token **amount** held over the window (accumulation/sell),
from prior snapshots. A window with no snapshot yet is blank (`building`), not `0`.
`+0` means a real no-change.
## By wallet
| Wallet | Amount |
|--------|--------|
| aeon-safe (0xf1e9…158e) | 12.53B |
| aeon-deployer (0x6797…e3a2) | 285.32M |
---
*Balances: public RPC (base=mainnet.base.org). Supply: GeckoTerminal. Growth: own snapshots.*
*Sources: rpc=[ok|fetch_fail] · supply=[ok|na] · growth=[Nd history|building]*
Format large token counts compactly (12.82B, 285.3M, 1.20K), % Supply to two
decimals. Omit the "By wallet" table if there is only one wallet (it duplicates the
top table).
4. State log (powers tomorrow's deltas)
Append to memory/logs/${today}.md:
### holdings
- HOLDINGS_STATE: date=${today} aeon_amount=XXXX.XX aeon_pct_supply=XX.XX
- Article: output/articles/holdings-${today}.md
- Sources: rpc=ok supply=ok
The HOLDINGS_STATE: line is the snapshot store — this is the "history it builds at
each run". Step 2 of every future run parses it with a key=value split. Include a
date= field plus, per tracked token, <symbol>_amount + <symbol>_pct_supply (no
dollar fields). No thousands separators, full-precision _amount (do not pre-round —
the 7d/30d deltas subtract these). Keep key order stable. Always write this line,
even on a flat/quiet run, so the series stays unbroken (a missing day just widens the
nearest-snapshot search window).
5. Notify
*Holdings — aeon*
12.82B · 12.82% of supply
7d +1.20B (+10.3%) · 30d +2.10B (+19.6%)
The title names the tracked token. The growth line shows token-amount change over
the window; render building for a window with no snapshot yet, +0 for a real
no-change. With more than one tracked token, repeat the two-line block per token.
Skip rule: if no token's amount changed since the last run, send a single line
aeon holdings flat — 12.82B (12.82% of supply). instead of the full block. On a
total RPC failure (every wallet fetch_fail), log only — no notification.
Sandbox note
holdings.py uses only the Python stdlib and sends a browser User-Agent (the
public mainnet.base.org endpoint 403s the default urllib UA). All reads are public
and keyless; no secretcurl, no secrets. If the sandbox blocks the RPC POST, the
row carries an error and the skill degrades to a partial report — it never invents
a balance.
Constraints
- Never invent a balance or price. Every number traces to an RPC response or a
GeckoTerminal price. A failed fetch is reported as
fetch_fail, not zero.
- A zero balance (wallet holds none of the token) is real data — report
0, distinct
from fetch_fail.
- Preserve the
HOLDINGS_STATE: log schema — tomorrow's deltas depend on it.
- Public RPC only by default; only use
BASE_RPC_URL/SOLANA_RPC_URL overrides, and
put any key in the URL path, never a header (sandbox blocks env expansion in -H).
