XDC Gateway Documentation

XDC Gateway provides enterprise-grade RPC infrastructure for XDC Network and 15+ other blockchain networks. Access reliable, fast, and scalable blockchain data through a unified API.

Get Started API Reference

Quick Start

Get started in 3 simple steps:

1. Create an Account

2. Generate an API Key

Navigate to the API Keys section in your dashboard and create a new key. Each key can be configured with specific rate limits and network access.

3. Make Your First Request

Use your API key to make RPC requests:

curl -X POST https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x5e903a6"
}

Authentication

All RPC requests require an API key. Include your key in the URL path:

https://ecloud.xdcrpc.com/{network}/{apiKey}

API keys are tied to your account and can be managed from the dashboard. You can create multiple keys for different applications or environments.

Security Best Practices

Never expose API keys in client-side code or public repositories
Use environment variables for key storage
Rotate keys periodically (recommended every 90 days)
Set appropriate rate limits per key
Use separate keys for development and production environments

API Reference Overview

XDC Gateway provides a REST API for managing your account, API keys, and accessing additional services. Base URL for all REST API requests:

https://cloud.xdcrpc.com/api/v1

Authentication

All API endpoints require authentication via Bearer token in the Authorization header:

Authorization: Bearer {your_access_token}

Auth Endpoints

POST/auth/register

Create a new account.

Request Body

{
  "email": "user@example.com",
  "password": "securePassword123",
  "name": "John Doe"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "user_uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "tier": "free"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

POST/auth/login

Authenticate and receive access tokens.

Request Body

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "user_uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "tier": "pro"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
    }
  }
}

POST/auth/refresh

Refresh access token using refresh token.

Request Body

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}

Network Endpoints

GET/networks

List all available blockchain networks.

Response

{
  "success": true,
  "data": [
    {
      "id": "network_uuid",
      "name": "XDC Mainnet",
      "slug": "xdc-mainnet",
      "chainId": 50,
      "type": "mainnet",
      "rpcUrl": "https://ecloud.xdcrpc.com/xdc-mainnet",
      "currency": {
        "name": "XDC",
        "symbol": "XDC",
        "decimals": 18
      }
    },
    {
      "id": "network_uuid_2",
      "name": "XDC Testnet",
      "slug": "xdc-testnet",
      "chainId": 51,
      "type": "testnet",
      "rpcUrl": "https://ecloud.xdcrpc.com/xdc-testnet",
      "currency": {
        "name": "XDC",
        "symbol": "XDC",
        "decimals": 18
      }
    }
  ]
}

GET/networks/:slug

Get details for a specific network by slug.

Path Parameters

Parameter	Type	Description
`slug`	string	Network slug (e.g., xdc-mainnet)

Response

{
  "success": true,
  "data": {
    "id": "network_uuid",
    "name": "XDC Mainnet",
    "slug": "xdc-mainnet",
    "chainId": 50,
    "type": "mainnet",
    "rpcUrl": "https://ecloud.xdcrpc.com/xdc-mainnet",
    "explorerUrl": "https://explorer.xinfin.network",
    "currency": {
      "name": "XDC",
      "symbol": "XDC",
      "decimals": 18
    },
    "supportedMethods": [
      "eth_blockNumber",
      "eth_getBalance",
      "eth_sendRawTransaction",
      "..."
    ]
  }
}

API Key Endpoints

GET/api-keys

List all API keys for your account.

Response

{
  "success": true,
  "data": [
    {
      "id": "key_uuid",
      "name": "Production Key",
      "key": "xg_live_abc123...",
      "prefix": "xg_live",
      "networks": ["xdc-mainnet", "ethereum"],
      "rateLimit": 1000,
      "usage": {
        "daily": 5420,
        "monthly": 125000
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-02-10T08:45:00Z"
    }
  ]
}

POST/api-keys

Create a new API key.

Request Body

{
  "name": "My App Key",
  "networks": ["xdc-mainnet", "xdc-testnet"],
  "rateLimit": 100
}

Response

{
  "success": true,
  "data": {
    "id": "key_uuid",
    "name": "My App Key",
    "key": "xg_live_xyz789...",
    "prefix": "xg_live",
    "networks": ["xdc-mainnet", "xdc-testnet"],
    "rateLimit": 100,
    "createdAt": "2024-02-10T20:00:00Z"
  }
}

DELETE/api-keys/:id

Delete an API key. This action cannot be undone.

Response

{
  "success": true,
  "message": "API key deleted successfully"
}

Usage Endpoints

GET/usage/stats

Get usage statistics for your account.

Query Parameters

Parameter	Type	Required	Description
`startDate`	string	No	Start date (YYYY-MM-DD)
`endDate`	string	No	End date (YYYY-MM-DD)

Response

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-02-01",
      "end": "2024-02-10"
    },
    "totalRequests": 125000,
    "requestsByNetwork": {
      "xdc-mainnet": 85000,
      "ethereum": 25000,
      "polygon": 15000
    },
    "requestsByMethod": {
      "eth_blockNumber": 45000,
      "eth_getBalance": 35000,
      "eth_call": 25000
    },
    "dailyBreakdown": [
      {
        "date": "2024-02-10",
        "requests": 15420
      }
    ]
  }
}

