Rationales

Rationales let you document whyyou made specific investment decisions. Whether it's explaining your portfolio strategy, wallet allocation, or a rebalancing decision, rationales help you track your reasoning over time.

✅ Try it live

Visit the Rationale feature page to see interactive examples without signing up.

What Are Rationales?#

A rationale is a markdown-formatted note attached to:

  • Portfolios: Your overall investment strategy and thesis
  • Wallets: Why you organized holdings this specific way
  • Portfolio Commits: The reasoning behind a rebalancing action

Rationales support full Markdown formatting, so you can use headings, lists, bold text, links, and more to structure your notes.

Data Model#

Each rationale has the following properties:

FieldTypeDescription
idstringUnique identifier for the rationale
entityTypeenumOne of: portfolio, wallet, or portfolioCommit
entityIdstringID of the related portfolio, wallet, or commit
contentstringMarkdown-formatted rationale text
createdAt / updatedAttimestampWhen the rationale was created/updated

💡 Unique constraint

You can only have one rationale per entity. If you create a new rationale for an entity that already has one, it will be updated (upserted).

Portfolio Rationales#

Portfolio rationales are perfect for documenting your high-level investment strategy, thesis, or philosophy. Think of it as a living document that evolves with your portfolio.

Portfolio Rationale

Investment Thesis

This portfolio follows a conservative long-term strategy focused on established cryptocurrencies with strong fundamentals.

Allocation Strategy

  • 60% Bitcoin (store of value, digital gold)
  • 30% Ethereum (smart contract platform, DeFi backbone)
  • 10% Stablecoins (liquidity buffer for opportunities)

Risk Management

  • Dollar-cost averaging monthly
  • Rebalance quarterly if allocations drift >10%
  • Hold through market volatility (5+ year horizon)

Portfolio rationale with markdown-formatted investment thesis

Common Use Cases#

  • Investment thesis: Why you believe in these assets
  • Allocation strategy: Target percentages and reasoning
  • Time horizon: How long you plan to hold these positions
  • Risk tolerance: Your comfort level with volatility
  • Rebalancing rules: When and how you'll adjust positions

Wallet Rationales#

Wallet rationales explain why you organized coins into a specific wallet. This is useful when you have multiple wallets with different purposes or strategies.

Wallet Rationale

DeFi Experimental Wallet

This wallet is dedicated to exploring DeFi protocols and yield farming opportunities.

Current Focus:

  • Lending protocols (Aave, Compound)
  • DEX liquidity provision (Uniswap, Curve)
  • Max 10% of total portfolio value

Exit Criteria: If protocol TVL drops below $100M or if exploit risks increase, migrate to more established platforms.

Wallet rationale explaining DeFi experimentation strategy

Common Use Cases#

  • Strategy-based: “HODLing”, “Trading”, “DeFi”, “Staking”
  • Exchange-based: Track coins on different exchanges
  • Risk-based: “Conservative”, “Aggressive”, “Experimental”
  • Tax optimization: Separate short-term vs long-term holdings

Portfolio Commit Rationales#

When you rebalance your portfolio (via a “commit”), you can attach a rationale explaining what changed and why. This creates an audit trail of your portfolio decisions.

Commit Rationale

Rebalancing due to Bitcoin rally. BTC allocation reached 72% (target: 60%).

Actions:

  • Trim 0.15 BTC (~$10,000)
  • Add to ETH position to restore 30% target
  • Keep remainder in stablecoins for next dip

Commit rationale documenting rebalancing decision

Common Use Cases#

  • Rebalancing: Why you adjusted allocations
  • Market response: Decisions based on market conditions
  • Tax harvesting: Documenting tax-loss harvesting actions
  • Exit strategies: Recording when/why you sold positions

💡 Learn about commits

To learn more about portfolio commits and rebalancing, see the Portfolios documentation.

Markdown Support#

Rationales support standard Markdown syntax, allowing you to format your notes with:

SyntaxResult
**bold text**bold text
*italic text*italic text
## HeadingHeading
- List item• List item
[Link](url)Link
`code`code

Best Practices#

Be Specific and Actionable#

Instead of vague notes like “Good project”, write specific reasons:

❌ Vague
“Bitcoin is a good investment”
✓ Specific
“Bitcoin: Store of value thesis. Limited supply (21M cap), institutional adoption growing, portfolio hedge against inflation. Target 40% allocation.”

Update as Things Change#

Your rationales should evolve with your strategy. When market conditions change or you learn new information, update your rationales to reflect your current thinking.

Use Markdown for Structure#

Break up long rationales with headings, lists, and formatting. This makes them easier to scan when you revisit them months later.

Track Your Decision-Making Process#

Rationales are your personal investment journal. Years later, you'll be able to look back and understand exactly why you made certain decisions—and learn from them.

API Reference#

For developers integrating with MyHold App, rationales are accessible via REST API. See the Rationales API documentation for detailed endpoint specifications, request/response schemas, and authentication requirements.

✅ API Features

The API supports upsert operations (create or update in one call), batch retrieval by entity type, and automatic user scoping via JWT authentication.

Privacy & Security#

Your rationales are private and only visible to you. They are:

  • Stored securely in our encrypted database
  • Never shared with third parties
  • Automatically deleted if you delete the parent portfolio or wallet
  • Accessible only with your authenticated session

Developers can integrate with MyHold App using our REST API. See the API Documentation for details.