# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/for-developers/bitbadges-blockchain/evm-rpc-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.