Faucet Endpoints

Request test tokens for development on testnets.

POST/faucet/request

Request test tokens from the faucet.

Request Body

{
  "network": "xdc-testnet",
  "address": "0x...",
  "amount": "1000"
}

Response

{
  "success": true,
  "data": {
    "txHash": "0x...",
    "amount": "1000",
    "network": "xdc-testnet",
    "recipient": "0x..."
  }
}

GET/faucet/balance

Get current faucet balance for all testnet networks.

Response

{
  "success": true,
  "data": {
    "xdc-testnet": {
      "balance": "10000000",
      "symbol": "XDC",
      "faucetAddress": "0x..."
    },
    "ethereum-sepolia": {
      "balance": "5000000",
      "symbol": "ETH",
      "faucetAddress": "0x..."
    }
  }
}

Whale Alerts

Get notified about large transactions on XDC Network.

GET/whale-alerts

Fetch recent whale alerts (large transactions).

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (max 100)
`minValue`	string	100000	Minimum transaction value in XDC

Response

{
  "success": true,
  "data": [
    {
      "id": "alert_uuid",
      "txHash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "500000",
      "valueUsd": 25000,
      "timestamp": "2024-02-10T19:30:00Z",
      "blockNumber": 68923000
    }
  ]
}

RPC Endpoints

Base URL for all RPC requests:

https://ecloud.xdcrpc.com/{network}/{apiKey}

Example Endpoints

# XDC Mainnet
https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY

# XDC Testnet
https://ecloud.xdcrpc.com/xdc-testnet/YOUR_API_KEY

# Ethereum
https://ecloud.xdcrpc.com/ethereum/YOUR_API_KEY

# Polygon
https://ecloud.xdcrpc.com/polygon/YOUR_API_KEY

Supported Methods

XDC Gateway supports all standard Ethereum JSON-RPC methods. Common methods include:

Method	Description
`eth_blockNumber`	Returns the current block number
`eth_getBalance`	Returns the balance of an address
`eth_getBlockByNumber`	Returns block data by number
`eth_getBlockByHash`	Returns block data by hash
`eth_getTransactionByHash`	Returns transaction data
`eth_getTransactionReceipt`	Returns transaction receipt
`eth_sendRawTransaction`	Submits a signed transaction
`eth_call`	Executes a call without creating a transaction
`eth_estimateGas`	Estimates gas for a transaction
`eth_gasPrice`	Returns current gas price
`eth_chainId`	Returns the chain ID
`eth_getLogs`	Returns logs matching filter criteria
`eth_getCode`	Returns code at a given address
`eth_getStorageAt`	Returns storage value at a position
`eth_getTransactionCount`	Returns nonce for an address
`eth_syncing`	Returns sync status
`eth_mining`	Returns mining status
`net_version`	Returns network version
`web3_clientVersion`	Returns client version

XDC-Specific Methods

XDC Network extends standard Ethereum JSON-RPC with additional methods:

Method	Description
`xdc_getBlockByNumber`	XDC-specific block retrieval
`xdc_getCandidates`	Get masternode candidates
`xdc_getMasternodes`	Get active masternodes
`xdc_getValidatorReward`	Get validator rewards
`xdc_getVoterReward`	Get voter rewards

Example Request

curl -X POST https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "xdc_getCandidates",
    "params": ["latest"],
    "id": 1
  }'

Supported Networks

XDC Gateway supports the following networks:

Network	Slug	Chain ID
XDC Mainnet	`xdc-mainnet`	50
XDC Testnet	`xdc-testnet`	51
Ethereum	`ethereum`	1
Ethereum Sepolia	`ethereum-sepolia`	11155111
Polygon	`polygon`	137
Polygon Amoy	`polygon-amoy`	80002
BNB Chain	`bsc`	56
BNB Testnet	`bsc-testnet`	97
Arbitrum One	`arbitrum`	42161
Arbitrum Sepolia	`arbitrum-sepolia`	421614
Optimism	`optimism`	10
Optimism Sepolia	`optimism-sepolia`	11155420
Base	`base`	8453
Base Sepolia	`base-sepolia`	84532
Avalanche C-Chain	`avalanche`	43114
Avalanche Fuji	`avalanche-fuji`	43113

Rate Limits

Rate limits vary by plan:

Plan	Requests/Min	Daily Limit	Monthly Limit
Free	100	10,000	100,000
Pro	1,000	100,000	1,000,000
Max	5,000	500,000	5,000,000
Enterprise	Unlimited	Unlimited	Custom

Rate Limit Headers

Responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707609600

Pricing

Free

$0/month

