crypto-price-bot/docs/superpowers/specs/2026-04-26-token-message-rich-design.md

Token message rich design

Context

Current token message flow returns early for Alpha tokens, so users cannot see Spot/Future together with Alpha when multiple sources are available. Message content is also rigid and less informative for partial-source cases.

Goal: redesign Telegram token message so each available price source is shown in one rich message, with stable ordering and conditional rows.

Scope

Applies to token query message rendering in Telegram bot (OnTokenInfoByToken flow and price view formatting).

Out of scope:

• changing market data fetch logic
• changing command routing
• trend arrows / historical diff

Requirements

1. Rich, multi-line Telegram message format.
2. Spot is primary source when present.
3. Show all available sources in a single message: Spot, Future, Alpha.
4. Hide rows for missing data.
5. Show Basis only when both Spot and Future exist.
6. Show Alpha 24h when Alpha data exists.
7. No trend arrows.
8. Preserve current behavior of no reply when no Spot/Future/Alpha data exists.

Message format

Fixed row order (hide missing rows):

1. 🪙 TOKEN
2. 💵 Spot: ... (primary if exists)
3. 📈 Future: ...
4. 🅰️ Alpha: ...
5. 🧭 Basis: Future-Spot (only if Spot+Future)
6. 💸 Funding: ... in ... (if Future exists)
7. 🏦 Margin: ... APR (if margin exists)
8. 📊 Alpha 24h: ... (if Alpha change exists)

Fallback rules

• All three available: render all rows above (except any missing optional fields).
• Spot + Future: render Spot, Future, Basis, Funding, Margin.
• Alpha only: render Alpha and Alpha 24h.
• Future only: render Future, Funding, Margin.
• Spot only: render Spot, Margin.
• No Spot/Future/Alpha: no reply.

Data flow behavior

1. Resolve token to candidate futures symbol(s) using existing resolver.
2. Collect available values from Spot/Future/Alpha/margin sources.
3. Build one unified message model.
4. Render rows in fixed order; each row is conditional on availability.
5. Send single Telegram message.

Important behavioral change: remove alpha-first early-return behavior; Alpha becomes a peer data source in unified rendering.

Formatting notes

• Reuse existing numeric formatter (RenderPrice) for price values.
• Keep current funding icon and countdown style.
• Basis format:
  • absolute delta: Future - Spot
  • percent delta: (Future-Spot)/Spot*100
  • sign preserved (+/-)

Example outputs

A) Spot + Future + Alpha

🪙 ETH
💵 Spot: $3,245
📈 Future: $3,251
🅰️ Alpha: $3,248
🧭 Basis: +$6 (+0.18%)
💸 Funding: +0.0123% 🟢 in 05m
🏦 Margin: 7.665% APR
📊 Alpha 24h: 🔴 -3.21%

B) Spot + Future

🪙 SOL
💵 Spot: $182.4
📈 Future: $183.0
🧭 Basis: +$0.6 (+0.33%)
💸 Funding: -0.0041% 🔴 in 42m
🏦 Margin: 5.110% APR

C) Alpha only

🪙 ABC
🅰️ Alpha: $0.1234
📊 Alpha 24h: 🟢 +12.40%

D) Future only

🪙 TOKEN
📈 Future: $1,234
💸 Funding: +0.0081% 🟢 in 17m
🏦 Margin: 6.200% APR

E) Spot only

🪙 TOKEN
💵 Spot: $1,228
🏦 Margin: 6.200% APR

Verification checklist

• Token with all 3 sources -> all expected rows appear, ordered correctly.
• Token with Spot+Future but no Alpha -> no Alpha rows.
• Token with Alpha only -> no Spot/Future/Basis/Funding rows.
• Token with Future only -> no Spot/Basis/Alpha rows.
• Token with Spot only -> no Future/Basis/Funding/Alpha rows.
• Token with no data -> no reply.
• Basis not shown unless both Spot and Future exist.
• No trend arrows anywhere.