transfers.mdx Documentation

1. Project Overview & Quickstart (we-promise/transfers.mdx) Copy Chapter

transfers.mdx

Open-source repository we-promise/transfers.mdx

Repository Details Copy Section

• Repository: we-promise/transfers.mdx
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (we-promise/docs) Copy Chapter

File: README.md Copy Chapter

Sure Docs

Still #needsupdate!

This is the starter kit to get your docs deployed and ready to customize.

Click the green Use this template button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with

• Guide pages
• Navigation
• Customizations
• API reference pages
• Use of popular components

Follow the full quickstart guide

Development Copy Chapter

Install the Mintlify CLI to preview your documentation changes locally. To install, use the following command:

npm i mint

Run the following command at the root of your documentation, where your docs.json is located:

mint dev

View your local preview at http://localhost:3000.

Publishing changes Copy Chapter

Install our GitHub app from your dashboard to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.

Need help? Copy Chapter

Troubleshooting Copy Section

• If your dev environment isn't running: Run mint update to ensure you have the most recent version of the CLI.
• If a page loads as a 404: Make sure you are running in a folder with a valid docs.json.

Resources Copy Section

• Mintlify documentation

File: guides/knowledge-base/faq.mdx Copy Chapter

title: "FAQ" Copy Chapter

Transfers and Currencies Copy Chapter

- The outgoing transaction uses the source account's currency and amount
- The incoming transaction is converted to the destination account's currency using the latest available rate
- If no exchange rate is found, it falls back to a 1:1 rate, which may result in incorrect amounts until rates are synced
- Foreign exchange metadata is also recorded for auditing purposes

For best results, make sure your exchange rates are up to date to avoid conversion errors.

