@ironwallet/mcp-server 1.0.0-preprod.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 INWAY AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @ironwallet/mcp-server
+
+Local [MCP](https://modelcontextprotocol.io) server for **Ironwallet** (`ironwallet-mcp` bin).
+
+Give an agent a **self-custody hot wallet** on this machine, seed-compatible with the [Ironwallet](https://ironwallet.io) app. Signing never leaves the machine. Recovery phrases stay encrypted on disk and **never pass through the agent**.
+
+There is no per-transaction confirmation UI.
+
+> **Hot-wallet only.** Use a dedicated wallet with limited balance. See [Security](#security).
+
+Product page: [ironwallet.io/ai](https://ironwallet.io/ai)
+
+**Requirements:** Node.js 20+ (`npx`).
+
+---
+
+## Install
+
+```bash
+npx -y @ironwallet/mcp-server
+```
+
+Or add to MCP config (Cursor: `.cursor/mcp.json` or global):
+
+```json
+{
+  "mcpServers": {
+    "ironwallet": {
+      "command": "npx",
+      "args": ["-y", "@ironwallet/mcp-server"]
+    }
+  }
+}
+```
+
+`npx` pulls the latest published build. First launch can take ~30s while dependencies install. If the MCP client times out, run the same command once in a terminal to warm the cache, then reconnect.
+
+The plugin install on [ironwallet.io/ai](https://ironwallet.io/ai) wires this up automatically.
+
+---
+
+## How it works
+
+```
+MCP client  →  ironwallet-mcp (stdio)
+                    ├── encrypted keystore on disk
+                    ├── signs on this machine
+                    └── HTTPS to Ironwallet backends
+```
+
+The mnemonic never appears in tool inputs/outputs, logs meant for the agent, or requests to backends / the LLM / the MCP client’s cloud.
+
+---
+
+## Features
+
+| Area | Capability |
+|------|------------|
+| **Networks** | Ethereum, BSC, Polygon, Base, Arbitrum, Optimism, Avalanche, Tron, Bitcoin, Litecoin, Dogecoin, Solana, XRP, TON |
+| **Wallets** | Create, import, list, and back up (local browser for secrets) |
+| **Balances** | Native coins and tokens |
+| **Transfers** | Fee estimate and send through Ironwallet’s transfer relay |
+| **Swaps** | Quotes and execution through Ironwallet **Swap Proxy** |
+| **Policy** | Optional per-wallet limits (`readOnly`, `maxPerTx`, transfer recipient allow-list). Applies to `send_transfer` and `execute_swap`. |
+
+---
+
+## Tools
+
+| Tool | Purpose | Moves funds? |
+|------|---------|:------------:|
+| `list_wallets` | Names and addresses | no |
+| `create_wallets` | New wallets; returns a browser `backup_url` | no |
+| `open_wallet_manager` | Local browser UI to import / create / back up | no |
+| `get_balance` | Native or token balance | no |
+| `estimate_transfer` | Fee estimate, no broadcast | no |
+| `send_transfer` | Sign locally and send | **yes** |
+| `get_operation_status` | Poll a transfer | no |
+| `list_swap_networks` | Networks available for swap | no |
+| `list_swap_assets` | Sell / buy catalog | no |
+| `estimate_swap` | Quote (may expire) | no |
+| `execute_swap` | Fresh quote → sign → swap | **yes** |
+| `get_swap_status` | Poll a swap | no |
+
+No tool accepts or returns a seed. Import and backup only in the local browser (`open_wallet_manager` / `backup_url`).
+
+### Wallets
+
+- **Create:** `create_wallets` — the agent gets names and addresses; open `backup_url` in a browser to view and back up recovery phrases.
+- **Import / back up:** `open_wallet_manager` — loopback-only page; the phrase is typed or shown only in the browser.
+- **List:** `list_wallets`
+
+The browser page binds to `127.0.0.1` under an unguessable path and shuts down after 15 minutes of inactivity.
+
+### Transfers
+
+1. `list_wallets` / `get_balance`
+2. `estimate_transfer` (optional)
+3. `send_transfer`
+4. `get_operation_status` when you need to wait on the operation
+
+`send_transfer` may reduce the amount slightly so the fee still fits the balance; the response reports when that happened.
+
+### Swaps
+
+Swaps use **Swap Proxy**, not the transfer relay.
+
+1. `list_swap_networks`
+2. `list_swap_assets` (`direction=from`, then `direction=to` with the chosen sell asset)
+3. Copy **network, symbol, address, decimals** from the catalog into `estimate_swap` / `execute_swap` (especially for tokens)
+4. `estimate_swap` for a preview, or go straight to `execute_swap`
+5. Poll with `get_swap_status` using `operationId`
+
+**Useful options**
+
+- `maxMode: true` — sell as much of the balance as the service allows (fees are accounted for server-side). `amount` can be omitted when `maxMode` is set.
+- Omit `address` only for native coins. For tokens, always pass `address` (and ideally `decimals`) from `list_swap_assets`.
+
+**Operational notes**
+
+- Quotes expire. Prefer `execute_swap` (fresh quote). If execute times out, **poll status** before retrying — do not blindly re-run execute.
+- Wallet policy: `readOnly` blocks sends and swaps. `maxPerTx` applies to the transfer amount or the corrected swap sell amount. A transfer recipient allow-list also blocks swaps (the swap router is not a whitelisted destination).
+
+---
+
+## Configuration
+
+Nothing to paste into MCP config for normal use. On first launch the server writes a relay API key, keystore wrapping secret, and device id under `~/.ironwallet-mcp/` (`keystore-passphrase`, `relay-api-key`, `device-id`, mode `0600`). Set the env vars only to override.
+
+The user-facing backup is the **recovery phrase** in the wallet manager, not those files.
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `IW_PASSPHRASE` | generated locally | Override keystore wrapping secret |
+| `IW_RELAY_API_KEY` | generated UUID | Override `x-api-key` |
+| `IW_DEVICE_ID` | generated UUID | Override `X-Device-Id` (stable per keystore directory) |
+| `IW_KEYSTORE_DIR` | `~/.ironwallet-mcp` | Keystore directory |
+| `IW_HTTP_TIMEOUT_MS` | `15000` | General HTTP timeout (1s–120s) |
+| `IW_HTTP_FORWARD_TIMEOUT_MS` | `60000` | Longer timeout for broadcast-style calls. A client timeout does not always mean the operation failed — check status |
+| `IW_HTTP_RETRIES` | `2` | Retries for safe/idempotent calls; broadcasts are not auto-retried |
+| `IW_LOG_ENABLED` | `1` | JSONL diagnostics to a log file (`0` to disable) |
+| `IW_LOG_FILE` | `{keystoreDir}/logs/iw-mcp-YYYY-MM-DD.jsonl` | Log path |
+| `IW_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |
+| `IW_LOG_STDERR` | `0` | Mirror logs to stderr (stdout is reserved for MCP) |
+
+---
+
+## Security
+
+- Seeds are encrypted at rest. They never appear in tool results, agent chat, or backend requests.
+- The agent **can move funds without asking again**. Optional wallet policy (`readOnly`, `maxPerTx`, transfer recipient allow-list) is off by default and applies to both `send_transfer` and `execute_swap`.
+- Anyone with the keystore **and** the wrapping secret controls the funds. A leaked seed cannot be revoked.
+- Timeout is not always failure: poll status before retrying a send or swap.
+- Desktop / stdio only. A phone or remote agent would need a design where signing stays on a trusted device.
+- **Do not** put a main wallet here. Use a small hot wallet.
+
+Details and private disclosure: [SECURITY.md](../../SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/assets/wordmark.svg

@@ -0,0 +1,20 @@
+<svg width="111" height="27" viewBox="0 0 111 27" fill="none" xmlns="http://www.w3.org/2000/svg">
+<defs>
+<linearGradient id="iwblue" x1="0" y1="0" x2="111" y2="27" gradientUnits="userSpaceOnUse">
+<stop stop-color="#2C6FE0"/>
+<stop offset="1" stop-color="#12B4EA"/>
+</linearGradient>
+</defs>
+<path d="M46.3652 14.0577V0.594684H50.6898V14.0577H46.3652Z" fill="url(#iwblue)"/>
+<path d="M70.4671 4.72361C70.4671 5.54548 70.2453 6.28908 69.8017 6.95441C69.3582 7.61973 68.7124 8.10894 67.8645 8.42203L70.8584 14.0577H66.0055L63.6181 9.14606H62.0135V14.0577H57.6889V0.594684H65.9272C66.8926 0.594684 67.7144 0.783845 68.3928 1.16217C69.0842 1.52744 69.5995 2.0297 69.9387 2.66893C70.2909 3.29512 70.4671 3.98001 70.4671 4.72361ZM66.0642 4.89973C66.0642 4.5475 65.9468 4.25397 65.7119 4.01915C65.4771 3.78433 65.1901 3.66692 64.8509 3.66692H62.0135V6.1521H64.8509C65.1901 6.1521 65.4771 6.03469 65.7119 5.79987C65.9468 5.55201 66.0642 5.25196 66.0642 4.89973Z" fill="url(#iwblue)"/>
+<path d="M83.2006 0.359863C85.5227 0.359863 87.3164 0.953438 88.5819 2.14059C89.8473 3.32773 90.48 5.05627 90.48 7.32621C90.48 9.59614 89.8473 11.3247 88.5819 12.5118C87.3164 13.699 85.5227 14.2925 83.2006 14.2925C80.8785 14.2925 79.0847 13.7055 77.8193 12.5314C76.5669 11.3442 75.9407 9.60918 75.9407 7.32621C75.9407 5.04323 76.5669 3.31469 77.8193 2.14059C79.0847 0.953438 80.8785 0.359863 83.2006 0.359863ZM83.2006 3.58865C82.2743 3.58865 81.5699 3.86913 81.0872 4.43009C80.6045 4.99105 80.3632 5.74769 80.3632 6.70002V7.95239C80.3632 8.90472 80.6045 9.66137 81.0872 10.2223C81.5699 10.7833 82.2743 11.0638 83.2006 11.0638C84.1268 11.0638 84.8313 10.7833 85.3139 10.2223C85.8097 9.66137 86.0575 8.90472 86.0575 7.95239V6.70002C86.0575 5.74769 85.8097 4.99105 85.3139 4.43009C84.8313 3.86913 84.1268 3.58865 83.2006 3.58865Z" fill="url(#iwblue)"/>
+<path d="M106.35 14.0577L100.695 7.52189V14.0577H96.7225V0.594684H100.499L106.154 7.22836V0.594684H110.127V14.0577H106.35Z" fill="url(#iwblue)"/>
+<path d="M49.0385 26.2881L46.2676 18.0693H47.1599L49.7547 25.8067H49.3085L51.9855 18.0693H52.7838L55.4256 25.8067H55.0029L57.6211 18.0693H58.4548L55.6839 26.2881H54.7681L52.2438 18.9499H52.4786L49.9425 26.2881H49.0385Z" fill="url(#iwblue)"/>
+<path d="M61.5136 26.2881L65.2708 18.0693H66.1279L69.885 26.2881H68.9692L65.5173 18.5742H65.8696L62.4177 26.2881H61.5136ZM62.993 24.0925L63.2513 23.388H68.0299L68.2882 24.0925H62.993Z" fill="url(#iwblue)"/>
+<path d="M74.2777 26.2881V18.0693H75.1465V25.5366H79.749V26.2881H74.2777Z" fill="url(#iwblue)"/>
+<path d="M84.2247 26.2881V18.0693H85.0935V25.5366H89.696V26.2881H84.2247Z" fill="url(#iwblue)"/>
+<path d="M94.9466 21.7443H99.2907V22.484H94.9466V21.7443ZM95.0405 25.5366H99.9835V26.2881H94.1717V18.0693H99.8074V18.8208H95.0405V25.5366Z" fill="url(#iwblue)"/>
+<path d="M106.656 26.2881V18.8208H103.767V18.0693H110.413V18.8208H107.524V26.2881H106.656Z" fill="url(#iwblue)"/>
+<path d="M34.9699 0.321167C36.4223 0.835034 37.1485 1.52019 37.1485 2.37664C37.1485 2.65498 37.0184 3.17955 36.7583 3.95035L27.9868 22.9408C27.9435 23.0907 27.8676 23.2727 27.7592 23.4868C27.6508 23.7009 27.3582 23.99 26.8813 24.3539C26.426 24.6965 25.8733 24.8678 25.223 24.8678C24.5943 24.8678 24.0415 24.6965 23.5647 24.3539C23.1094 23.99 22.8059 23.6367 22.6542 23.2941L18.8498 12.2138C16.4437 19.2367 15.2189 22.8123 15.1755 22.9408C15.1322 23.0693 15.0346 23.2513 14.8829 23.4868C14.7312 23.7223 14.5577 23.9364 14.3627 24.1291C13.8641 24.6216 13.2679 24.8678 12.5743 24.8678C11.8806 24.8678 11.3062 24.7072 10.8509 24.3861C10.4174 24.0649 10.1247 23.7437 9.973 23.4226L9.74539 22.9408L3.66432 11.1387C3.42587 10.4321 3.30664 9.90756 3.30664 9.56499C3.30664 8.70854 4.03283 8.03409 5.48521 7.54163C6.11385 7.32752 6.67746 7.22047 7.17603 7.22047C7.69629 7.22047 8.08648 7.39176 8.34661 7.73433C8.62841 8.07691 9.23868 9.15618 9.23868 9.15618L12.1561 14.4989L16.021 5.9716C16.3244 5.07233 16.8772 4.45141 17.6793 4.10883C18.0261 3.95895 18.4705 3.88402 19.0124 3.88402C19.576 3.88402 20.0963 4.06601 20.5732 4.43C21.0501 4.77258 21.3536 5.11516 21.4836 5.45773L25.223 14.0766L31.2164 2.16211C31.2164 2.16211 31.5734 1.47207 31.7999 1.09357C31.9832 0.787288 32.0552 0.57374 32.3361 0.353283C32.6926 0.0735416 33.0081 0 33.4417 0C33.8752 0 34.3846 0.107056 34.9699 0.321167Z" fill="url(#iwblue)"/>
+<rect width="5.8342" height="5.82899" rx="2.91449" transform="matrix(0.952501 -0.304536 0.305143 0.952307 0 1.93018)" fill="url(#iwblue)"/>
+</svg>

package/dist/api/auth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Challenge-signature login, matching the mobile app:
+ *   1. POST {authUrl}/api/v1/login/start  { wallets: [{ network, publicKey }] }
+ *   2. Sign the returned challenge with the Ethereum key (EIP-191 personal_sign)
+ *   3. POST {authUrl}/api/v1/login/confirm { challenge, signature }
+ *      -> { accessToken, expiryIn }
+ *
+ * Tokens are cached per wallet (keyed by EVM address) until shortly before
+ * expiry, then a fresh challenge login runs (the app does not use refresh).
+ */
+export interface AuthOpts {
+    correlationId?: string;
+}
+/**
+ * Return a valid Bearer token for the wallet identified by its mnemonic.
+ * Uses the cache when the token is still fresh (10s safety margin).
+ */
+export declare function getAccessToken(mnemonic: string, opts?: AuthOpts): Promise<string>;
+/** Authorization + device headers for authenticated backend calls. */
+export declare function authHeaders(token: string): Record<string, string>;

package/dist/api/auth.js

@@ -0,0 +1,92 @@
+/**
+ * Challenge-signature login, matching the mobile app:
+ *   1. POST {authUrl}/api/v1/login/start  { wallets: [{ network, publicKey }] }
+ *   2. Sign the returned challenge with the Ethereum key (EIP-191 personal_sign)
+ *   3. POST {authUrl}/api/v1/login/confirm { challenge, signature }
+ *      -> { accessToken, expiryIn }
+ *
+ * Tokens are cached per wallet (keyed by EVM address) until shortly before
+ * expiry, then a fresh challenge login runs (the app does not use refresh).
+ */
+import { Wallet } from "ethers";
+import { getConfig, commonHeaders, AUTH_NETWORKS } from "../config.js";
+import { deriveAddresses, deriveEvm } from "../wallet/derive.js";
+import { httpJson } from "./http.js";
+import { logError, logInfo, newCorrelationId } from "../log.js";
+const tokenCache = new Map();
+/**
+ * Return a valid Bearer token for the wallet identified by its mnemonic.
+ * Uses the cache when the token is still fresh (10s safety margin).
+ */
+export async function getAccessToken(mnemonic, opts = {}) {
+    const correlationId = opts.correlationId ?? newCorrelationId("auth");
+    const cfg = getConfig();
+    const addresses = deriveAddresses(mnemonic);
+    const cacheKey = addresses.ethereum.toLowerCase();
+    const cached = tokenCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) {
+        logInfo("auth.token.cache_hit", {
+            correlationId,
+            ethereum: addresses.ethereum,
+            expiresInMs: cached.expiresAt - Date.now(),
+        });
+        return cached.token;
+    }
+    logInfo("auth.login.start", {
+        correlationId,
+        ethereum: addresses.ethereum,
+        authUrl: cfg.authUrl,
+        networks: AUTH_NETWORKS,
+    });
+    const started = Date.now();
+    try {
+        const wallets = AUTH_NETWORKS.map((network) => ({
+            network,
+            publicKey: addresses[network],
+        }));
+        const start = await httpJson(`${cfg.authUrl}/api/v1/login/start`, {
+            method: "POST",
+            headers: { ...commonHeaders(cfg), "Content-Type": "application/json" },
+            body: JSON.stringify({ wallets }),
+        }, { retry: true, correlationId, label: "auth.login.start" });
+        if (!start?.challenge)
+            throw new Error("login/start returned no challenge.");
+        logInfo("auth.login.challenge", {
+            correlationId,
+            challengeLen: start.challenge.length,
+        });
+        const evm = deriveEvm(mnemonic);
+        const signature = await new Wallet(evm.privateKey).signMessage(start.challenge);
+        const confirm = await httpJson(`${cfg.authUrl}/api/v1/login/confirm`, {
+            method: "POST",
+            headers: { ...commonHeaders(cfg), "Content-Type": "application/json" },
+            body: JSON.stringify({ challenge: start.challenge, signature }),
+        }, { retry: true, correlationId, label: "auth.login.confirm" });
+        if (!confirm?.accessToken)
+            throw new Error("login/confirm returned no token.");
+        const expiresAt = Date.now() + Math.max(0, confirm.expiryIn - 10) * 1000;
+        tokenCache.set(cacheKey, { token: confirm.accessToken, expiresAt });
+        logInfo("auth.login.ok", {
+            correlationId,
+            ethereum: addresses.ethereum,
+            elapsedMs: Date.now() - started,
+            expiryIn: confirm.expiryIn,
+            tokenLen: confirm.accessToken.length,
+        });
+        return confirm.accessToken;
+    }
+    catch (e) {
+        logError("auth.login.fail", e, {
+            correlationId,
+            ethereum: addresses.ethereum,
+            elapsedMs: Date.now() - started,
+        });
+        throw e;
+    }
+}
+/** Authorization + device headers for authenticated backend calls. */
+export function authHeaders(token) {
+    const cfg = getConfig();
+    return { ...commonHeaders(cfg), Authorization: `Bearer ${token}` };
+}
+//# sourceMappingURL=auth.js.map

package/dist/api/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"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"}

package/dist/api/balances.d.ts

@@ -0,0 +1,25 @@
+/**
+ * On-chain balances read directly from RPC.
+ *   - EVM: ethers JsonRpcProvider. Native via getBalance; ERC-20 via
+ *     balanceOf/decimals/symbol calls.
+ *   - Tron: TronGrid HTTP API. Native TRX via /wallet/getaccount; TRC-20 via
+ *     /wallet/triggerconstantcontract (balanceOf) plus on-chain decimals/symbol.
+ *   - Solana: native SOL via getBalance; SPL via getTokenAccountsByOwner + mint.
+ *   - TON: native via getAddressBalance; jettons via TonCenter v3 indexer,
+ *     with on-chain get_wallet_address + get_wallet_data as fallback.
+ */
+import { type NetworkId } from "../config.js";
+export interface BalanceResult {
+    network: NetworkId;
+    address: string;
+    /** Token contract address for non-native balances; null for the native coin. */
+    contractAddress: string | null;
+    symbol: string;
+    decimals: number;
+    /** Balance in the smallest unit (wei / sun / token base units) as a string. */
+    raw: string;
+    /** Human-readable balance formatted with `decimals`. */
+    formatted: string;
+}
+/** Read the on-chain balance for a wallet address on the given network. */
+export declare function getBalance(network: NetworkId, address: string, contractAddress?: string): Promise<BalanceResult>;