> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# X Layer tooling

> Connect MetaMask, ethers.js, viem, web3.py, Foundry, and Hardhat to an X Layer Mainnet or Testnet node on Chainstack. Chain configuration, the OKB gas token, contract verification on Sourcify, and the X Layer behaviors that affect tooling.

X Layer is OKX's Ethereum layer 2, built on the [OP Stack](https://docs.optimism.io/) with OKB as the gas token. It is EVM-equivalent, so the standard Ethereum libraries and frameworks work against an X Layer node without modification. Chainstack serves X Layer Mainnet and X Layer Testnet on Global Nodes with archive data and both the `debug_*` and `trace_*` namespaces. See [Debug and trace APIs](https://docs.chainstack.com/docs/debug-and-trace-apis.md#x-layer).

## Chain configuration

| Property | Mainnet | Testnet |
| - | - | - |
| Chain ID | `196` | `1952` |
| Native gas currency | OKB | OKB |
| Decimals | `18` | `18` |
| Block time | 1 second | 1 second |
| RPC URL | your Chainstack [X Layer endpoint](https://docs.chainstack.com/docs/manage-your-node.md#view-node-access-and-credentials) | your Chainstack [X Layer endpoint](https://docs.chainstack.com/docs/manage-your-node.md#view-node-access-and-credentials) |
| Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` | `0xcA11bde05977b3631167028862bE2a173976CA11` |
| Block explorer | [web3.okx.com/explorer/x-layer](https://web3.okx.com/explorer/x-layer) | [web3.okx.com/explorer/x-layer-testnet](https://web3.okx.com/explorer/x-layer-testnet) |
| Faucet | — | [web3.okx.com/xlayer/faucet](https://web3.okx.com/xlayer/faucet) |

## MetaMask

Add X Layer as a custom network. On Chainstack, get your [X Layer endpoint](https://docs.chainstack.com/docs/manage-your-node.md#view-node-access-and-credentials), then in MetaMask select **Add a custom network** and fill in:

* Network name — X Layer Mainnet
* Default RPC URL — your Chainstack X Layer Mainnet endpoint
* Chain ID — `196`
* Currency symbol — OKB
* Block explorer URL — `https://web3.okx.com/explorer/x-layer`

For X Layer Testnet, use your Chainstack X Layer Testnet endpoint, chain ID `1952`, and the block explorer URL `https://web3.okx.com/explorer/x-layer-testnet`.

## ethers.js

Install [ethers.js](https://docs.ethers.org/):

```shell Shell theme={"system"}
npm install ethers
```

```javascript index.js theme={"system"}
const { JsonRpcProvider, formatEther } = require("ethers");

const provider = new JsonRpcProvider("CHAINSTACK_NODE_URL");

async function main() {
  const network = await provider.getNetwork();
  console.log("Chain ID:", network.chainId.toString());

  const block = await provider.getBlockNumber();
  console.log("Block:", block);

  const balance = await provider.getBalance("0xe538905cf8410324e03A5A23C1c177a474D59b2b");
  console.log("Balance:", formatEther(balance), "OKB");
}

main();
```

The address in the example is the wrapped OKB (WOKB) contract on X Layer Mainnet, which holds the OKB deposited into it.

To receive new blocks as X Layer produces them, connect to the WSS endpoint and subscribe:

```javascript index.js theme={"system"}
const { WebSocketProvider } = require("ethers");

const provider = new WebSocketProvider("CHAINSTACK_WSS_URL");

provider.on("block", (blockNumber) => {
  console.log("New block:", blockNumber);
});
```

## viem

viem ships `xLayer` (chain `196`) and `xLayerTestnet` (chain `1952`) chain definitions in `viem/chains`. Their default RPC URLs are OKX's public endpoints, so pass your Chainstack endpoint to `http()`. Both definitions include the Multicall3 address, so `client.multicall` batches contract reads into a single `eth_call`.

```shell Shell theme={"system"}
npm install viem
```

```javascript index.mjs theme={"system"}
import { createPublicClient, http, formatEther, erc20Abi } from "viem";
import { xLayer } from "viem/chains";

const client = createPublicClient({
  chain: xLayer,
  transport: http("CHAINSTACK_NODE_URL"),
});

console.log("Chain ID:", await client.getChainId());
console.log("Block:", await client.getBlockNumber());

const wokb = "0xe538905cf8410324e03A5A23C1c177a474D59b2b";

const balance = await client.getBalance({ address: wokb });
console.log("Balance:", formatEther(balance), "OKB");

const [symbol, totalSupply] = await client.multicall({
  contracts: [
    { address: wokb, abi: erc20Abi, functionName: "symbol" },
    { address: wokb, abi: erc20Abi, functionName: "totalSupply" },
  ],
  allowFailure: false,
});
console.log(symbol, "supply:", formatEther(totalSupply));
```

For X Layer Testnet, import `xLayerTestnet` instead and pass your Chainstack X Layer Testnet endpoint.

## web3.py

Install [web3.py](https://web3py.readthedocs.io/):

```shell Shell theme={"system"}
pip install web3
```

```python main.py theme={"system"}
from web3 import Web3

web3 = Web3(Web3.HTTPProvider("CHAINSTACK_NODE_URL"))

print("Connected:", web3.is_connected())
print("Chain ID:", web3.eth.chain_id)
print("Block:", web3.eth.block_number)

address = Web3.to_checksum_address("0xe538905cf8410324e03a5a23c1c177a474d59b2b")
balance = web3.eth.get_balance(address)
print("Balance:", web3.from_wei(balance, "ether"), "OKB")
```

`from_wei(balance, "ether")` converts from the smallest unit with 18 decimals, which is the same conversion for OKB as for ETH.

## Foundry

Install [Foundry](https://getfoundry.sh/) and pass your Chainstack endpoint with `--rpc-url`.

Read chain data with `cast`:

```shell Shell theme={"system"}
cast chain-id --rpc-url CHAINSTACK_NODE_URL
cast block-number --rpc-url CHAINSTACK_NODE_URL
cast balance 0xe538905cf8410324e03A5A23C1c177a474D59b2b --ether --rpc-url CHAINSTACK_NODE_URL
```

Deploy a contract with `forge create`. Without `--broadcast`, `forge create` only simulates the deployment.

```shell Shell theme={"system"}
forge create src/Counter.sol:Counter \
  --rpc-url CHAINSTACK_NODE_URL \
  --private-key YOUR_PRIVATE_KEY \
  --broadcast
```

Verify the deployed contract on [Sourcify](https://sourcify.dev/), which supports both X Layer networks and does not need an API key. For X Layer Testnet, pass `--chain 1952`.

```shell Shell theme={"system"}
forge verify-contract DEPLOYED_CONTRACT_ADDRESS src/Counter.sol:Counter \
  --chain 196 \
  --verifier sourcify \
  --watch
```

X Layer's own explorers take verifications through OKLink, which needs an OKLink API key. See X Layer's [contract verification guide](https://web3.okx.com/onchainos/dev-docs/xlayer/developer/verify-a-smart-contract/verifying-contract).

## Hardhat

In a [Hardhat 3](https://hardhat.org/) project that uses `@nomicfoundation/hardhat-toolbox-viem`, add the X Layer networks to `hardhat.config.ts`:

```typescript hardhat.config.ts theme={"system"}
import { configVariable, defineConfig } from "hardhat/config";
import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";

export default defineConfig({
  plugins: [hardhatToolboxViem],
  solidity: "0.8.28",
  networks: {
    xlayer: {
      type: "http",
      url: configVariable("XLAYER_RPC_URL"),
      accounts: [configVariable("XLAYER_PRIVATE_KEY")],
    },
    xlayerTestnet: {
      type: "http",
      url: configVariable("XLAYER_TESTNET_RPC_URL"),
      accounts: [configVariable("XLAYER_PRIVATE_KEY")],
    },
  },
});
```

`configVariable` reads the endpoints and the key from environment variables or the Hardhat keystore, which keeps them out of the config file.

Deploy with an Ignition module, for example `ignition/modules/Counter.ts`:

```typescript ignition/modules/Counter.ts theme={"system"}
import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

export default buildModule("CounterModule", (m) => {
  const counter = m.contract("Counter");
  return { counter };
});
```

Then verify on Sourcify with the `verify sourcify` task. Hardhat has no built-in Etherscan or Blockscout explorer for X Layer, so the plain `hardhat verify` task reports the chain as not supported for those two providers.

```shell Shell theme={"system"}
npx hardhat ignition deploy ignition/modules/Counter.ts --network xlayer
npx hardhat verify sourcify --network xlayer DEPLOYED_CONTRACT_ADDRESS
```

## X Layer behaviors that affect tooling

### Transactions pay no L1 data fee

X Layer sets the L1 fee scalars in the `GasPriceOracle` predeploy at `0x420000000000000000000000000000000000000F` to zero, so the OP Stack L1 data fee is zero. Transaction receipts still carry the `l1Fee`, `l1GasUsed`, `l1GasPrice`, and `l1BlobBaseFee` fields, with `l1Fee` at `0x0`, and the total cost of a transaction is `gasUsed × effectiveGasPrice`.

### Pending transactions are never delivered

X Layer is an OP Stack chain, so pending transactions stay with the sequencer. `eth_subscribe("newPendingTransactions")` and `eth_newPendingTransactionFilter` return an ID but deliver nothing, and `txpool_status` always reads empty. To follow transactions before the sequencer seals their block on X Layer Mainnet, use [Flashblocks on X Layer Mainnet](#flashblocks-on-x-layer-mainnet). See [What gives you mempool access](https://docs.chainstack.com/docs/mempool-configuration.md#what-gives-you-mempool-access).

### Flashblocks on X Layer Mainnet

Chainstack X Layer Mainnet endpoints serve Flashblocks, the sequencer's preconfirmations of the block in progress. X Layer Testnet endpoints do not.

* `eth_getBlockByNumber("pending")` on Mainnet returns the next block with the transactions preconfirmed so far, and the block gains transactions until the sequencer seals it. On Testnet, the `pending` tag returns the latest block.
* `eth_flashblocksEnabled` returns `true` on Mainnet and `false` on Testnet.
* `eth_subscribe("flashblocks", filter)` over the WebSocket endpoint streams preconfirmed block headers and transactions on Mainnet. Each event has a `type` of `header` or `transaction`.

The `flashblocks` subscription filter takes these fields:

* `headerInfo` — `true` to receive `header` events for the block in progress, several per block as preconfirmations arrive.
* `subTxFilter.subscribeAddresses` — receive only transactions whose sender, recipient, or log-emitting contract is one of these addresses.
* `subTxFilter.txInfo` — `true` to include the full transaction in each `transaction` event.
* `subTxFilter.txReceipt` — `true` to include the receipt in each `transaction` event.

This subscription streams every preconfirmed transaction that calls the L1 attributes predeploy, with its receipt, one transaction per block:

```json Request theme={"system"}
{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["flashblocks",{"subTxFilter":{"subscribeAddresses":["0x4200000000000000000000000000000000000015"],"txInfo":true,"txReceipt":true}}]}
```

### Block-count limits and the proof window

X Layer produces a block every second, so a 10,000-block `eth_getLogs` request covers under 3 hours of chain time. `eth_getProof` serves the latest 256 blocks, about 4 minutes of chain time. See [EVM range limits](https://docs.chainstack.com/docs/limits.md#evm-range-limits) and [EVM `eth_getProof` history limits](https://docs.chainstack.com/docs/limits#evm-eth_getproof-history-limits).
