Network Interfaces

Shardeum exposes different interfaces depending on how participants interact with the network. Application developers building EVM-compatible dApps primarily use Ethereum JSON-RPC, while validators, node operators, and infrastructure providers may interact with additional network-level interfaces for querying staking, validator, and protocol state.

This page provides a high-level overview of the interfaces available on Shardeum today and explains when each interface should be used. Detailed specifications and usage examples are documented separately where applicable.

EVM JSON-RPC Interface (For Application Developers)

Shardeum is a fully EVM-compatible Layer 1 blockchain. Application developers can interact with the network using standard Ethereum JSON-RPC APIs and familiar tooling such as MetaMask, ethers.js, web3.js, viem, Hardhat, and Foundry, without requiring protocol-specific changes.

If you have previously built on Ethereum, you can use the same workflows, libraries, and mental models on Shardeum.

The JSON-RPC interface is used for:

Sending transactions
Deploying and interacting with smart contracts
Querying blocks, transactions, logs, and account state
Subscribing to real-time events via WebSockets

Full JSON-RPC method reference, advanced examples, and error handling guidance are documented separately in the JSON-RPC Guide

Mainnet Endpoints

Service	Endpoint
JSON-RPC	`https://api.shardeum.org`
WebSocket	`wss://api.shardeum.org`
LCD (REST)	`https://lcd.shardeum.org`
gRPC	`grpc.shardeum.org:9090`
Explorer	`https://explorer.shardeum.org`
Chain ID	`8118`

Chain Configuration

{
  "chainId": "8118",        // EVM chain ID (hex: 0x1fb6)
  "chainName": "Shardeum",
  "nativeCurrency": {
    "name": "SHM",
    "symbol": "SHM",
    "decimals": 18
  },
  "rpcUrls": ["https://api.shardeum.org"],
  "blockExplorerUrls": ["https://explorer.shardeum.org"]
}

The examples below demonstrate common connectivity and interaction patterns using the EVM JSON-RPC interface. They are intentionally minimal and focus on how applications connect to the Shardeum network, rather than providing a complete method reference.

1. JSON-RPC Examples

Example: Connecting with ethers.js

import { ethers } from 'ethers';
 
// Create provider
const provider = new ethers.JsonRpcProvider('https://api.shardeum.org');
 
// Get block number
const blockNumber = await provider.getBlockNumber();
console.log('Current block:', blockNumber);
 
