diff --git a/docs.json b/docs.json index 00fee1a..144970a 100644 --- a/docs.json +++ b/docs.json @@ -80,6 +80,7 @@ "providers/binance", "providers/coinbase", "providers/coinstats", + "providers/onchain-wallets", "providers/sophtron" ] }, diff --git a/guides/app-features/transactions.mdx b/guides/app-features/transactions.mdx index 4e63e12..0e40092 100644 --- a/guides/app-features/transactions.mdx +++ b/guides/app-features/transactions.mdx @@ -43,6 +43,8 @@ Categories help Sure group income and expenses consistently. You can assign a ca When there are uncategorized transactions, use the categorize flow to work through them in batches. You can assign a category to each transaction and optionally create a categorization rule so future matching transactions use the same category. +Rules can match transactions by name, amount, category, merchant, or tag. Use the **tag** condition to build rules that act on transactions already carrying a specific tag — for example, automatically categorizing everything tagged "reimbursable" or excluding tagged transactions from budgets. + Use subcategories when you want more detail within a broader category. For example, a parent category such as **Food & Dining** can contain subcategories such as **Groceries**, **Restaurants**, and **Coffee**. Budgets can use those subcategories individually or share the parent budget. ## Bulk edit transactions diff --git a/providers/enable-banking.mdx b/providers/enable-banking.mdx index a7a847a..79109ff 100644 --- a/providers/enable-banking.mdx +++ b/providers/enable-banking.mdx @@ -115,6 +115,10 @@ When syncing transactions from Enable Banking, Sure automatically detects certai See [transfers](/guides/key-concepts/transfers) for more details on how transfer types affect budgets. +### Transaction naming + +Sure extracts a clean merchant name from the remittance information your bank provides. For banks that return multi-line remittance data (common with Austrian and German banks), Sure skips technical card-terminal descriptor lines (such as POS terminal identifiers) and uses the first descriptive line as the transaction name. Known payment processor prefixes (SumUp, Square, iZettle, PayPal) are also stripped. If the merchant matches one already in your family's merchant list, Sure assigns it automatically. + ### Duplicate transaction handling Enable Banking includes robust content-based deduplication to prevent API-level duplicate transactions: diff --git a/providers/onchain-wallets.mdx b/providers/onchain-wallets.mdx new file mode 100644 index 0000000..51b396f --- /dev/null +++ b/providers/onchain-wallets.mdx @@ -0,0 +1,116 @@ +--- +title: "On-chain wallets" +description: "Track self-custody Bitcoin, EVM, and Solana wallets natively in Sure" +--- + +Sure can track self-custody cryptocurrency wallets directly — no third-party aggregator required. Link a Bitcoin, EVM-compatible, or Solana address and Sure imports balances, token holdings, and transfer history automatically. + +## Supported networks + +| Network | Address format | Notes | +| --- | --- | --- | +| Bitcoin | Base58 (P2PKH/P2SH), bech32 (segwit), bech32m (taproot) | Single address only — see [limitations](#limitations) | +| Ethereum | 0x hex | | +| Base | 0x hex | | +| Arbitrum | 0x hex | | +| Optimism | 0x hex | | +| Polygon | 0x hex | | +| Solana | Base58 public key | SPL tokens supported | + +## How it works + +Linking a wallet is a three-step flow: + +1. **Paste an address** — Sure detects which networks the address is active on. +2. **Confirm the network** — When an address is valid on more than one chain, Sure shows which ones have activity so you can pick the right one. +3. **Choose what to track** — Sure lists the tokens found at that address. Assets that can be priced are pre-selected; spam airdrops are listed but unchecked. You can adjust the selection before importing. + +After linking, Sure syncs the wallet on a recurring schedule. Balances come from a direct address summary request; transfer history is paginated separately. + +## Pricing and valuation + +On-chain wallet values depend on your market data configuration: + +- **Crypto prices**: Sure uses your configured securities provider to look up prices by symbol. Enable a crypto-capable provider (such as Binance Public) from **Settings > Self-Hosting > Market data**. +- **Currency conversion**: If your family currency is not USD, Sure also needs an exchange rate provider. [Frankfurter](https://www.frankfurter.app/) is a free option that requires no API key. + + +Without a crypto-capable market data provider, every wallet is tracked by quantity and valued at zero. The linking flow warns you before you connect a wallet, and links to the market data settings page where you can fix it. + + +### What gets priced and what does not + +Sure prices assets by symbol. A symbol is not a token's identity, so coverage is limited: + +- Well-known coins and tokens (BTC, ETH, SOL, USDC, and others) are priced correctly. +- Bridged and wrapped variants (WETH, USDC.e, USDbC) are mapped to their canonical asset and priced as that asset. +- Tokens whose symbol the provider does not list show a zero value. The quantity is still tracked correctly — a zero next to a token you know is worth something means the provider does not cover it, not that the balance is wrong. +- DeFi positions (staked ETH, LP tokens, lending positions, Solana stake accounts) are not visible. A wallet holding most of its value in a staking protocol will report only the portion held directly. + +## Transfer history + +Sure imports transfer history and creates trade entries when a price is available for the transfer date. When no price is available, Sure records a display-only entry so the transfer is visible without fabricating a cost basis. Display-only entries are automatically upgraded to trades the next time a sync runs and the price becomes available. + +### History depth + +By default, Sure reads up to 10 pages of history per address. You can raise this limit with the `ONCHAIN_HISTORY_MAX_PAGES` environment variable (maximum 200). When an address has more history than the budget allows, the wallet's manage screen notes that the history is incomplete. Balances are always accurate regardless of history depth, because they come from an address summary rather than from history. + +## Token limits + +Sure surfaces at most 200 tokens per address by default. You can raise this with `ONCHAIN_MAX_TOKENS_PER_ADDRESS` (maximum 5,000). On EVM networks, tokens are ranked by market cap so real assets are kept and airdrops fall off the end. On Solana, tokens are ordered by mint address for stability between syncs. + +Tokens already being tracked are never dropped by the cap, even if they fall outside the surfaced set on a later sync. + +## Linking a wallet + + + + Go to **Settings > Bank sync** and find **On-chain wallets** under Available connections. + + + Paste a wallet address. Sure detects which supported networks show activity at that address. + + + If the address is active on more than one network, select the correct one. If only one network shows activity, it is selected automatically. + + + Sure lists the tokens found. Assets that can be priced are pre-checked. Uncheck anything you do not want to track, then click **Link wallet**. + + + + +Never enter a seed phrase or private key. Sure only needs a public wallet address. + + +## Managing a linked wallet + +From the wallet's manage screen you can: + +- **Review tokens** — Reopen the token selection to add or remove tracked assets without changing the address. +- **Change address** — Update the address while keeping all existing accounts, holdings, and history intact. +- **Disconnect one asset** — Remove a single token from tracking. Its account becomes a manual account and stops syncing. +- **Disconnect wallet** — Remove all tracked assets for an address. Each account becomes a manual account and stops syncing. + +Disconnecting never deletes an account. Holdings are detached and the account stops updating, but the history remains. + +## Etherscan API key (optional) + +For Ethereum addresses, you can supply an Etherscan API key to increase the rate limit on transfer history requests. Balances and token detection always use the keyless Blockscout indexer regardless of whether a key is set — Etherscan does not provide a reliable token balance endpoint, so adding a key only affects history throughput. + +Set the key from the on-chain wallets settings panel under **Ethereum API key**. + +## Environment variables + +| Variable | Default | Description | +| --- | --- | --- | +| `ONCHAIN_HISTORY_MAX_PAGES` | `10` | Maximum pages of transfer history per address per sync (capped at 200). | +| `ONCHAIN_MAX_TOKENS_PER_ADDRESS` | `200` | Maximum tokens surfaced per address (capped at 5,000). | +| `ONCHAIN_DETECTION_TIMEOUT` | `10` | Seconds allowed for chain detection during linking. | + +## Limitations + +- **Bitcoin: single address only.** A standard HD wallet derives thousands of addresses. Tracking one address under-reports such a wallet. Extended key (xpub) support is not available. +- **DeFi positions are not tracked.** Staked assets, LP tokens, lending positions, and Solana stake accounts are not visible. +- **Token pricing depends on symbol coverage.** Tokens the market data provider does not list are tracked by quantity only. +- **History depth is capped.** Wallets with deep history may have incomplete cost basis reconstruction. Balances are not affected. +- **One address per network per connection.** Each linked address is tracked independently. Link additional addresses separately. diff --git a/providers/overview.mdx b/providers/overview.mdx index 2b448fe..c55c50e 100644 --- a/providers/overview.mdx +++ b/providers/overview.mdx @@ -92,6 +92,14 @@ Available providers include Yahoo Finance, Twelve Data, Tiingo, EODHD, Alpha Van - **Pricing**: Free (requires Coinbase API credentials) - **Documentation**: [Coinbase](/providers/coinbase) +### On-chain wallets + +**On-chain wallets** lets you track self-custody Bitcoin, EVM, and Solana addresses natively — no third-party aggregator required. Link a public wallet address and Sure imports balances, token holdings, and transfer history directly from the chain. + +- **Best for**: Users who hold crypto in self-custody wallets and want native tracking without a third-party service +- **Pricing**: Free (optional Etherscan API key for higher Ethereum history rate limits) +- **Documentation**: [On-chain wallets](/providers/onchain-wallets) + ### CoinStats **CoinStats** allows you to sync cryptocurrency wallets, DeFi positions, and centralized exchange accounts from multiple blockchain networks.