✓ 100 req/min
✓ 100,000 requests/month
✓ 3 API keys
✓ 5 networks
✓ Community support

Popular

Pro

$49/month

✓ 1,000 req/min
✓ 1,000,000 requests/month
✓ 10 API keys
✓ All 16+ networks
✓ Priority email support
✓ Advanced analytics

Max

$199/month

✓ 5,000 req/min
✓ 5,000,000 requests/month
✓ 25 API keys
✓ All 16+ networks
✓ Priority support
✓ Webhooks
✓ Whale alerts

Enterprise

Custom

✓ Unlimited requests/min
✓ Unlimited requests
✓ Unlimited API keys
✓ All 16+ networks
✓ Dedicated support
✓ SLA guarantee
✓ Custom features

Error Codes

XDC Gateway uses standard JSON-RPC error codes with additional custom codes:

Code	Message
`-32001`	Invalid or inactive API key
`-32002`	API key revoked or expired
`-32003`	API key not authorized for network
`-32004`	Unknown network
`-32005`	Rate limit exceeded
`-32006`	Daily request limit exceeded
`-32000`	Upstream RPC error

HTTP Status Codes

Status	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

JavaScript / TypeScript SDK

Use XDC Gateway with popular Web3 libraries:

ethers.js v6

import { ethers } from 'ethers';

// Create provider
const provider = new ethers.JsonRpcProvider(
  'https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY'
);

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

// Get balance
const balance = await provider.getBalance('0x...');
console.log('Balance:', ethers.formatEther(balance), 'XDC');

// Get block details
const block = await provider.getBlock(blockNumber);
console.log('Block timestamp:', block?.timestamp);

// Send transaction (requires signer)
const signer = new ethers.Wallet(privateKey, provider);
const tx = await signer.sendTransaction({
  to: '0x...',
  value: ethers.parseEther('1.0')
});
await tx.wait();
console.log('Transaction confirmed:', tx.hash);

web3.js

import Web3 from 'web3';

// Create Web3 instance
const web3 = new Web3(
  'https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY'
);

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

// Get balance
const balance = await web3.eth.getBalance('0x...');
console.log('Balance:', web3.utils.fromWei(balance, 'ether'), 'XDC');

// Get block details
const block = await web3.eth.getBlock(blockNumber);
console.log('Block timestamp:', block.timestamp);

// Send transaction (requires account)
const account = web3.eth.accounts.privateKeyToAccount(privateKey);
web3.eth.accounts.wallet.add(account);

const tx = {
  from: account.address,
  to: '0x...',
  value: web3.utils.toWei('1', 'ether'),
  gas: 21000
};

const receipt = await web3.eth.sendTransaction(tx);
console.log('Transaction confirmed:', receipt.transactionHash);

viem

import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { xdc, xdcTestnet } from 'viem/chains';

// Create public client (read-only)
const publicClient = createPublicClient({
  chain: xdc,
  transport: http('https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY')
});

// Get block number
const blockNumber = await publicClient.getBlockNumber();
console.log('Current block:', blockNumber);

// Get balance
const balance = await publicClient.getBalance({ 
  address: '0x...' 
});
console.log('Balance:', balance);

// Get block
const block = await publicClient.getBlock({ blockNumber });
console.log('Block timestamp:', block.timestamp);

// Create wallet client (for transactions)
const account = privateKeyToAccount(privateKey);
const walletClient = createWalletClient({
  account,
  chain: xdc,
  transport: http('https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY')
});

// Send transaction
const hash = await walletClient.sendTransaction({
  to: '0x...',
  value: parseEther('1')
});

const receipt = await publicClient.waitForTransactionReceipt({ hash });
console.log('Transaction confirmed:', receipt.transactionHash);

Python SDK

web3.py

from web3 import Web3

# Create Web3 instance
w3 = Web3(Web3.HTTPProvider(
    'https://ecloud.xdcrpc.com/xdc-mainnet/YOUR_API_KEY'
))

# Check connection
print(f"Connected: {w3.is_connected()}")

# Get current block number
block_number = w3.eth.block_number
print(f'Current block: {block_number}')

# Get balance
address = '0x...'
balance = w3.eth.get_balance(address)
print(f'Balance: {w3.from_wei(balance, "ether")} XDC')

# Get block details
block = w3.eth.get_block(block_number)
print(f'Block timestamp: {block.timestamp}')

# Send transaction (requires private key)
from eth_account import Account

account = Account.from_key(private_key)

tx = {
    'to': '0x...',
    'value': w3.to_wei(1, 'ether'),
    'gas': 21000,
    'gasPrice': w3.eth.gas_price,
    'nonce': w3.eth.get_transaction_count(account.address),
    'chainId': 50  # XDC Mainnet
}

# Sign and send
signed_tx = account.sign_transaction(tx)
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
print(f'Transaction confirmed: {tx_hash.hex()}')

Postman Collection

Download our Postman collection to quickly test all API endpoints:

Download Postman Collection