**Sources:**
- [Transfer Creator Implementation](https://github.com/we-promise/sure/blob/8e36c8e7368cef008133970404bcaabd6cde3df9/app/models/transfer/creator.rb#L1-L103)
- [Issue #124](https://github.com/we-promise/sure/issues/124)

File: guides/knowledge-base/troubleshooting.mdx Copy Chapter

title: "Troubleshooting" Copy Chapter

When Rules Are Triggered Copy Chapter

Rules run automatically during family syncs or can be triggered manually. Understanding when rules execute helps troubleshoot categorization issues.

- Clicking "Re-apply" on an individual rule in `/settings/rules`
- Clicking "Apply All" in `/settings/rules`
- Running the rake task: `bin/rails rules:apply_all[family_id]`

**Scheduled syncs:**
- `SyncAllJob` - runs daily at 2:22 AM for all families
- `SyncHourlyJob` - runs every hour (for items that opt-in to hourly syncing)

**Triggered syncs:**
- Provider webhooks (Plaid, etc.) - triggers sync which eventually propagates to family
- Manual sync button on accounts page
- After CSV imports complete (`Import` model calls `family.sync_later`)

- **Manual transaction creation** - Only triggers an Account sync (not Family sync)
- **Manual transaction editing** - Same as above, only Account sync runs
- **Inactive rules** - Rules with `active: false` never run automatically, only via manual "Re-apply"

1. Go to **Settings** → **Debug**
2. Look for entries with category **`rules`**

Each failed run includes the error message and the rule that triggered it.

Rule run failures not visible in the UI Copy Chapter

When rules run asynchronously (during a sync or via a background job), failures are not surfaced in the main UI. If auto-categorization or merchant detection appears to stop working silently, check the debug log.

1. Go to **Settings → Debug**
2. Filter by the relevant category (e.g., `rules` or `auto_categorize`)

A request that was enqueued but has no matching start entry in the log means the job never reached a worker.

Category Rule Popup Behavior Copy Chapter

When a user selects a category for a transaction, a popup may appear to create an automatic categorization rule. This popup is intentionally gated by several conditions:

1. User has not disabled rule prompts (`rule_prompts_disabled` is false)
2. User hasn't dismissed the popup in the last **24 hours**
3. The transaction category actually changed
4. No existing rule already sets this category for similar transactions
5. The transaction has a category assigned

- **Recently dismissed**: Wait 24 hours after dismissing the popup
- **Rule already exists**: A matching rule may already be in place
- **Prompts disabled**: Check if `rule_prompts_disabled` is enabled for the user

Sure Doesn’t Work Over HTTPS Copy Chapter

If Sure behaves incorrectly or fails when accessed over HTTPS, it’s usually due to missing SSL-related configuration between Nginx and Rails.

Sure relies on correct protocol headers to determine whether a request is secure.  
When HTTPS is terminated at Nginx but not properly forwarded to the app, Rails may treat requests as HTTP.

Apply the following configuration changes:

1. **Nginx**

   Ensure HTTPS is forwarded to the upstream app:

   ```nginx
   proxy_set_header X-Forwarded-Proto https;
   ```

2. **docker-compose.yml**

   In the `x-rails-env: &rails_env` section, set:

   ```yaml
   RAILS_ASSUME_SSL: "true"
   ```

   This tells Rails to treat all requests as HTTPS.

Some pages break over HTTPS Copy Chapter

Sure uses WebSockets for certain pages. If some pages fail to render correctly or break entirely, this is often caused by missing SSL or upgrade headers in your reverse proxy configuration.

You may see pages partially load, fail completely, or errors similar to:

```text
Failed to upgrade to WebSocket (REQUEST_METHOD: GET, HTTP_CONNECTION: close, HTTP_UPGRADE: )
```

This indicates that the WebSocket upgrade request is not being forwarded correctly.

Ensure your Nginx configuration includes the required WebSocket headers:

```nginx
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

These headers allow Nginx to properly handle WebSocket upgrade requests over HTTPS.

Budget totals do not update after deleting transactions Copy Chapter

If a budget still shows spending from a transaction that was already deleted, the most likely cause is a stale aggregate cache. Sure hard-deletes the transaction entry, so the deleted transaction is gone; the stale value can come from cached budget or income totals that were not invalidated by deleting an older entry.

Budget totals are derived from entry aggregation queries. Older versions of Sure used the most recent entry update timestamp as part of the cache key, which meant deleting an older transaction could leave the cache key unchanged.

The entry aggregate cache version now includes both:

- The current entry count
- The newest entry `updated_at` timestamp

Because the count changes when an entry is deleted, budget and income aggregate caches are invalidated even when the deleted transaction was not the most recently updated entry.

Confirm the installed version includes the cache invalidation fix for `Family#entries_cache_version`, then re-check the affected budget after the next request or cache refresh. The regression test is:

```bash
bin/rails test test/models/family_test.rb
```

Chat fails immediately on a fresh family with a strict OpenAI-compatible provider Copy Chapter

Some strict OpenAI-compatible providers (not OpenAI itself) reject chat requests with a schema validation error when a family has no accounts, categories, merchants, tags, or tickers yet.

Rule runs fail silently Copy Chapter

If auto-categorization or merchant detection rules appear to do nothing, the background job may have failed without surfacing an error in the UI.

Async rule run failures are now logged to the debug log. Go to **Settings → Debug** and look for entries from the `rule_run` category. Each failed run includes the error class, message, and the rule that triggered it.

You can also check worker logs directly:

```bash
docker compose logs worker
```

Common causes include:

- **LLM provider errors** — The AI provider returned an error or timed out. Check your `OPENAI_ACCESS_TOKEN` and provider connectivity.
- **Auto-categorize provider failures** — The provider returned an unexpected response format. These are now propagated and logged rather than silently swallowed.
- **Worker not running** — Rules run in the background via Sidekiq. Verify the `worker` container is healthy.

App crashes for a family with an invalid timezone Copy Chapter

If a family's timezone setting contains an unrecognized IANA zone name (for example, after a tzdata rename like Europe/Kiev → Europe/Kyiv), Sure now falls back to the application default timezone instead of crashing.

Chat fails immediately on a new account with a strict OpenAI-compatible provider Copy Chapter

Some strict OpenAI-compatible providers (not OpenAI itself) reject chat requests with a schema validation error when a family has no tags, merchants, or categories yet. This happens because the assistant's tool schemas include enum fields built from family data — an empty family produces enum: [], which is invalid JSON Schema.

Sure builds tool schemas for the assistant using family data (account names, categories, merchants, tags, tickers). A family with none of this data produces `enum: []` for those fields, which is invalid JSON Schema. OpenAI tolerates it, but strict providers reject the entire request before the model runs.
`Family#timezone` is a free-text field. If the stored value becomes stale — due to a tzdata rename, a database restore from an older backup, or a direct database edit — the app previously raised an `ArgumentError` on every request for that family, including the login page.

Sure validates the timezone value against `ActiveSupport::TimeZone` before using it. If the value is unrecognized, the app falls back to the default timezone and logs a warning to **Settings → Debug** under the `timezone` category. The log is debounced to once per day per family so it does not flood the debug log.

To fix the root cause, update the family's timezone to a valid IANA zone name from **Settings → Profile**.
Sure builds tool schemas dynamically from your family's data (account names, categories, merchants, tags, tickers). When none of that data exists yet, the schema contains `enum: []`, which is invalid JSON Schema. OpenAI tolerates it, but strict OpenAI-compatible providers reject the entire request before the model runs.

Empty enum arrays are now pruned from tool schemas before the request is sent, falling back to a plain `string` type. This fix applies to both chat tool definitions and the `/mcp` endpoint's `tools/list`.

If you are on an older version and cannot upgrade, add at least one account, category, or tag to the family — this populates the enum and avoids the empty-array case.

Chat shows "assistant not available" before the model finishes Copy Chapter

Self-hosted users running a local model (Ollama, LM Studio, etc.) may see the chat fail with "assistant not available" even though the model is still generating a reply and tokens are being billed.

Sure uses a whole-turn watchdog (`AI_RESPONSE_TIMEOUT`, default 90 seconds) that starts when the message is queued. Custom OpenAI-compatible providers use a synchronous code path — nothing renders until the full reply is generated — so the watchdog fires before the model finishes.

Tool-using turns make this worse: each tool call adds another full model round. The total time the watchdog must cover is:

```text
(1 + ASSISTANT_MAX_TOOL_CALL_ITERATIONS) × OPENAI_REQUEST_TIMEOUT
  + tool execution time + queue wait
```

With the defaults (`ASSISTANT_MAX_TOOL_CALL_ITERATIONS=5`, `OPENAI_REQUEST_TIMEOUT=60`), a worst-case turn can take up to 360 seconds of model time — far beyond the 90-second default.

The most effective approach is to lower `ASSISTANT_MAX_TOOL_CALL_ITERATIONS` (reducing the worst-case bound) and then size `AI_RESPONSE_TIMEOUT` using the formula above.

For a local Ollama setup:

```bash
OPENAI_REQUEST_TIMEOUT=300
ASSISTANT_MAX_TOOL_CALL_ITERATIONS=2
AI_RESPONSE_TIMEOUT=1200
```

You can also set **Chat Response Timeout** from **Settings → Self-Hosting → AI Provider** in the UI. The environment variable takes precedence.

See [Chat response timeout](/llm-support#chat-response-timeout) for full sizing guidance.

Why is Sure not running auto-categorization and merchant detection on the same transactions again? Copy Chapter

Sure caches AI-generated results to avoid redundant API calls and costs. Once a transaction has been processed by AI rules, it won't be re-processed unless you explicitly reset the AI cache.

When AI rules process transactions, Sure stores:

- **Enrichment records** - Which attributes were set by AI (category, merchant, etc.)
- **Attribute locks** - Prevents rules from re-processing already-handled transactions

This caching ensures:

- Transactions aren't sent to the LLM repeatedly
- API costs are minimized
- Processing is faster on subsequent rule runs

To have AI rules re-process transactions, you need to reset the AI cache:

1. Go to **Settings** → **Rules**
2. Click the menu button (three dots)
3. Select **Reset AI cache**
4. Confirm the action

After resetting, the next time rules run (either manually or during a sync), AI will re-process all transactions.

**Note:** This will incur API costs if using a cloud provider.

The reset runs in the background. You can track its progress and see how many AI cache entries were removed in **Settings → Debug**, filtered by the `ai_cache_reset` category. Each run logs when it starts, how many entries were removed per scope, and any records that could not be cleared.

Common scenarios for resetting the cache:

- **Switching LLM models** - Different models may produce better categorizations
- **After system updates** - New versions may have improved prompts
- **Fixing miscategorizations** - When AI made systematic errors
- **Testing** - During development or evaluation of AI features

The AI cache is automatically cleared when you change the OpenAI model setting.

The reset runs as a background job. You can confirm it completed — and see a breakdown of how many AI cache entries were removed — in the debug log:

1. Go to **Settings** → **Debug**
2. Filter by category **`ai_cache_reset`**

You will see:
- An **info** entry when the reset is enqueued from the rules page
- An **info** entry when the job starts on a worker
- A **completion** entry with the number of enrichments deleted, broken down by scope
- **warn** entries for any individual records that could not be cleared
- An **error** entry if the job could not be enqueued at all

If you see the enqueue entry but no start entry, the job never reached a worker — check that your worker container is running.

File: guides/key-concepts/account-types.mdx Copy Chapter

title: All Account Types Sure Offers Copy Chapter

All Account Types Sure Offers

Sure supports a comprehensive range of account types to track your complete financial picture. This page provides a complete reference of all available account types and their subtypes.

Overview: Assets vs. Liabilities Copy Chapter

Asset Accounts Copy Chapter

Cash (Depository) Copy Section

Liquid funds in bank accounts.

Investment Copy Section

Investment accounts hold securities and have tax treatment based on account type.

United States

United Kingdom

Canada

Australia

Europe

Generic (Available Everywhere)

Crypto Copy Section

Cryptocurrency holdings.

[!NOTE]
Only exchange accounts support manual trade entry. Wallet accounts are sync-only.

Property Copy Section

Real estate assets.

Additional fields:

• Address
• Area (square feet or square meters)
• Year built

Vehicle Copy Section

Cars, trucks, and other vehicles.

Additional fields:

• Make
• Model
• Year
• Mileage (miles or kilometers)

Other Asset Copy Section

Anything of value that doesn't fit other categories:

• Collectibles (art, antiques, coins)
• Jewelry and watches
• Equipment
• Other valuables

Liability Accounts Copy Chapter

Credit Card Copy Section

Track credit card balances and spending.

Additional fields:

Loan Copy Section

Track mortgages, auto loans, student loans, and other installment debt.

Additional fields:

[!TIP]
For fixed-rate loans, Sure automatically calculates the monthly payment based on your original balance, interest rate, and term.

Other Liability Copy Section

Debts that don't fit the above categories:

• Personal loans from friends/family
• Medical bills
• IOUs
• Tax obligations

Tax Treatment Explained Copy Chapter

Investment accounts have different tax implications:

[!IMPORTANT]
Tax treatment in Sure is for informational and organizational purposes. Consult a tax professional for tax advice specific to your situation.

Choosing the Right Account Type Copy Chapter

Account Sharing and Permissions Copy Chapter

Sure supports sharing accounts with other family members, allowing collaborative financial management while maintaining appropriate access controls.

How Account Sharing Works Copy Section

Accounts can be shared with other members of your family with different permission levels:

Permission Levels:

Sharing an Account Copy Section

To share an account with family members:

1. Navigate to the account you want to share
2. Open the account settings or details page
3. Find the "Sharing" or "Permissions" section
4. Click Share Account or Manage Access
5. Select the family member you want to share with
6. Choose their permission level
7. Click Save or Share

Managing Shared Accounts Copy Section

As an account owner:

• You maintain full control over accounts you create
• You can modify or revoke sharing permissions at any time
• You can see who has access to each account

As a shared user:

• Shared accounts appear in your account list
• Your available actions depend on your permission level
• You can see who owns the account

Account Scoping Copy Section

Account sharing affects how data appears throughout Sure:

Dashboard and reports:

• Your dashboard shows all accounts you own plus accounts shared with you
• Net worth calculations include all accessible accounts
• Reports and budgets can be filtered by account ownership

Transactions and activity:

• You can view transactions for any account you have access to
• Edit permissions allow you to categorize, tag, and modify transactions
• Full access allows you to delete transactions and manage account settings

Provider connections:

• Only account owners and users with full access can manage provider connections
• Synced data is visible to all users with access to the account

Family-Level Features Copy Section

Some features operate at the family level and are accessible to all family members:

• Recurring transactions: Scoped to accounts you have access to
• Merchants: Shared across the family for consistent categorization
• Categories and tags: Available to all family members
• Rules: Can be created by any family member and apply to their accessible accounts

[!IMPORTANT]
Account sharing is designed for trusted family members. Users with edit or full access permissions can modify financial data, so only share accounts with people you trust.

Privacy and Security Copy Section

What's shared:

• Account balances and transaction history
• Holdings and investment details (for investment accounts)
• Account metadata (name, type, institution)

What's not shared:

• Your login credentials
• Provider API keys (unless explicitly configured)
• Personal settings and preferences

Admin controls:

• Family admins can manage provider connections for the entire family
• Only admins can configure third-party provider integrations
• Account owners always retain control over their own accounts

Related Pages Copy Chapter

• How Asset Accounts Work
• How Debt Accounts Work
• Managing Investment Accounts
• Transfers Between Accounts

File: guides/key-concepts/debt-accounts.mdx Copy Chapter

title: How Debt Accounts Work Copy Chapter

How Debt Accounts Work

Debt accounts (also called liability accounts) track money you owe to others. This includes credit cards, loans, and any other obligations.

Why Debt Math Seems "Backwards" Copy Chapter

If you're used to thinking about asset accounts, debt accounts can feel counterintuitive at first. Here's the key difference:

And transactions work in the opposite direction from assets:

[!TIP]
Think of a debt balance as "Amount Owed" rather than "money I have." A higher number means you owe more, not that you have more.

Credit Card Example Copy Chapter

Let's walk through a typical credit card scenario:

Notice how spending increases the balance (you owe more) and payments decrease it (you owe less).

Overpayment Scenario Copy Section

What happens if you pay more than you owe?

A negative balance on a credit card means you've overpaid—the credit card company owes you money. This might happen from:

• Overpayment
• Refunds for returned purchases
• Statement credits or rewards

Types of Debt Accounts Copy Chapter

Sure supports three types of liability accounts:

Credit Card Copy Section

Track your credit card balances and spending. Credit card accounts can include:

Loan Copy Section

Track mortgages, auto loans, student loans, and other installment debt.

Loan accounts support additional fields:

[!NOTE]
For fixed-rate loans, Sure can calculate your monthly payment automatically based on the original balance, interest rate, and term.

Other Liability Copy Section

For debts that don't fit the above categories:

• Personal loans from friends/family
• Medical bills
• IOUs
• Tax obligations

How Debt Affects Net Worth Copy Chapter

Liabilities reduce your net worth:

Net Worth = Total Assets - Total Liabilities

When you pay down debt, your net worth increases (even though your cash decreases). This is because the debt reduction outweighs the cash spent—you're converting a liquid asset (cash) into reduced liability (less debt).

Example: Paying Off a Credit Card Copy Section

Your net worth stays the same because you traded $500 of cash for $500 of debt reduction. But now you have no credit card debt!

Adding Debt Accounts Copy Chapter

To add a debt account:

1. Click + Add Account on your dashboard
2. Select the liability type (Credit Card, Loan, or Other Liability)
3. Enter your account details:
   • Account name
   • Current balance (the amount you owe)
   • For loans: interest rate, term, and rate type
4. Click Create Account

[!IMPORTANT]
Make sure to select a liability account type (Credit Card, Loan, or Other Liability) when adding debt. If you accidentally create a Cash account for your credit card, the balance calculations will be incorrect.

Understanding Loan Payments Copy Chapter

When you make a loan payment, the payment typically covers:

1. Interest - Cost of borrowing
2. Principal - Reducing the amount you owe

Sure tracks your loan balance, which represents the remaining principal. As you make payments, the balance decreases until the loan is paid off.

[!TIP]
To track loan payments accurately, create a transfer from your checking account to your loan account. This properly reflects the payment in both accounts.

File: guides/key-concepts/investment-accounts.mdx Copy Chapter

title: Managing Investment Accounts Copy Chapter

Managing Investment Accounts

Investment accounts in Sure go beyond simple balance tracking. They help you understand your portfolio through holdings, trades, cost basis tracking, and investment activity labels.

Understanding Holdings Copy Chapter

A holding represents your position in a specific security. For example, if you own 50 shares of Apple stock, that's one holding.

Each holding tracks:

• Security - What you own (stock, ETF, mutual fund, crypto)
• Quantity - How many shares or units you hold
• Price - Current market price per share
• Amount - Total current value (quantity x price)
• Cost Basis - What you originally paid

Recording Trades Copy Chapter

Investment accounts support manual trade entry to track your buy and sell activity.

Trade Types Copy Section

When recording a trade, you can specify:

• Buy: Purchase of securities
• Sell: Sale of securities
• Dividend: Dividend income (recorded as a trade with qty: 0 and price: 0)
• Interest: Interest income (recorded as a trade with qty: 0 and price: 0)

Recording Dividends and Interest Copy Section

Dividends and interest are recorded as trades to maintain data integrity:

Dividends:

• Require a security selection (the security that paid the dividend)
• Recorded with qty: 0 and price: 0
• Amount represents the dividend payment received

Interest:

• Security selection is optional
• If no security is selected, Sure creates a synthetic cash security for the account
• Recorded with qty: 0 and price: 0
• Amount represents the interest earned

This approach ensures all investment income is properly tracked while maintaining the requirement that trades reference a security.

Transaction Fees Copy Section

Trades support an optional fee field to track transaction costs:

• Fees are included in the total amount calculation: qty × price + fee
• Fees default to 0 if not specified
• Useful for tracking brokerage commissions, exchange fees, or other trading costs

For example:

• Buy 10 shares at $100/share with a $5 fee = $1,005 total
• Sell 10 shares at $110/share with a $5 fee = $1,095 total (proceeds after fee)

To add a fee to a trade:

1. Open the trade form (create or edit)
2. Enter the fee amount in the fee field
3. The total amount updates automatically to include the fee

Fees are automatically factored into your cost basis calculations and realized gains/losses.

Securities Types Copy Chapter

Sure supports various security types:

Cost Basis Tracking Copy Chapter

Cost basis is the original purchase price of your investments. It's essential for:

• Calculating gains and losses
• Understanding investment performance
• Tax reporting

Cost Basis Sources Copy Section

Sure tracks cost basis from three sources, in order of priority:

This hierarchy ensures your manual entries always take precedence, calculated values override provider data, and provider data is used when nothing else is available.

Setting Cost Basis Manually Copy Section

You can set cost basis in two ways:

From the Holdings List:

1. Navigate to your investment account
2. Find the holding in your portfolio
3. Click the pencil icon next to the average cost
4. Enter either:
   • Total cost basis: The total amount you paid for all shares
   • Per-share cost: The average price per share
5. Click Save

From the Holding Drawer:

1. Click on a holding to open its detail drawer
2. In the Overview section, click the pencil icon next to "Average Cost"
3. Enter the cost basis (total or per-share)
4. Click Save

[!TIP]
The cost basis editor provides real-time conversion between total and per-share values. Enter whichever format you have available, and Sure calculates the other automatically.

Lock Protection Copy Section

When you manually set a cost basis, Sure automatically locks it to prevent automatic updates from overwriting your value. You'll see a lock icon indicating the value is protected.

This ensures your manual entries remain intact during account syncs.

Unlocking Cost Basis Copy Section

If you want Sure to recalculate cost basis from your trades:

1. Open the holding drawer
2. Scroll to the Settings section
3. Find "Cost basis locked"
4. Click Unlock

After unlocking:

• The lock icon disappears
• Future syncs can update the cost basis
• Calculated values (from trades) will replace the manual value

Recording Trades Copy Chapter

Investment accounts support recording various types of trades to track your portfolio activity.

Trade Types Copy Section

Recording Dividends and Interest Copy Section

Dividends and interest are recorded as trades with zero quantity and zero price, allowing them to be associated with specific securities while maintaining data integrity.

Dividends:

• Require a security selection (the stock/fund paying the dividend)
• Recorded as a trade with qty: 0 and price: 0
• Amount represents the dividend payment received

Interest:

• Security selection is optional
• When no security is selected, Sure creates a synthetic cash security for the account
• Recorded as a trade with qty: 0 and price: 0
• Amount represents the interest earned

To record a dividend or interest payment:

1. Navigate to your investment account
2. Click + New Trade
3. Select Dividend or Interest from the type dropdown
4. For dividends: Select the security that paid the dividend
5. For interest: Optionally select a security, or leave blank for cash interest
6. Enter the amount received
7. Set the date
8. Click Save

[!NOTE]
Dividends require a security selection, while interest can be recorded without one. When no security is selected for interest, Sure automatically creates a per-account synthetic cash security (kind: cash, offline: true) to maintain data integrity.

Trade Fees Copy Section

All trades support an optional fee field to track transaction costs:

• Fees are included in the total amount calculation: total = (qty × price) + fee
• Fees default to 0 if not specified
• Fees are tracked separately for accurate cost basis calculations

Investment Activity Labels Copy Chapter

Activity labels help you classify investment transactions. They appear as badges in your transaction list and help you understand your investment activity at a glance.

Recording Dividends and Interest Copy Chapter

Dividends and interest are recorded as trades with zero quantity and zero price. This approach maintains data integrity while properly tracking investment income:

• Dividends require a security to be selected (the stock or fund paying the dividend)
• Interest can optionally specify a security, or will use a synthetic cash security for the account
• Both appear in your holdings and trade history
• Both are properly labeled with their respective activity types
• The zero-quantity, zero-price approach preserves the trade model's required security association

When creating a dividend or interest transaction:

1. Select Dividend or Interest from the trade type dropdown
2. For dividends: Choose the security paying the dividend (required)
3. For interest: Optionally select a security, or leave blank to use the account's cash position
4. Enter the amount received
5. The trade is created with qty: 0 and price: 0, maintaining the security association

Trade Fees Copy Chapter

All trades support an optional fee field to track transaction costs like brokerage commissions, exchange fees, or other trading expenses.

How Fees Work Copy Section

• Fees are included in the total transaction amount: Total = (Quantity × Price) + Fee
• Fees default to 0 if not specified
• Fees can be added when creating or editing trades
• The fee field auto-submits like other trade fields

Adding Fees to Trades Copy Section

When creating or editing a trade:

1. Enter the quantity and price as usual
2. Add the fee amount in the Fee field
3. The total amount updates automatically to include the fee
4. Save the trade

Example: Buying 10 shares at $50 with a $5 commission:

• Quantity: 10
• Price: $50
• Fee: $5
• Total: $505 (10 × $50 + $5)

Fees are particularly important for:

• Accurate cost basis calculations
• Understanding true investment returns
• Tax reporting and record keeping

Available Activity Labels Copy Section

[!NOTE]
Dividends and interest are recorded as trades with zero quantity and zero price. Dividends require a security selection, while interest can optionally use a synthetic cash security if no specific security is selected.

Setting Labels Manually Copy Section

1. Open a transaction from an investment or crypto account
2. Scroll to the Settings section
3. Find "Activity type"
4. Select a label from the dropdown
5. The change saves automatically

Setting Labels with Rules Copy Section

Create rules to automatically label transactions based on patterns:

1. Go to Settings > Rules
2. Create a new rule
3. Set conditions (e.g., "IF transaction name contains 'DIVIDEND'")
4. Add action: "Set investment activity label"
5. Choose the label (e.g., "Dividend")
6. Save the rule

Example rules:

• IF name contains "DIVIDEND" THEN set label to "Dividend"
• IF name contains "INTEREST" THEN set label to "Interest"
• IF name contains "FEE" THEN set label to "Fee"

[!NOTE]
Internal movement labels (Transfer, Sweep In, Sweep Out, Exchange) are automatically excluded from budget calculations since they represent cash management rather than income or expenses.

Tax Treatment Categories Copy Chapter

Investment accounts have different tax implications based on their type:

Sure automatically assigns tax treatment based on account subtype, but you can adjust it manually if needed.

Understanding Gains and Losses Copy Chapter

Sure helps you track two types of gains:

Unrealized Gains/Losses Copy Section

Paper gains or losses on holdings you still own:

Unrealized Gain = Current Value - Cost Basis

If you bought 10 shares at $100 ($1,000 total) and they're now worth $1,200, you have an unrealized gain of $200.

Realized Gains/Losses Copy Section

Actual gains or losses from securities you've sold. These are what matter for taxes.

The Trend indicator on each holding shows your unrealized gain or loss, calculated from your cost basis. If cost basis is unknown (no trades and no manual entry), the trend won't display.

Crypto-Specific Features Copy Chapter

Crypto accounts work similarly to investment accounts but have unique characteristics:

• Exchange accounts support manual trade entry, letting you record buys and sells
• Wallet accounts are sync-only, holdings are updated through provider connections

Crypto is taxable by default, though it can be held in tax-advantaged accounts (for example, a self-directed IRA).

Adding Investment Accounts Copy Chapter

1. Click + Add Account on your dashboard
2. Select Investment or Crypto
3. Choose the appropriate subtype (see Account Types for all options)
4. Enter your account details:
   • Account name
   • Current balance
   • Tax treatment (if different from default)
5. Click Create Account

After creating the account, you can add holdings manually or connect a provider to sync them automatically.

File: guides/key-concepts/transfers.mdx Copy Chapter

title: Transfers Between Accounts Copy Chapter

Transfers Between Accounts

A transfer moves money between your own accounts. Unlike income or expenses, transfers don't change your net worth—they simply move funds from one place to another.

How Transfers Work Copy Chapter

Every transfer consists of two linked transactions:

1. Outflow - Money leaving one account (negative amount)
2. Inflow - Money entering another account (positive amount)

These two transactions are linked together as a single transfer.

Example: Moving Money to Savings Copy Section

When you transfer $500 from checking to savings:

Your total net worth stays the same—the money simply moved from one account to another.

Transfer Types Copy Chapter

Sure recognizes different types of transfers based on the destination account:

Funds Movement Copy Section

General transfers between asset accounts:

• Checking to savings
• Savings to money market
• Between investment accounts

These are excluded from budgets because they don't represent spending or income.

Credit card payment Copy Section

When you pay your credit card bill, Sure creates a cc_payment transfer:

• Outflow from your checking account
• Inflow to your credit card (reducing your debt)

This is excluded from budgets because the spending already happened when you used the credit card.

When syncing transactions from a provider, Sure automatically classifies transactions to credit card accounts as credit card payment transfers.

Loan payment Copy Section

Payments to loan accounts (mortgage, auto, student loans) are treated as loan_payment transfers.

[!NOTE]
Loan payments can be treated as expenses in budgets since they represent an ongoing financial obligation, even though they also reduce your debt.

When syncing transactions from a provider, Sure automatically classifies transactions to loan accounts as loan payment transfers.

Investment Contribution Copy Section

Transfers to investment or crypto accounts:

• Contributing to your 401(k)
• Adding funds to a brokerage account
• Moving money to a crypto exchange

These are excluded from budgets because you're saving/investing, not spending.

Creating Transfers Manually Copy Chapter

To create a transfer:

1. Go to the Transactions page
2. Click + New Transaction
3. Select Transfer
4. Choose:
   • From account - Where money is coming from
   • To account - Where money is going
   • Amount - How much to transfer
   • Date - When the transfer occurred
5. Click Add transaction

Sure automatically creates both the outflow and inflow transactions and links them together.

Automatic Transfer Matching Copy Chapter

When you sync accounts with a provider (Plaid, SimpleFIN, etc.), Sure attempts to automatically match transfers between accounts.

How Matching Works Copy Section

Sure looks for transaction pairs that:

• Are from different accounts in the same family
• Have opposite amounts (one positive, one negative)
• Occurred within a date window

Date Windows Copy Section

Suggested Matches Copy Section

When Sure finds a potential transfer match, it creates a pending transfer suggestion. You can:

1. Confirm - Accept the match and link the transactions
2. Reject - Dismiss the match (transactions remain separate)

To review suggested transfers:

1. Open a transaction that may be part of a transfer
2. Look for transfer match suggestions
3. Confirm or reject as appropriate

Cross-Currency Transfers Copy Chapter

When transferring between accounts with different currencies:

• Sure validates that amounts have opposite signs
• The exact amounts don't need to match (due to exchange rates)
• Both transactions are linked as a transfer

Example: Transferring from a USD checking account to a EUR savings account:

The transfer is valid because one amount is negative and one is positive, even though the numbers differ due to the exchange rate.

Transfer Summary Totals Copy Chapter

When viewing your transaction list filtered by transfers, Sure displays Inflow and Outflow totals instead of the standard Income and Expenses labels.

How It Works Copy Section

Transfer-only filter:

• When filtering exclusively by "Transfer" type, the summary bar shows:
  • Inflow: Total positive transfer amounts (money coming in)
  • Outflow: Total negative transfer amounts (money going out)

Mixed filters:

• When filtering by transfers along with other transaction types (income, expenses), the summary bar shows standard Income/Expenses labels
• Transfer amounts are excluded from these totals since they don't represent actual income or spending

This helps you understand your cash movement patterns when reviewing transfers in isolation.

[!NOTE]
When filtering by both transfers and other transaction types, transfer amounts are excluded from income and expense totals to avoid confusion.

How Transfers Affect Budgets Copy Chapter

Transfers are generally excluded from budget calculations because they don't represent actual spending or income:

[!TIP]
If you want to budget for loan payments, you may want to track them as expenses. Sure treats loan payments specially since they represent ongoing obligations.

Understanding Net Worth Impact Copy Chapter

Transfers are zero-sum for net worth:

• Moving $500 from checking to savings: Net worth unchanged
• Paying $500 to credit card: Net worth unchanged (reduced cash = reduced debt)
• Contributing $500 to 401(k): Net worth unchanged (reduced cash = increased investments)

The only time a transfer affects net worth is if there are fees involved (which would be a separate expense transaction).

Common Transfer Scenarios Copy Chapter

Paying Off a Credit Card Copy Section

1. Money leaves your checking account (-$500)
2. Credit card balance decreases (-$500 debt)
3. Net worth: unchanged

Making a Mortgage Payment Copy Section

1. Money leaves your checking account (-$2,000)
2. Loan balance decreases (-$1,700 principal, $300 goes to interest)
3. Note: The interest portion is technically an expense

[!IMPORTANT]
Mortgage payments include both principal (reducing debt) and interest (an expense). Sure tracks the full payment as a loan transfer, but the interest portion represents a true cost.

Contributing to Retirement Copy Section

1. Money leaves your checking account (-$500)
2. Investment account balance increases (+$500)
3. Net worth: unchanged (cash converted to investments)

Transferring Between Banks Copy Section

1. Money leaves Bank A checking (-$1,000)
2. Money arrives at Bank B checking (+$1,000)
3. Net worth: unchanged

Troubleshooting Transfers Copy Chapter

Duplicate Transactions Copy Section

If you see both a transfer and separate expense/income transactions:

• Check if the transactions should be linked as a transfer
• Confirm or reject the transfer suggestion
• Delete duplicate transactions if needed

Unmatched Transfers Copy Section

If Sure didn't automatically match a transfer:

• The amounts may not match exactly (due to fees or timing)
• The dates may be too far apart
• You can manually create a transfer to link them

Wrong Transfer Type Copy Section

If a transfer is categorized incorrectly:

• Check that both accounts are the correct type
• The transfer type is determined by the destination account

File: guides/key-concepts/untitled-page.mdx Copy Chapter

title: How Asset Accounts Work Copy Chapter

How Asset Accounts Work

Assets are things you own that have monetary value. In Sure, asset accounts track your wealth—from the cash in your checking account to the value of your home.

Understanding Asset Balances Copy Chapter

Asset account balances work intuitively:

• Income increases your balance (money coming in)
• Expenses decrease your balance (money going out)

Example: Checking Account Copy Section

Let's walk through a simple example:

This matches what you see in your bank account—straightforward and predictable.

Types of Asset Accounts Copy Chapter

Sure supports six types of asset accounts:

Cash (Depository) Copy Section

Liquid funds you can access immediately. Includes:

Investment Copy Section

Accounts that hold securities like stocks, bonds, and mutual funds. Investment accounts have additional features for tracking holdings, trades, and cost basis. See Managing Investment Accounts for details.

Crypto Copy Section

Cryptocurrency holdings, either in:

[!NOTE]
Only exchange accounts support manual trade entry. Wallet accounts are sync-only.

Property Copy Section

Real estate you own:

Property accounts can track additional details like address, area (square footage), and year built.

Vehicle Copy Section

Cars, trucks, motorcycles, and other vehicles you own. Vehicle accounts can track make, model, year, and mileage.

Other Asset Copy Section

Anything else of value that doesn't fit the categories above:

• Collectibles (art, antiques, coins)
• Jewelry and watches
• Equipment
• Other valuables

Liquid vs. Illiquid Assets Copy Chapter

Sure distinguishes between liquid and illiquid assets:

Liquid assets can be quickly converted to cash without significant loss of value:

• Cash accounts (checking, savings)
• Most investments (stocks, bonds, ETFs)

Illiquid assets take time to sell or may lose value if sold quickly:

• Property
• Vehicles
• Some investments (private equity, real estate funds)
• Other assets (collectibles, jewelry)

This distinction helps you understand not just your total net worth, but how much of it you could access quickly if needed.

How Assets Affect Net Worth Copy Chapter

Your net worth is calculated as:

Net Worth = Total Assets - Total Liabilities

Every asset account contributes positively to your net worth. When asset values increase (your investments grow, your home appreciates), your net worth increases. When you spend from asset accounts, that balance decreases—but the money likely went toward something (an expense, a purchase, or a debt payment).

[!TIP]
For a complete picture of your finances, make sure to add both your assets and your debt accounts. Sure calculates your true net worth by subtracting what you owe from what you own.

Adding Asset Accounts Copy Chapter

To add an asset account:

1. Click + Add Account on your dashboard
2. Select the asset type (Cash, Investment, Crypto, Property, Vehicle, or Other Asset)
3. Enter your account details:
   • Account name
   • Current balance
   • Subtype (if applicable)
4. Click Create Account

Your new asset account will appear in your accounts list and contribute to your net worth calculation immediately.

File: guides/app-features/assistant-sidebar.mdx Copy Chapter

title: "AI assistant sidebar" Copy Chapter

Sure includes an AI assistant sidebar on desktop. If you do not want to use it yet, you can hide it and bring it back later.

Hide or show the AI sidebar on desktop Copy Chapter

On desktop, use the panel-right button in the top bar to toggle the right-hand AI sidebar.

• Click it once to collapse the AI sidebar
• Click it again to reopen the AI sidebar
• Sure saves this preference to your account

This is useful if you want more room for the main app content or simply do not want to use the assistant yet.

When the sidebar is hidden by default Copy Chapter

Sure can also hide the AI sidebar by default for some people:

• New member and guest users start with the AI sidebar hidden when AI is not available
• admin users still see it by default so they can finish AI setup or troubleshooting

If AI becomes available later, you can reopen the sidebar at any time with the same desktop toggle.

Related settings Copy Chapter

• For AI provider setup, see LLM support
• For general app settings, see Settings

File: guides/app-features/budgets.mdx Copy Chapter

title: "Budgets" Copy Chapter

Budgets

Budgets help you set spending limits for different categories and track how well you're sticking to them throughout the month.

How Budgets Work Copy Chapter

When you create a budget, you assign a spending limit to a category. As you spend money in that category, Sure tracks your progress and shows you:

• Amount spent so far this month
• Amount remaining in your budget
• Status indicators showing if you're on track, near your limit, or over budget

Planning ahead Copy Section

You can create budgets for future months, up to 2 years in advance. This lets you plan your spending ahead of time and set category limits before the month begins. Navigate forward using the month selector to set up upcoming budgets.

Setting Up Category Budgets Copy Chapter

Each category can have its own budget. For example, you might set:

• Food & Dining: $500/month
• Entertainment: $200/month
• Transportation: $300/month

Sure shows helpful daily suggestions like "$29.91 suggested per day for 11 remaining days" to help you pace your spending.

When editing a subcategory's budget, you'll see "Shared" as the placeholder text. Leave the field empty or set it to $0 to share the parent category's budget. Hover over the field to see the tooltip: "Leave empty to share parent's budget".

Subcategories and Shared Budgets Copy Chapter

You can organize your spending further with subcategories. For example, "Food & Dining" might include:

• Coffee & Takeout
• Groceries
• Restaurants

Individual budgets Copy Section

Give each subcategory its own limit. This works well when you want strict control over specific types of spending.

Shared budgets Copy Section

Leave a subcategory's budget empty to share the parent category's budget. This is great when you want flexibility across related expenses.

Example: Set "Food & Dining" to $500, but leave the subcategories without individual limits. Now all your food spending draws from the same $500 pool, whether you're buying groceries or eating out.

When a subcategory shares its parent's budget, you'll see a "(shared)" label next to the budget amount, making it clear which subcategories are drawing from the shared pool.

Mixed approach Copy Section

Combine both methods. Set a fixed budget for some subcategories while others share the remaining amount.

Example:

• Food & Dining: $500 total
• Restaurants: $100 (fixed limit)
• Groceries and Coffee share the remaining $400

When you set an individual budget for a subcategory, that amount is "ring-fenced" from the parent budget. Only that subcategory can use it, and it won't be available to other subcategories sharing the parent's budget.

How it works:

• Restaurants has $100 remaining ($100 budget - $0 spent)
• Groceries and Coffee share $350 remaining ($400 shared pool - $50 spent between them)
• The parent Food & Dining shows the total remaining across all subcategories

Parent auto-aggregation Copy Section

When you edit a subcategory's budget, the parent category's budget automatically updates to reflect the change. You don't need to manually adjust the parent — Sure keeps it in sync for you.

How it works:

• When you increase a subcategory's budget, the parent's budget increases by the same amount.
• When you decrease a subcategory's budget, the parent's budget decreases accordingly.
• If the parent had extra budget beyond the sum of its subcategories (a "reserve"), that reserve is preserved during the update.
• The parent's budget never drops below the combined total of its subcategories.

Example:

• Food & Dining starts at $500 with Restaurants at $100 and Groceries at $150 ($250 reserve in the shared pool)
• You increase Groceries from $150 to $200
• Food & Dining automatically updates to $550, preserving the $250 reserve

Status Indicators Copy Chapter

Sure uses color-coded badges to show your budget status at a glance:

• On Track (green) - You're within budget and pacing well
• Near Limit (yellow) - Getting close to your limit
• Over Budget (red) - You've exceeded your budget

Tax-advantaged accounts and budgets Copy Chapter

Sure automatically excludes activity from tax-advantaged investment accounts when calculating budget spending. This ensures your budgets accurately reflect your day-to-day spending without being skewed by investment contributions or withdrawals.

Excluded account types:

• 401(k) accounts
• IRA accounts (Traditional and Roth)
• 403(b) accounts
• Other tax-advantaged retirement accounts

Transactions from these accounts won't count toward your budget limits, keeping your budget focused on regular income and expenses.

Tips for Effective Budgeting Copy Chapter

1. Start simple - Begin with just a few major categories before adding detail
2. Review monthly - Check your budgets at the end of each month and adjust as needed
3. Use shared budgets for categories where you want flexibility between subcategories
4. Use individual limits when you need strict control over specific spending