> For the complete documentation index, see [llms.txt](https://docs.bitbadges.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitbadges.io/for-developers/bitbadges-blockchain/evm-rpc-endpoints.md).

# EVM RPC Endpoints

BitBadges Chain provides Ethereum-compatible JSON-RPC endpoints for interacting with the blockchain using standard Ethereum tools and libraries.

> **Important:** EVM RPC endpoints are different from Cosmos RPC endpoints. Use the correct endpoint type for your tooling:
>
> * **EVM Tools** (MetaMask, Hardhat, ethers.js): Use `evm-rpc*.bitbadges.io` URLs
> * **Cosmos Tools** (cosmjs, LCD queries): Use `rpc*.bitbadges.io` or `lcd*.bitbadges.io` URLs

## Overview

The EVM RPC endpoints support all standard Ethereum JSON-RPC methods, allowing you to use tools like:

* MetaMask
* ethers.js
* web3.js
* Hardhat
* Foundry
* Any other Ethereum-compatible tooling

## Mainnet Endpoints

### EVM JSON-RPC

**Endpoint**: `https://evm-rpc.bitbadges.io`

This endpoint provides full Ethereum JSON-RPC compatibility for mainnet operations.

**Chain ID**: `50024`

**Example Usage**:

```typescript
import { ethers } from "ethers";

// Connect to BitBadges mainnet EVM RPC
const provider = new ethers.JsonRpcProvider("https://evm-rpc.bitbadges.io");

// Get the current block number
const blockNumber = await provider.getBlockNumber();
console.log("Current block:", blockNumber);

// Get balance of an address
const balance = await provider.getBalance("0x...");
console.log("Balance:", ethers.formatEther(balance), "BADGE");
```

```javascript
// Using web3.js
const Web3 = require('web3');
const web3 = new Web3('https://evm-rpc.bitbadges.io');

// Get the current block number
const blockNumber = await web3.eth.getBlockNumber();
console.log("Current block:", blockNumber);
```

### MetaMask Configuration

To add BitBadges mainnet to MetaMask:

1. Open MetaMask
2. Go to **Settings > Networks > Add Network**
3. Enter the following details:
   * **Network Name**: BitBadges Mainnet
   * **RPC URL**: `https://evm-rpc.bitbadges.io`
   * **Chain ID**: `50024`
   * **Currency Symbol**: `BADGE`
   * **Block Explorer URL**: `https://explorer.bitbadges.io` (optional)

## Testnet Endpoints

### EVM JSON-RPC

**Endpoint**: `https://evm-rpc-testnet.bitbadges.io`

This endpoint provides full Ethereum JSON-RPC compatibility for testnet operations.

**Chain ID**: `50025`

**Example Usage**:

```typescript
import { ethers } from "ethers";

// Connect to BitBadges testnet EVM RPC
const provider = new ethers.JsonRpcProvider("https://evm-rpc-testnet.bitbadges.io");

// Get the current block number
const blockNumber = await provider.getBlockNumber();
console.log("Current block:", blockNumber);
```

### MetaMask Configuration

To add BitBadges testnet to MetaMask:

1. Open MetaMask
2. Go to **Settings > Networks > Add Network**
3. Enter the following details:
   * **Network Name**: BitBadges Testnet
   * **RPC URL**: `https://evm-rpc-testnet.bitbadges.io`
   * **Chain ID**: `50025`
   * **Currency Symbol**: `BADGE`
   * **Block Explorer URL**: (Testnet block explorer URL, if available)

## Supported JSON-RPC Methods

The EVM RPC endpoints support all standard Ethereum JSON-RPC methods, including:

### Account Methods

* `eth_accounts` - Returns a list of addresses owned by client
* `eth_getBalance` - Returns the balance of the account of given address
* `eth_getTransactionCount` - Returns the number of transactions sent from an address

### Block Methods

* `eth_blockNumber` - Returns the number of most recent block
* `eth_getBlockByNumber` - Returns information about a block by block number
* `eth_getBlockByHash` - Returns information about a block by block hash

### Transaction Methods

* `eth_sendTransaction` - Creates new message call transaction or a contract creation
* `eth_sendRawTransaction` - Sends a signed transaction
* `eth_getTransactionByHash` - Returns the information about a transaction requested by transaction hash
* `eth_getTransactionReceipt` - Returns the receipt of a transaction by transaction hash

### Contract Methods

* `eth_call` - Executes a new message call immediately without creating a transaction on the block chain
* `eth_estimateGas` - Generates and returns an estimate of how much gas is necessary to allow the transaction to complete

### Event Methods

* `eth_getLogs` - Returns an array of all logs matching a given filter object
* `eth_newFilter` - Creates a filter object, based on filter options
* `eth_newBlockFilter` - Creates a filter in the node, to notify when a new block arrives
* `eth_newPendingTransactionFilter` - Creates a filter in the node, to notify when new pending transactions arrive

### State Methods

* `eth_getCode` - Returns code at a given address
* `eth_getStorageAt` - Returns the value from a storage position at a given address

### Network Methods

* `eth_chainId` - Returns the current chain ID
* `net_version` - Returns the current network ID
* `net_listening` - Returns true if client is actively listening for network connections

### Web3 Methods

* `web3_clientVersion` - Returns the current client version
* `web3_sha3` - Returns Keccak-256 hash of the given data

## Example: Deploying a Contract

```typescript
import { ethers } from "ethers";
import * as fs from "fs";

async function deploy() {
  // Connect to BitBadges mainnet EVM RPC
  const provider = new ethers.JsonRpcProvider("https://evm-rpc.bitbadges.io");
  
  // Get deployer wallet
  const privateKey = process.env.PRIVATE_KEY || "";
  if (!privateKey) {
    throw new Error("PRIVATE_KEY environment variable required");
  }
  
  const wallet = new ethers.Wallet(privateKey, provider);
  console.log("Deployer address:", wallet.address);
  
  // Check balance
  const balance = await provider.getBalance(wallet.address);
  console.log("Balance:", ethers.formatEther(balance), "BADGE");
  
  // Deploy contract
  const contractFactory = new ethers.ContractFactory(
    CONTRACT_ABI,
    CONTRACT_BYTECODE,
    wallet
  );
  
  const contract = await contractFactory.deploy(/* constructor args */);
  await contract.waitForDeployment();
  
  const address = await contract.getAddress();
  console.log("Contract deployed at:", address);
}
```

## Example: Interacting with Contracts

```typescript
import { ethers } from "ethers";

async function interactWithContract() {
  // Connect to BitBadges mainnet EVM RPC
  const provider = new ethers.JsonRpcProvider("https://evm-rpc.bitbadges.io");
  
  // Load contract
  const contractAddress = "0x..."; // Your contract address
  const contract = new ethers.Contract(
    contractAddress,
    CONTRACT_ABI,
    provider
  );
  
  // Read from contract
  const value = await contract.someViewFunction();
  console.log("Value:", value);
  
  // Write to contract (requires signer)
  const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
  const contractWithSigner = contract.connect(signer);
  
  const tx = await contractWithSigner.someWriteFunction(/* args */);
  await tx.wait();
  console.log("Transaction confirmed:", tx.hash);
}
```

## Hardhat Configuration

Add BitBadges networks to your `hardhat.config.js`:

```javascript
require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: "0.8.20",
  networks: {
    bitbadges: {
      url: "https://evm-rpc.bitbadges.io",
      chainId: 50024,
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
    bitbadgesTestnet: {
      url: "https://evm-rpc-testnet.bitbadges.io",
      chainId: 50025,
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
  },
};
```

## Foundry Configuration

Add BitBadges networks to your `foundry.toml`:

```toml
[rpc_endpoints]
bitbadges = "https://evm-rpc.bitbadges.io"
bitbadgesTestnet = "https://evm-rpc-testnet.bitbadges.io"

[profile.default]
rpc_endpoints = ["bitbadges", "bitbadgesTestnet"]
```

## Rate Limiting

The public EVM RPC endpoints may have rate limiting in place to ensure fair usage. For production applications, consider:

* Running your own node
* Using a dedicated RPC provider
* Implementing request caching and batching

## Running Your Own JSON-RPC Node

If you need higher rate limits or want full control, you can run your own node with JSON-RPC enabled.

### Critical Configuration

⚠️ **IMPORTANT**: When running your own node, you **must** configure the `evm-chain-id` in `app.toml`:

```toml
[evm]
# CRITICAL: Set this to match your network's EVM chain ID
# Mainnet: 50024
# Testnet: 50025
# The default (90123) is the local-dev chain ID and will cause MetaMask transaction failures on mainnet/testnet!
evm-chain-id = 50024
```

This setting is used by `net_version` for EIP-155 signature verification. If it doesn't match `eth_chainId`, wallets will fail with an error like: `incorrect chain-id; expected 90123, got 50024` (the "expected" value reflects whatever `evm-chain-id` is currently set to — `90123` is the local-dev default emitted by `bitbadgeschaind init`).

### Enable JSON-RPC

Add to your `app.toml`:

```toml
[json-rpc]
enable = true
address = "0.0.0.0:8545"  # Use 127.0.0.1 for local only
ws-address = "0.0.0.0:8546"
api = ["eth", "net", "web3"]
enable-indexer = true
```

### Full Configuration Reference

| Option                    | Default               | Description                   |
| ------------------------- | --------------------- | ----------------------------- |
| `enable`                  | `false`               | Enable JSON-RPC server        |
| `address`                 | `127.0.0.1:8545`      | HTTP listen address           |
| `ws-address`              | `127.0.0.1:8546`      | WebSocket address             |
| `api`                     | `eth,net,web3`        | Enabled namespaces            |
| `enable-indexer`          | `false`               | Custom tx indexer             |
| `evm-timeout`             | `5s`                  | eth\_call timeout             |
| `gas-cap`                 | `25000000`            | Gas limit for calls           |
| `txfee-cap`               | `1.0`                 | Max tx fee (BADGE)            |
| `filter-cap`              | `200`                 | Max active filters            |
| `block-range-cap`         | `10000`               | Max block range for logs      |
| `logs-cap`                | `10000`               | Max log results               |
| `batch-request-limit`     | `1000`                | Max batch size                |
| `batch-response-max-size` | `25000000`            | Max response bytes            |
| `http-timeout`            | `30s`                 | HTTP timeout                  |
| `http-idle-timeout`       | `2m0s`                | HTTP idle timeout             |
| `max-open-connections`    | `0`                   | Max connections (0=unlimited) |
| `allow-unprotected-txs`   | `false`               | Allow non-EIP155 txs          |
| `ws-origins`              | `127.0.0.1,localhost` | WebSocket allowed origins     |

See [Run a Mainnet Node](/for-developers/bitbadges-blockchain/run-a-mainnet-node.md#evm-json-rpc-configuration) for complete setup instructions.

## Related Documentation

* [EVM Integration Guide](https://github.com/trevormil/bitbadges-docs/blob/master/for-developers/evm/EVM_INTEGRATION.md) - Complete EVM integration overview
* [Setup and Configuration](https://github.com/trevormil/bitbadges-docs/blob/master/for-developers/evm/evm-precompiles/setup-and-configuration.md) - Local development setup
* [Developer Guide](https://github.com/trevormil/bitbadges-docs/blob/master/for-developers/evm/evm-precompiles/developer-guide.md) - EVM development best practices
* [Tokenization Precompile API](https://github.com/trevormil/bitbadges-docs/blob/master/for-developers/evm/evm-precompiles/tokenization-precompile/API.md) - Precompile contract reference

## Quick Reference: All Endpoints

| Network     | Type            | URL                                    | Use For                      |
| ----------- | --------------- | -------------------------------------- | ---------------------------- |
| **Mainnet** | EVM JSON-RPC    | `https://evm-rpc.bitbadges.io`         | MetaMask, Hardhat, ethers.js |
| **Mainnet** | Cosmos RPC      | `https://rpc.bitbadges.io`             | Cosmos SDK queries           |
| **Mainnet** | Cosmos REST/LCD | `https://lcd.bitbadges.io`             | REST API queries             |
| **Testnet** | EVM JSON-RPC    | `https://evm-rpc-testnet.bitbadges.io` | MetaMask, Hardhat, ethers.js |
| **Testnet** | Cosmos RPC      | `https://rpc-testnet.bitbadges.io`     | Cosmos SDK queries           |
| **Testnet** | Cosmos REST/LCD | `https://lcd-testnet.bitbadges.io`     | REST API queries             |

## Other Endpoints

For Cosmos SDK operations, use the Tendermint RPC endpoints:

* **Mainnet RPC**: `https://rpc.bitbadges.io`
* **Mainnet REST/LCD**: `https://lcd.bitbadges.io`
* **Testnet RPC**: `https://rpc-testnet.bitbadges.io`
* **Testnet REST/LCD**: `https://lcd-testnet.bitbadges.io`

See the [Blockchain Overview](/for-developers/bitbadges-blockchain/overview.md) for more information about Cosmos SDK endpoints.