DODOEX · junjieit · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/README.md b/README.md
@@ -69,7 +69,7 @@ DODO_PROJECT_ID=your-id
 
 ## Configuration
 
-Supported environment variables are intentionally limited. Runtime config is read only from `PRIVATE_KEY`, `KEYSTORE_PATH`, `KEYSTORE_PASSWORD_FILE`, `KEYSTORE_PASSWORD_ENV`, `KEYSTORE_PASSWORD`, `WALLET_ADDRESS`, `CHAIN_ID`, `DODO_API_KEY`, `DODO_PROJECT_ID`, `DODO_API_URL`, `COINGECKO_API_KEY`, `COINGECKO_API_URL`, `DEXSCREENER_API_URL`, `DEBANK_API_KEY`, `DEBANK_API_URL`, `ZERION_API_KEY`, `ZERION_API_URL`, `GOLDRUSH_API_KEY`, and `GOLDRUSH_API_URL`. CLI flags still override where available.
+Supported environment variables are intentionally limited. Runtime config is read only from `PRIVATE_KEY`, `KEYSTORE_PATH`, `KEYSTORE_PASSWORD_FILE`, `KEYSTORE_PASSWORD_ENV`, `KEYSTORE_PASSWORD`, `WALLET_ADDRESS`, `CHAIN_ID`, `RPC_URL_<chainId>`, `DODO_API_KEY`, `DODO_PROJECT_ID`, `DODO_API_URL`, `COINGECKO_API_KEY`, `COINGECKO_API_URL`, `DEXSCREENER_API_URL`, `DEBANK_API_KEY`, `DEBANK_API_URL`, `ZERION_API_KEY`, `ZERION_API_URL`, `GOLDRUSH_API_KEY`, and `GOLDRUSH_API_URL`. CLI flags still override where available.
 
 | Variable               | CLI flag              | Default                        | Description                                    |
 |------------------------|-----------------------|--------------------------------|------------------------------------------------|
@@ -79,7 +79,8 @@ Supported environment variables are intentionally limited. Runtime config is rea
 | `KEYSTORE_PASSWORD_ENV` | `--password-env`     | —                              | Read keystore password from named env var      |
 | `KEYSTORE_PASSWORD`    | —                     | —                              | Default env var used for keystore password     |
 | `WALLET_ADDRESS`       | `--wallet-address`    | —                              | Wallet address for balance/simulate and dry-run sender fallback |
-| `--rpc-url`            | CLI only              | Chain's built-in public RPC    | Explicit JSON-RPC override                     |
+| `--rpc-url`            | CLI only              | Chain's built-in public RPC    | Explicit JSON-RPC override (all chains)        |
+| `RPC_URL_<chainId>`    | `config set rpc_url`  | Chain's built-in public RPC    | Persisted per-chain RPC override               |
 | `CHAIN_ID`             | `--chain-id`          | `1` (Ethereum mainnet)         | Active chain ID                                |
 | `DODO_API_KEY`         | —                     | Compiled-in default            | DODO routing API key                           |
 | `DODO_PROJECT_ID`      | —                     | Compiled-in default            | DODO project ID for token list lookup          |
@@ -144,7 +145,35 @@ Custom token behavior:
 | Plume              | 98866      |
 | Sepolia Testnet    | 11155111   |
 
