> For the complete documentation index, see [llms.txt](https://archer-bot.gitbook.io/archer.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archer-bot.gitbook.io/archer.bot/getting-started/manage-your-wallet.md). # Manage Your Wallet Archer uses [Privy](https://docs.privy.io/) for wallet management, providing every user with secure embedded wallets while supporting external wallet connections for portfolio visibility and fund consolidation. ## Wallet Types ### Embedded Wallets (Primary) When you create an Archer account, Privy automatically provisions two embedded wallets: * **EVM wallet**: used for transactions on Ethereum, Base, Polygon, Arbitrum, Optimism, BSC, and Avalanche * **Solana wallet**: used for transactions on Solana These wallets are your **primary wallets**. Swaps, bridges, and all complex transactions execute from these wallets. They are non-custodial — Archer **never** holds your private keys. Signing happens either in your browser or inside Privy's Trusted Execution Environment when you opt in to server-resident signing — see [Security](/archer.bot/readme/security.md) for the full architecture. You can view your embedded wallet addresses on the **Settings** page under "Security & Authentication," where they are labeled **Primary**. ### External Wallets (Connected) You can link external wallets (MetaMask, Phantom, Coinbase Wallet, etc.) to your Archer account. External wallets serve three purposes: 1. **Authentication** — sign in to Archer using an external wallet instead of email or social login 2. **Portfolio visibility** — balances from connected wallets are included when you ask about your holdings 3. **Fund consolidation** — send tokens from a connected wallet to your Archer Wallet directly through the platform External wallets are labeled **Connected** on the Settings page and in the wallet dropdown. ## How Balances Work Archer tracks balances **per wallet**. When you ask "what are my balances?" or an agent calls `get_user_balances`, each balance row identifies which wallet holds it: ``` USDC on Polygon: 2.00 ($2.00) [primary] USDC on Polygon: 3.00 ($3.00) [connected: 0x976b...46ab] ETH on Base: 0.049 ($115.06) [primary] ``` This per-wallet attribution is critical for transaction accuracy. The system never combines balances from different wallets when checking whether a transaction is feasible. The **Portfolio page** shows aggregated totals across all wallets for a unified portfolio view. The per-wallet breakdown is used by the agent pipeline and MCP tools. Connected wallets that have been toggled off (see [Toggling Wallets On and Off](#toggling-wallets-on-and-off)) are excluded from both the per-wallet rows and the aggregated portfolio total. ## Transaction Routing Swaps, bridges, and complex transactions always execute from your **primary (embedded) wallet**: | Operation | Wallet Used | | -------------------------------------------- | ------------------------------------------------- | | EVM swap (e.g., "Swap ETH for USDC on Base") | Primary EVM wallet | | Solana swap (e.g., "Swap SOL for USDC") | Primary Solana wallet | | Cross-chain bridge | Primary wallet on the source chain | | Token send | Primary wallet (default) | | Consolidation send | Connected wallet (user approves via wallet popup) | ### When Primary Has Insufficient Balance If your primary wallet doesn't have enough for a transaction but a connected wallet does, Archer offers a two-step consolidation: 1. **Move funds** — send tokens from your connected wallet to your Archer Wallet (you approve via your external wallet's popup) 2. **Execute** — once funds arrive, proceed with the original swap or bridge from your Archer Wallet Archer never silently pulls funds from multiple wallets or aggregates balances for a single transaction. Each transaction executes from exactly one wallet. A connected wallet that has been toggled off is invisible to this flow — the agent won't see its balances, won't propose consolidation from it, and won't route any leg of a transaction through it. See [Toggling Wallets On and Off](#toggling-wallets-on-and-off). ### For MCP / Agent Integrations The MCP server returns the same per-wallet balance data. When building on Archer's MCP tools: * `get_user_balances` returns per-wallet rows with `walletType: "primary"` or `"connected"` * `check_feasibility` checks the primary wallet's balance and returns a `consolidationOption` if a connected wallet could help * Consolidation sends (connected to primary) are **only available in the web app** — MCP clients are headless and cannot render external wallet approval popups When balance is insufficient in an MCP context, the structured feasibility response gives your agent enough context to explain the situation and suggest the user consolidate via the web app. ## Linking and Unlinking Wallets ### Linking On the **Settings** page, click **Link Wallet** to connect an external wallet. Privy will prompt your browser wallet extension for a signature to verify ownership. Once linked, the wallet's balances appear in your portfolio and are available for consolidation. ### Unlinking Connected external wallets can be unlinked from the Settings page using the **Unlink** button. Unlinking removes the wallet from your Archer profile and stops its balances from appearing. It does not affect the assets in that wallet. Embedded wallets cannot be unlinked — they are permanently tied to your Archer account. ## Toggling Wallets On and Off Every connected wallet on the **Settings** page has an **Active** switch next to it. Flipping a wallet off keeps it linked to your account but tells Archer to **completely ignore it** until you flip it back on. Specifically, a toggled-off wallet is: * **Excluded from balance queries** — `get_user_balances`, the portfolio total, the chain breakdown, and the per-token rows all stop counting that wallet immediately. * **Excluded from agent context** — the LLM cannot see the wallet exists, won't suggest swapping or bridging from it, and won't offer it as a consolidation source when the primary wallet is short on funds. * **Excluded from transaction routing** — the wallet cannot be picked as the source of any send, swap, or bridge while it's off. This is useful when: * A connected wallet holds assets you don't want trading against (e.g., a cold-storage wallet linked only for portfolio visibility). * You want to temporarily focus a session on a single wallet (e.g., "only trade from my Phantom wallet today") without unlinking the others. * Dust or spam tokens in a particular wallet are polluting your portfolio view. ### Rules * **Embedded (primary) wallets cannot be toggled off.** They are always active — Archer needs at least one wallet that can sign transactions, and embedded wallets are the only ones eligible for server-side signing. The toggle switch is hidden on primary rows and the row is labeled **Always active**. (Toggling off the primary wallet returns an `EMBEDDED_NOT_TOGGLEABLE` error; external-only mode is not yet supported.) * **The toggle applies to the wallet, not the chain.** If you have one EVM address that holds tokens on Ethereum, Base, and Polygon, toggling it off hides all three chains at once. * **Changes take effect on the next request.** Archer flushes the cached balance snapshot the moment you toggle, so the next message you send already sees the new state — no manual refresh needed. ### For MCP / Agent Integrations The same toggle is exposed as the `toggle_wallet_active` MCP tool: ```json { "name": "toggle_wallet_active", "arguments": { "walletAddress": "0x976b...46ab", "isActive": false } } ``` EVM addresses are matched case-insensitively; Solana addresses match exactly. The tool returns `{ code: 'OK' }` on success, `{ code: 'NOT_FOUND' }` if the address isn't linked to the calling user, or `{ code: 'EMBEDDED_NOT_TOGGLEABLE' }` if you attempt to deactivate a primary wallet. `list_user_wallets` returns each wallet's current `isActive` state so a downstream agent can read the toggle status before deciding what to do. ## Server-Side Signing (Optional) For automated or hands-free execution, you can enable **server-side signing** from your Settings page. This allows Archer to sign transactions on your behalf using Privy's TEE infrastructure — your private key remains in a secure enclave and is never exposed to Archer's servers. Server-side signing only works with embedded wallets. External wallets will always require manual approval in your browser extension. ## Security Model * **Non-custodial**: Archer never holds or has access to your private keys * **In-memory tokens**: Authentication tokens are stored in memory only, never in local storage * **Embedded wallet isolation**: Your embedded wallets are provisioned and managed by Privy's infrastructure, which is entirely separate from Archer's backend * **Per-wallet transaction scoping**: Each transaction executes from exactly one wallet — no silent cross-wallet aggregation * **Connected wallet approval**: Sends from connected wallets always require explicit approval in your external wallet's native popup * **HttpOnly cookies**: Session persistence uses secure HttpOnly cookies that JavaScript cannot access --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://archer-bot.gitbook.io/archer.bot/getting-started/manage-your-wallet.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.