we-promise · mintlify · Aug 24, 2026 · Aug 24, 2026 · Aug 24, 2026 · Aug 24, 2026
diff --git a/development/clients.mdx b/development/clients.mdx
@@ -0,0 +1,70 @@
+---
+title: Sure clients
+description: Overview of the web, desktop, mobile, MCP, and API clients for Sure
+---
+
+Sure is centered on a Rails server. Every client connects to that server and uses the same accounts, users, authentication rules, and financial data. A client can be a browser, a native app, a mobile app, an automation script, or an LLM agent using Sure's MCP endpoint.
+
+## Client overview
+
+| Client | Best for | Status | Entry point |
+|---|---|---|---|
+| Web app | Full everyday use, administration, and self-hosted access from any modern browser | Primary client | Run the Rails app and visit the server URL |
+| macOS desktop app | People who want Sure in a native Mac window with system app chrome and deep-link handling | Native shell around the web app | See the desktop README |
+| Mobile app | Basic mobile access on iOS and Android, currently focused on login and account balances | Flutter companion app | See the mobile README |
+| LLM agents and assistants | Claude Desktop, GPT agents, local agents, or custom tools that need structured access to Sure data | MCP endpoint for external AI clients | See [MCP server](/development/mcp) |
+| Custom API clients | Scripts, services, importer experiments, dashboards, or other integrations | HTTP API | See the [API reference](/api-reference) |
+
+## Web app
+
+The web app is the complete Sure experience. It is the right default when a person wants to use Sure directly, manage settings, connect providers, review transactions, or work with features that may not yet be available in native clients.
+
+For self-hosting, start with the [self-hosting guide](/self-hosting). For local development, run the Rails app and visit the local server URL:
+
+```sh
+bin/dev
+```
+
+```text
+http://localhost:3000
+```
+
+The web app also serves as the surface rendered by the macOS desktop app.
+
+## macOS desktop app
+
+The macOS desktop app is a Tauri 2 shell that renders the full Sure web app in a native Mac window. On first launch, it asks for the Sure server URL, checks the server health endpoint, and then loads the normal sign-in flow.
+
+Use it when someone wants a desktop app experience without a separate desktop data model. It uses the same server, authentication, MFA, and permissions as the browser.
+
+## Mobile app
+
+The mobile app is a Flutter companion app for iOS and Android. It connects to a Sure server through the API and currently focuses on core mobile flows such as authentication and viewing account balances.
+
+Use it when someone needs phone access and the feature set they need is available in the mobile client. For the full application surface, use the web app.
+
+## LLM agents and MCP clients
+
+Sure exposes a Model Context Protocol endpoint for external assistants and agent runtimes that need structured access to financial data.
+
+Use MCP when a person wants an assistant such as Claude Desktop, a GPT agent, or a custom local agent to query Sure directly instead of copying data into a chat window. MCP access is configured server-side with a bearer token and a specific Sure user email.
+
+Because this gives the assistant read access to that user's family data, treat the MCP token like a production secret and only connect assistants and providers the user trusts.
+
+See [MCP server](/development/mcp) for setup and protocol details.
+
+## Custom API clients
+
+Custom clients can call Sure's HTTP API directly. This is the right path for scripts, services, import experiments, dashboards, and integrations that do not need an MCP-compatible agent interface.
+
+API requests can authenticate with a user-generated `X-Api-Key` header, or with OAuth2 bearer tokens from Sure's Doorkeeper authorization server for registered app clients.
+
+## Choosing a client
+
+- Start with the **web app** when a person needs the complete Sure experience.
+- Use the **macOS desktop app** when they want the web app wrapped in a native Mac application.
+- Use the **mobile app** for iOS or Android access to supported mobile flows.
+- Use **MCP** for LLM agents and assistant runtimes.
+- Use the **HTTP API** for custom software integrations.
+
+All clients connect to a Sure server the user controls or trusts. Native, mobile, API, and MCP clients do not replace the server; they are different ways to access it.
diff --git a/docs.json b/docs.json
@@ -51,6 +51,7 @@
             "pages": [
               "llm-support",
               "development/mcp",
+              "development/clients",
               "evals",
               "development/rails-provider-generator",
               "development/llm-benchmarks"
@@ -70,17 +71,18 @@
               "providers/overview",
               "providers/market-data",
               "providers/binance",
+              "providers/coinbase",
+              "providers/coinstats",
+              "providers/onchain-wallets",
               "providers/enable-banking",
               "providers/lunchflow",
               "providers/wise",
               "providers/simplefin",
               "providers/plaid",
               "providers/redbark",
               "providers/snaptrade",
-              "providers/binance",
-              "providers/coinbase",
-              "providers/coinstats",
-              "providers/sophtron"
+              "providers/sophtron",
+              "providers/up"
             ]
           },
           {

diff --git a/providers/onchain-wallets.mdx b/providers/onchain-wallets.mdx
@@ -0,0 +1,135 @@
+---
+title: On-chain wallets
+description: Track self-custody Bitcoin, EVM, and Solana wallets using public addresses
+---
+
+Sure can track wallets you hold the keys to — Bitcoin, six EVM networks, and Solana — from their **public addresses only**. No key or seed phrase is ever entered, and no API key is required for any chain.
+
+## How it works
+
+Sure reads your wallet's public address from the chain's explorer or RPC node and creates one account per **asset**, per **address**, per **network**. A wallet holding ETH and USDC on Ethereum becomes two accounts, both Crypto accounts with the wallet subtype.
+
+For each asset Sure records:
+
+- the **quantity** held, read from the chain
+- a **holding** valued at the current price, or at zero when no price is available
+- the **transfers** in and out, as investment trades when the price for that day is known, so cost basis and the value chart reconstruct back to acquisition
+
+Balances are read-only and always derived from the chain. Editing them by hand is pointless: the next sync overwrites them.
+
+## Supported networks
+
+| Network | Data source | Override env var |
+|---|---|---|
+| Bitcoin | [mempool.space](https://mempool.space) REST API | `MEMPOOL_SPACE_URL` |
+| Ethereum | Blockscout (`eth.blockscout.com`) | `BLOCKSCOUT_ETHEREUM_URL` |
+| Base | Blockscout (`base.blockscout.com`) | `BLOCKSCOUT_BASE_URL` |
+| Arbitrum | Blockscout (`arbitrum.blockscout.com`) | `BLOCKSCOUT_ARBITRUM_URL` |
+| Optimism | Blockscout (`optimism.blockscout.com`) | `BLOCKSCOUT_OPTIMISM_URL` |
+| Polygon | Blockscout (`polygon.blockscout.com`) | `BLOCKSCOUT_POLYGON_URL` |
+| Gnosis | Blockscout (`gnosis.blockscout.com`) | `BLOCKSCOUT_GNOSIS_URL` |
+| Solana | Public JSON-RPC (`api.mainnet-beta.solana.com`) | `SOLANA_RPC_URL` |
+| Solana token names | Jupiter token search (`lite-api.jup.ag`) | `SOLANA_TOKEN_LIST_URL` |
+
+Every override expects the base URL of a compatible instance, without a trailing slash. This is useful if you run your own indexer or node, or if a public endpoint rate limits you.
+
+## Pricing requirements
+
+On-chain data sources report **quantities, not values**. Prices come from Sure's market data providers, and the only provider that can quote bare crypto symbols is **Binance public** (keyless).
+
+If no crypto-capable market data provider is enabled, every on-chain wallet is tracked by quantity and **valued at zero**. The settings panel and linking modal both warn you before you link anything. On a self-hosted instance an admin can fix it from the warning itself with **Enable crypto prices** — that adds `binance_public` to the enabled providers without affecting others. Otherwise, enable it under **Settings → Self hosting → Market data providers**, or set `SECURITIES_PROVIDERS` to a comma-separated list including `binance_public`.
+
+### Exchange rates for non-USD families
+
+The crypto provider quotes in USD. Valuing a wallet in any other family currency requires an exchange rate provider. Sure's default exchange rate provider (`twelve_data`) requires an API key, so a self-hosted install without one has no FX and every wallet is valued at zero for that separate reason.
+
+Set `EXCHANGE_RATE_PROVIDER` (or **Settings → Self hosting**) to a provider you can use; `frankfurter` needs no API key. The linking UI warns about this gap specifically, naming your currency. A USD family never sees this warning.
+
+When an asset ends up valued at zero for either reason, it is recorded in **Settings → Debug logs** under the `onchain_wallet` provider with the reasons listed.
+
+## Linking a wallet
+
+Go to **Settings → Providers → On-chain wallets → Add wallet**.
+
+<Steps>
+  <Step title="Paste the address">
+    Paste the public address. Leave the network on "Detect automatically" unless you know which one you want.
+  </Step>
+  <Step title="Confirm the network">
+    If the address format belongs to several networks — every `0x` address is valid on all six EVM networks, and Bitcoin's Base58 shape overlaps Solana's — Sure probes each and asks you to choose, marking the ones where it found activity.
+  </Step>
+  <Step title="Choose assets to track">
+    The native coin and assets the data source treats as notable are pre-ticked. "Notable" means a priced holding worth more than a dollar on EVM networks, or a place on Solana's verified token list. You can still track anything listed; unpriceable assets show a quantity and a value of zero.
+  </Step>
+</Steps>
+
+Nothing is imported that you did not tick.
+
+## Managing a wallet
+
+Go to **Settings → Providers → On-chain wallets → Manage wallets**.
+
+- **Review tokens** — reopens the asset selection with the address unchanged. Use this to start tracking a token that arrived later, or stop tracking one you no longer want.
+- **Stop tracking** (per asset) — drops one asset.
+- **Change address** — corrects the address while keeping the accounts, holdings, and balance history attached to it.
+- **Disconnect wallet** — drops every asset at one address.
+
+Disconnecting never deletes an account. The provider link is removed, holdings are detached, and what you can see stays as a manual account that no longer updates. Delete the account itself if you want it gone.
+
+An address can only be tracked once per network. To change which assets are tracked, use Review tokens rather than adding the address again.
+
+## Optional Etherscan key
+
+Ethereum, and only Ethereum, can use Etherscan for transfer history. A key buys nothing except a higher rate limit on the paginated history. Add it under **Settings → Providers → On-chain wallets → Advanced**; it is stored encrypted, per family.
+
+Balances and network detection always come from the keyless Blockscout indexer. Leave the field empty unless you are being rate limited.
+
+## Rate limits and request cost
+
+All default endpoints are free and shared. Per sync, per address, the approximate cost is:
+
+| Network | Requests per sync |
+|---|---|
+| Bitcoin | 1 + up to 10 history pages |
+| EVM | 1 summary + up to 10 pages of transfers + up to 10 pages of token transfers |
+| Solana | ~2 + up to 25 transaction reads |
+
+History is capped at 10 pages by default. Raise both caps with `ONCHAIN_HISTORY_MAX_PAGES` (default 10, maximum 200); the Solana budget scales proportionally. Balances always come from an address summary, never from history, so they remain correct even when history is capped.
+
+If a source refuses or times out on paginated history, the balances are still recorded and the history is marked incomplete rather than the whole read failing.
+
+Each address surfaces at most **200 tokens** by default, settable with `ONCHAIN_MAX_TOKENS_PER_ADDRESS` (maximum 5,000). The native coin is never affected, and anything already tracked keeps syncing regardless of the cap.
+
+## Limitations
+
+**Only tokens the crypto price provider quotes get a value, and it quotes by symbol.** A symbol is not a token's identity — its contract is. In practice the provider covers major assets and little else. A zero next to a token you know is worth something almost always means the provider does not list that token, not that the balance is wrong. Check the quantity, which is read straight from the chain.
+
+**DeFi positions are not seen at all.** Staked ETH, liquidity-pool tokens, lending positions, and Solana stake accounts are invisible. Only natively-held coins and fungible tokens sitting at the address are read.
+
+**Bitcoin is one address at a time.** Extended keys (`xpub`, `ypub`, `zpub`) are not supported and are rejected as addresses. Most Bitcoin wallets are HD wallets where one extended key derives thousands of addresses; tracking a single address reports only that address's balance.
+
+**Solana token names depend on a token list.** Names come from Jupiter's token search, and only for mints it reports as verified. An unverified or unknown mint keeps a label built from its mint address and is tracked by quantity only.
+
+**Fees are not itemised.** Network fees are included in the net effect of each transfer. On Solana, native balance changes below 0.0001 SOL are treated as fees and ignored.
+
+**Bridged assets are normalised.** USDC.e, USDbC, USDT0, WETH, and similar 1:1-redeemable forms are tracked as their canonical asset.
+
+**NFTs are not tracked.** They are filtered out by token standard.
+
+## Troubleshooting
+
+**Every wallet shows a value of zero.** Either no crypto-capable market data provider is enabled, or your family currency is not USD and no exchange rate provider is configured. The linking UI says which one applies.
+
+**One token shows zero while the others are fine.** The price provider does not quote that token. Pricing is by symbol and covers major assets; long-tail tokens are tracked by quantity and valued at zero.
+
+**A Bitcoin balance is much lower than my wallet app shows.** You are tracking one address of an HD wallet. See Limitations above.
+
+**Sync says the explorer could not be reached.** The public endpoint is down, throttling you, or too slow to answer. Retry later, or point the relevant `*_URL` override at your own instance.
+
+**Solana shows balances but no transfers.** The free endpoint throttles the history methods; balances are kept and the history is marked incomplete. Set `SOLANA_RPC_URL` to your own node or a paid endpoint to get the transfers.
+
+**A token I received is not showing up.** New assets are never imported automatically. Use **Review tokens** and tick it.
+
+**Transfers appear with a value of 0 and are excluded from totals.** No price was available for that date yet. Once market data covers the range, the next sync upgrades those entries to trades automatically. If they stay at zero, the date is outside what your market data provider can serve.
+
+**Manage wallets says the history is incomplete.** The address has more transfers than one sync reads. Balances are unaffected. Raise `ONCHAIN_HISTORY_MAX_PAGES` if you need the full history and can afford the extra requests.
diff --git 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 wallets directly from their public addresses — no API key required. Supports Bitcoin, six EVM networks (Ethereum, Base, Arbitrum, Optimism, Polygon, Gnosis), and Solana.
+
+- **Best for**: Tracking self-custody crypto holdings without connecting to a third-party service
+- **Pricing**: Free (uses public blockchain explorers and RPC nodes)
+- **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.

diff --git a/providers/up.mdx b/providers/up.mdx
@@ -0,0 +1,54 @@
+---
+title: Up
+description: Connect your Up bank account to sync transactions and balances
+---
+
+Up is an Australian bank that provides a personal API for accessing your account data. Sure uses this API to sync your Up accounts, balances, and transactions.
+
+## How it works
+
+Sure connects to Up using a personal access token you generate from the Up app. Once connected, Sure syncs:
+
+- **Account balances** for your Up accounts
+- **Transaction history** with merchant and category data
+- **Automatic category mapping** from Up's categories to your Sure categories
+
+## Setting up Up
+
+<Steps>
+  <Step title="Get a personal access token">
+    Open the Up app, go to **Settings → API**, and generate a personal access token.
+  </Step>
+  <Step title="Add the connection in Sure">
+    In Sure, go to **Settings → Providers**, select **Up**, and enter your personal access token.
+  </Step>
+  <Step title="Select accounts to sync">
+    Choose which Up accounts to link to Sure.
+  </Step>
+</Steps>
+
+## Category mapping
+
+Sure automatically maps Up's transaction categories to your Sure categories on import. This means transactions you have already categorised in Up arrive in Sure with the matching category applied, rather than landing uncategorised.
+
+The mapping uses Up's child category slugs. High-confidence mappings are applied automatically. Up-specific categories with no clear Sure equivalent — such as Booze, Pets, Apps & Games, Life Admin, and Technology — are left uncategorised so your own rules or AI can handle them. A wrong auto-category is worse than none.
+
+The category is applied through Sure's enrichment system, so a category you have already set or locked on a transaction is preserved on re-sync.
+
+If your family has no categories set up yet, transactions import uncategorised rather than creating the full default category set. Mapping resumes once you set up categories through the normal UI flow.
+
+## Supported features
+
+| Feature | Supported |
+|---|---|
+| Account balances | Yes |
+| Transaction history | Yes |
+| Automatic category mapping | Yes |
+| Merchant data | Yes |
+| Automatic periodic sync | Yes |
+
+## Limitations
+
+- Requires a personal access token from the Up app
+- Only supports Up bank accounts (Australian bank)
+- Subject to Up API rate limits