-For unsupported chain IDs, pass `--rpc-url` manually.
+For unsupported chain IDs, pass `--rpc-url` manually, or persist a per-chain RPC
+with `chainpilot config set rpc_url` (see [Custom RPC endpoints](#custom-rpc-endpoints)).
+
+### Custom RPC endpoints
+
+Each chain uses a built-in public RPC by default. To point a chain at your own
+node, persist a per-chain override (stored as `RPC_URL_<chainId>` in the config
+file). Precedence is **`--rpc-url` flag > configured `RPC_URL_<chainId>` > chain
+default**; the `--rpc-url` flag still overrides everything for all chains.
+
+```bash
+# Set the RPC for one chain (bare `rpc_url` targets the active --chain-id)
+chainpilot --chain-id 56 config set rpc_url https://my-bsc-node
+chainpilot config set rpc_url.56 https://my-bsc-node        # equivalent
+
+# Set several chains at once with a JSON map (merges, keeping other chains)
+chainpilot config set rpc_url '{"1":"https://my-eth-node","56":"https://my-bsc-node"}'
+
+# Inspect / remove
+chainpilot config get rpc_url            # all configured chains
+chainpilot config get rpc_url.56         # one chain
+chainpilot config unset rpc_url.56       # one chain
+chainpilot config unset rpc_url          # all chains
+```
+
+Note: `set` without a `.<chainId>` suffix targets the active chain
+(`--chain-id`, default 1). Bare `get`/`unset rpc_url`, however, always operate on
+**all** configured chains regardless of `--chain-id` / `CHAIN_ID`; use the
+`rpc_url.<chainId>` form to target a single chain.
 
 ## Non-EVM Support (Solana / Bitcoin)
 

diff --git a/README_CN.md b/README_CN.md
@@ -63,7 +63,7 @@ DODO_PROJECT_ID=your-id
 
 ## 配置
 
-环境变量刻意收敛为少数几个。运行时只读取 `PRIVATE_KEY`、`KEYSTORE_PATH`、`KEYSTORE_PASSWORD_FILE`、`KEYSTORE_PASSWORD_ENV`、`KEYSTORE_PASSWORD`、`WALLET_ADDRESS`、`CHAIN_ID`、`DODO_API_KEY`、`DODO_PROJECT_ID`、`DODO_API_URL`、`COINGECKO_API_KEY`、`COINGECKO_API_URL`、`DEXSCREENER_API_URL`、`DEBANK_API_KEY`、`DEBANK_API_URL`、`ZERION_API_KEY`、`ZERION_API_URL`、`GOLDRUSH_API_KEY`、`GOLDRUSH_API_URL`；有对应 CLI 标志的情况下，CLI 仍然优先。
+环境变量刻意收敛为少数几个。运行时只读取 `PRIVATE_KEY`、`KEYSTORE_PATH`、`KEYSTORE_PASSWORD_FILE`、`KEYSTORE_PASSWORD_ENV`、`KEYSTORE_PASSWORD`、`WALLET_ADDRESS`、`CHAIN_ID`、`RPC_URL_<chainId>`、`DODO_API_KEY`、`DODO_PROJECT_ID`、`DODO_API_URL`、`COINGECKO_API_KEY`、`COINGECKO_API_URL`、`DEXSCREENER_API_URL`、`DEBANK_API_KEY`、`DEBANK_API_URL`、`ZERION_API_KEY`、`ZERION_API_URL`、`GOLDRUSH_API_KEY`、`GOLDRUSH_API_URL`；有对应 CLI 标志的情况下，CLI 仍然优先。
 
 | 变量名                 | CLI 标志              | 默认值                       | 说明                               |
 |------------------------|-----------------------|------------------------------|------------------------------------|
@@ -73,7 +73,8 @@ DODO_PROJECT_ID=your-id
 | `KEYSTORE_PASSWORD_ENV` | `--password-env`     | —                            | 从指定环境变量读取 keystore 密码   |
 | `KEYSTORE_PASSWORD`    | —                     | —                            | keystore 密码的默认环境变量        |
 | `WALLET_ADDRESS`       | `--wallet-address`    | —                            | 余额查询 / 模拟 / dry-run sender fallback 钱包地址 |
-| `--rpc-url`            | 仅 CLI                | 链内置公共 RPC               | 显式覆盖 JSON-RPC 端点             |
+| `--rpc-url`            | 仅 CLI                | 链内置公共 RPC               | 显式覆盖 JSON-RPC 端点（所有链）   |
+| `RPC_URL_<chainId>`    | `config set rpc_url`  | 链内置公共 RPC               | 持久化的按链 RPC 覆盖              |
 | `CHAIN_ID`             | `--chain-id`          | `1`（以太坊主网）            | 当前链 ID                          |
 | `DODO_API_KEY`         | —                     | 编译时内嵌默认值             | DODO 路由 API Key                  |
 | `DODO_PROJECT_ID`      | —                     | 编译时内嵌默认值             | DODO 项目 ID，用于代币列表查询     |
@@ -138,7 +139,34 @@ RUST_LOG=debug chainpilot ...
 | Plume               | 98866      |
 | Sepolia Testnet     | 11155111   |
 
-不在列表中的链，请手动传入 `--rpc-url`。
+不在列表中的链，请手动传入 `--rpc-url`，或用 `chainpilot config set rpc_url`
+持久化一个按链的 RPC（见下方[自定义 RPC 端点](#自定义-rpc-端点)）。
+
+### 自定义 RPC 端点
+
+每条链默认使用内置的公共 RPC。如需指向你自己的节点，可持久化一个按链的覆盖
+（以 `RPC_URL_<chainId>` 存储在配置文件中）。优先级为 **`--rpc-url` 标志 >
+已配置的 `RPC_URL_<chainId>` > 链默认值**；`--rpc-url` 标志仍会对所有链生效、
+优先级最高。
+
+```bash
+# 设置某条链的 RPC（不带后缀的 `rpc_url` 作用于当前 --chain-id）
+chainpilot --chain-id 56 config set rpc_url https://my-bsc-node
+chainpilot config set rpc_url.56 https://my-bsc-node        # 等价写法
+
+# 用 JSON map 一次配置多条链（合并写入，保留其他链）
+chainpilot config set rpc_url '{"1":"https://my-eth-node","56":"https://my-bsc-node"}'
+
+# 查看 / 删除
+chainpilot config get rpc_url            # 所有已配置的链
+chainpilot config get rpc_url.56         # 单条链
+chainpilot config unset rpc_url.56       # 单条链
+chainpilot config unset rpc_url          # 全部
+```
+
+注意：`set` 不带 `.<chainId>` 后缀时作用于当前链（`--chain-id`，默认 1）；但
+`get`/`unset rpc_url` 不带后缀时**始终**作用于**所有**已配置的链，与
+`--chain-id` / `CHAIN_ID` 无关；如需针对单条链,请使用 `rpc_url.<chainId>` 形式。
 
 ## 非 EVM 支持（Solana / 比特币）
 

diff --git a/skills/chainpilot/SKILL.md b/skills/chainpilot/SKILL.md
@@ -101,7 +101,8 @@ chainpilot [GLOBAL_FLAGS] <COMMAND> [SUBcommand_FLAGS]
 | `--password-file <path>` | `KEYSTORE_PASSWORD_FILE` | — | Read keystore password from file |
 | `--password-env <NAME>` | `KEYSTORE_PASSWORD_ENV` | — | Read keystore password from the named env var |
 | `--wallet-address <addr>` | `WALLET_ADDRESS` | — | Read-only wallet context and dry-run sender fallback |
-| `--rpc-url <url>` | — | Chain's public RPC | Explicit JSON-RPC override |
+| `--rpc-url <url>` | — | Chain's public RPC | Explicit JSON-RPC override (all chains) |
+| `config set rpc_url` | `RPC_URL_<chainId>` | Chain's public RPC | Persisted per-chain RPC override |
 | `--chain-id <id>` | `CHAIN_ID` | `1` | Global chain context |
 
 **Context propagation**: Once the user specifies a `--wallet-address` or `--chain-id`,
@@ -119,7 +120,7 @@ the user explicitly asks for a different one.
 
 Runtime env vars are intentionally limited to `PRIVATE_KEY`, `KEYSTORE_PATH`,
 `KEYSTORE_PASSWORD_FILE`, `KEYSTORE_PASSWORD_ENV`, `KEYSTORE_PASSWORD`,
-`WALLET_ADDRESS`, `CHAIN_ID`, `DODO_API_KEY`, `DODO_PROJECT_ID`,
+`WALLET_ADDRESS`, `CHAIN_ID`, `RPC_URL_<chainId>`, `DODO_API_KEY`, `DODO_PROJECT_ID`,
 `DODO_API_URL`, `COINGECKO_API_URL`, `COINGECKO_API_KEY`,
 `DEXSCREENER_API_URL`, `DEBANK_API_KEY`, `DEBANK_API_URL`,
 `ZERION_API_KEY`, `ZERION_API_URL`, `GOLDRUSH_API_KEY`,
@@ -1018,7 +1019,8 @@ confirm with the user before using any candidate address in a swap or approval.
 | Plume | 98866 |
 | Sepolia Testnet | 11155111 |
 
-For unsupported chain IDs, pass `--rpc-url` manually.
+For unsupported chain IDs, pass `--rpc-url` manually, or persist a per-chain RPC
+with `chainpilot config set rpc_url` (see the `config` subcommands below).
 
 **Non-EVM analytics**: `chain` subcommands (and `protocol info/tvl/revenue/chains`)
 additionally accept `solana` / `svm` and `bitcoin` / `bvm` — read-only via
@@ -1043,13 +1045,29 @@ Save an API key or configuration value. The value is written to the persistent c
 and immediately available to the current process. On Unix, the config file is
 written with owner-only permissions (`0600`).
 
+**Per-chain RPC endpoints** use the special `rpc_url` key, stored as
+`RPC_URL_<chainId>`. Precedence is `--rpc-url` flag > configured
+`RPC_URL_<chainId>` > chain default RPC.
+
+```bash
+# Active chain (--chain-id, default 1); or name the chain in the key
+chainpilot --chain-id 56 config set rpc_url https://my-bsc-node
+chainpilot config set rpc_url.56 https://my-bsc-node
+
+# Batch several chains with a JSON map (merges; unlisted chains untouched)
+chainpilot config set rpc_url '{"1":"https://my-eth-node","56":"https://my-bsc-node"}'
+```
+
 ### `config get`
 
 ```bash
 chainpilot config get <KEY>
 ```
 
 Show the current value of a configuration key. Sensitive values are partially masked.
+For RPC endpoints, `config get rpc_url` lists every configured chain, while
+`config get rpc_url.56` shows one chain. Bare `rpc_url` always covers all chains
+regardless of `--chain-id` / `CHAIN_ID`.
 
 ### `config list`
 
@@ -1065,7 +1083,10 @@ Show all configurable keys with their current values (sensitive values masked).
 chainpilot config unset <KEY>
 ```
 
-Remove a configuration key from the config file.
+Remove a configuration key from the config file. For RPC endpoints,
+`config unset rpc_url.56` removes one chain, while a bare `config unset rpc_url`
+always clears every configured chain — it ignores `--chain-id` / `CHAIN_ID`, so
+it never silently removes just one.
 
 ### Configurable Keys
 
@@ -1078,6 +1099,7 @@ Remove a configuration key from the config file.
 | `zerion_api_key` | `ZERION_API_KEY` | Yes | Zerion API key — second-tier wallet aggregator |
 | `goldrush_api_key` | `GOLDRUSH_API_KEY` | Yes | Goldrush / Covalent API key — third-tier wallet aggregator |
 | `dune_api_key` | `DUNE_API_KEY` | Yes | Dune Analytics API key — wallet labels fallback |
+| `rpc_url[.<chainId>]` | `RPC_URL_<chainId>` | No | Per-chain RPC endpoint; accepts a single URL or a `{chainId: url}` JSON map |
 
 Only these keys are supported by `chainpilot config` today. Other runtime
 settings, such as `COINGECKO_API_URL`, `DEXSCREENER_API_URL`,

diff --git a/src/chain/rpc.rs b/src/chain/rpc.rs
@@ -277,6 +277,7 @@ mod tests {
         AppConfig {
             rpc_url: "https://ethereum-rpc.publicnode.com".to_string(),
             rpc_url_overridden: false,
+            rpc_overrides: std::collections::HashMap::new(),
             chain_id: 1,
             chain_id_overridden: false,
             private_key: None,

diff --git a/src/cli/config.rs b/src/cli/config.rs
@@ -21,14 +21,18 @@ pub enum ConfigAction {
 
 #[derive(Args)]
 pub struct ConfigSetArgs {
-    /// Configuration key name
+    /// Configuration key: an API key name, or `rpc_url[.<chainId>]` for a
+    /// per-chain RPC endpoint (bare `rpc_url` targets the active `--chain-id`).
     pub key: String,
-    /// Value to set
+    /// Value to set. For `rpc_url`, a single URL, or a JSON map of
+    /// chainId -> URL to configure several chains at once
+    /// (e.g. '{"1":"https://eth","56":"https://bsc"}').
     pub value: String,
 }
 
 #[derive(Args)]
 pub struct ConfigKeyArg {
-    /// Configuration key name
+    /// Configuration key: an API key name, or `rpc_url[.<chainId>]`. Bare
+    /// `rpc_url` always targets all chains; use `rpc_url.<chainId>` for one.
     pub key: String,
 }