// Get account balance
const balance = await provider.getBalance('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
console.log('Balance:', ethers.formatEther(balance));

WebSocket Support

For applications that require real-time updates, Shardeum supports event subscriptions over WebSocket connections.

const wsProvider = new ethers.WebSocketProvider('wss://api.shardeum.org');
 
// Subscribe to new blocks
wsProvider.on('block', (blockNumber) => {
  console.log('New block finalized:', blockNumber);
});

2. Network Interfaces (Validators & Infrastructure)

In addition to EVM-compatible JSON-RPC interfaces, Shardeum exposes network-level APIs for interacting with protocol features such as staking, delegation, validator information, and governance. These APIs are primarily intended for:

validators and node operators,
delegators and staking dashboards, and
infrastructure services and analytics platforms.

Application developers building smart contracts or dApps will typically not need these APIs and should instead use the EVM JSON-RPC interface.

REST API (Network Queries)

Shardeum provides REST-based endpoints for querying network and staking-related state, including account balances, validator sets, delegations, rewards, and governance proposals.

These endpoints expose protocol-level data derived from the underlying network state and are read-only.

Mainnet REST Endpoint:

https://lcd.shardeum.org

These endpoints follow Shardeum’s EVM and network query patterns where applicable, but only explicitly enabled interfaces should be considered supported.

Common Queries

Bank Module (Token Transfers)

# Get account balance
GET /cosmos/bank/v1beta1/balances/{address}
 
# Get total supply
GET /cosmos/bank/v1beta1/supply

Validators and Delegation Information

# List validators
GET /cosmos/staking/v1beta1/validators
 
# Get validator details
GET /cosmos/staking/v1beta1/validators/{validatorAddr}
 
# Get delegations for address
GET /cosmos/staking/v1beta1/delegations/{delegatorAddr}
 
# Get validator delegations
GET /cosmos/staking/v1beta1/validators/{validatorAddr}/delegations

Rewards and Distribution

# Get delegation rewards
GET /cosmos/distribution/v1beta1/delegators/{delegatorAddr}/rewards
 
# Get validator commission
GET /cosmos/distribution/v1beta1/validators/{validatorAddr}/commission

Governance

# List proposals
GET /cosmos/gov/v1beta1/proposals
 
# Get proposal details
GET /cosmos/gov/v1beta1/proposals/{proposalId}
 
# Get votes for proposal
GET /cosmos/gov/v1beta1/proposals/{proposalId}/votes

3. gRPC API (Advanced/High-Throughput Access)

For applications that require high-performance or low-latency access to network state, Shardeum also exposes gRPC interfaces. The gRPC API provides the same underlying data as the REST endpoints but is more efficient for:

large data queries,
frequent polling, and
backend or infrastructure services.

Mainnet gRPC Endpoint:

grpc.shardeum.org:9090

Example: Query with grpcurl

# List validators
grpcurl grpc.shardeum.org:9090 \
  cosmos.staking.v1beta1.Query/Validators

Note: The gRPC API can also be used to query account balances, staking state, and other network-level data for high-throughput backend services.

Example: JavaScript gRPC Client

This call returns the current active validator set using default query parameters. Advanced filtering and pagination options are available through lower-level query interfaces.

import { StargateClient } from '@cosmjs/stargate';
 
const client = await StargateClient.connect('RPC_ENDPOINT_HERE');
 
// Get active validator set
const validators = await client.getValidators();
console.log(validators);

4. Event Listening (EVM Logs and WebSockets)

Shardeum supports standard Ethereum-style event and log subscriptions, allowing applications to react to on-chain activity such as contract events, transfers, and state changes.

Listening to Events with eth_getLogs

Smart contract events can be queried using the standard Ethereum logs interface. This approach is suitable for:

historical queries,
batch processing,
backend services, and
analytics pipelines.

// Listen for ERC-20 Transfer events
const filter = {
  address: '0x...', // Token contract address
  topics: [
    ethers.id('Transfer(address,address,uint256)') // Event signature
  ],
  fromBlock: 'latest'
};
 
const logs = await provider.getLogs(filter);
console.log('Transfer events:', logs);

Real-Time Event Subscriptions (WebSocket)

For applications that require real-time updates, Shardeum supports event subscriptions over WebSocket connections. This approach is commonly used for:

live UI updates,
notifications,
dashboards, and
monitoring services.

Example: Subscribe to Contract Events

const wsProvider = new ethers.WebSocketProvider('wss://api.shardeum.org');
 
// Subscribe to contract events
const filter = { address: contractAddress };
 
wsProvider.on(filter, (log) => {
  console.log('New event:', log);
});

For real-time processing, applications can subscribe to newly finalized blocks and query logs or state as blocks are produced.

wsProvider.on('block', (blockNumber) => {
  console.log('New block finalized:', blockNumber);
});

For historical event data, use block-range queries with eth_getLogs.

Rate Limits

Rate limits apply to public endpoints and may change over time. Public RPC endpoints have the following rate limits:

Requests per second: 10
Requests per minute: 600
Concurrent connections: 5

For higher limits, consider running your own RPC node.

Best Practices

The following best practices help ensure reliable, efficient, and production-ready integrations with the Shardeum network.

1. Use the Appropriate Interface

Choose the API layer based on your use case:

Smart contracts and dApps → Use EVM JSON-RPC
Staking, delegation, and validator data → Use Network Interfaces (Validators & Infrastructure)
Historical data and analytics → Use block-range queries (eth_getLogs) and custom indexing pipelines where required

2. Handle Errors Gracefully

Always implement proper error handling and retries when interacting with network APIs.

try {
  const balance = await provider.getBalance(address);
} catch (error) {
  console.error('RPC error:', error);
 
  // Implement retry or fallback logic where appropriate
}

Avoid assuming immediate success, especially in production environments.

3. Submit Transactions Sequentially When Necessary

When sending multiple transactions from the same account, submit them sequentially to avoid nonce conflicts and rate limits. Avoid sending large bursts of parallel transactions to the same destination address.

4. Batch and Cache Read Requests

For applications making frequent read calls:

batch RPC requests where supported, and
cache frequently accessed data such as balances, blocks, or metadata.

This reduces latency and minimizes unnecessary API calls.

5. Design Idempotent Event Consumers

When processing events or logs:

assume events may be received more than once,
design consumers to handle duplicate events safely, and
persist checkpoints to resume processing reliably after restarts.

This is especially important for backend services and indexers.

6. Use WebSockets Carefully

WebSocket connections are ideal for real-time updates but should be handled defensively:

implement reconnection logic,
handle dropped connections gracefully, and
fall back to polling if required.

Do not rely on WebSocket connections as the sole source of truth.

7. Run Your Own Infrastructure for Production

For high-throughput or mission-critical applications, consider running your own RPC or full node. This provides:

higher reliability,
predictable performance, and
greater control over rate limits and availability.

Notes: Public API endpoints are shared resources and may be subject to rate limits or changes. For the latest implementation details and advanced usage, refer to the Shardeum open-source codebase on Github.