How to Add a Custom Network to OKX Wallet

Network Configuration Requirements

1. A valid Chain ID must be provided during manual network setup. The OKX Wallet strictly validates this value before allowing network registration.

2. The RPC URL must be HTTPS-enabled and publicly accessible. Invalid or unreachable endpoints will result in connection failure and wallet rejection.

3. Block explorer URL must point to a functional, chain-specific explorer interface. Missing or misconfigured explorers prevent transaction verification and asset tracking.

4. Currency symbol field accepts only uppercase alphanumeric strings up to six characters. Symbols exceeding length or containing special characters trigger input rejection.

5. Network name supports Unicode but must not contain control characters or null bytes. Names with invisible Unicode modifiers may cause inconsistent display across device types.

Step-by-Step Manual Addition Process

1. Launch OKX Wallet extension and navigate to Settings → Network → Add Network.

2. Select “Custom Network” and enter the required parameters: Network Name, New RPC URL, Chain ID, Currency Symbol, and Block Explorer URL.

3. Tap “Save” to initiate validation. Wallet performs real-time connectivity checks against the RPC endpoint.

4. If validation passes, the network appears in the active list and becomes selectable from the top navigation bar.

5. If validation fails, error messages specify exact failure points—such as timeout, invalid Chain ID, or CORS block—without generic fallbacks.

Chain ID Validation Logic

1. Chain ID is parsed as a base-10 integer. Hexadecimal or floating-point inputs are rejected immediately.

2. Values outside the 1–2147483647 range produce overflow errors. Negative numbers or zero are disallowed.

3. Duplicate Chain IDs across configured networks trigger conflict warnings. Wallet prohibits saving overlapping identifiers.

4. Predefined chains like Ethereum (1), BSC (56), and XLayer (196) enforce strict immutability. Custom entries cannot override these defaults.

5. Testnet Chain IDs follow distinct ranges: XLayer Testnet uses 195, while XLayer Testnet v2 uses 1952. Mismatched versions lead to silent transaction failures.

RPC Endpoint Behavior Rules

1. Wallet sends a lightweight eth_chainId request upon save. No balance or account queries occur during initial validation.

2. Timeouts default to 8 seconds. Networks failing to respond within this window are marked as “unreachable”.

3. CORS headers must include * or explicit OKX Wallet origin domains. Absence blocks cross-origin requests at browser level.

4. Responses must return JSON-RPC 2.0-compliant format with “id”, “jsonrpc”, and “result” fields. Malformed payloads cause immediate rejection.

5. Rate-limited endpoints returning HTTP 429 are cached for 120 seconds. Subsequent attempts within that window bypass network calls entirely.

Frequently Asked Questions

Q1. Can I add a network with Chain ID 0?Chain ID 0 is explicitly prohibited. The wallet rejects it with error code NW-ERR-003 during parameter parsing.

Q2. Does OKX Wallet support EIP-3085 wallet_addEthereumChain requests?No. OKX Wallet does not implement EIP-3085. It relies solely on its internal network configuration UI and does not accept dapp-initiated network addition prompts.

Q3. Why does my custom RPC show “Connected” but fail to load balances?This indicates successful eth_chainId response but subsequent eth_getBalance calls returning null or malformed data. Verify your node serves full state responses and supports the correct API version.

Q4. Are custom networks synced across devices using the same seed phrase?No. Network configurations are stored locally per installation and are not part of seed phrase recovery. Each device requires independent manual setup.