SEO Title: Redbelly Network Developer Troubleshooting: Fix Common RPC, Wallet, Gas, Deployment & EligibilitySDK Errors

Description: A practical troubleshooting guide for Redbelly developers covering recurring RPC, MetaMask, transaction, gas, deployment, contract verification, testnet funding, and EligibilitySDK integration problems.

Network: Redbelly Testnet
Testnet RPC: https://governors.testnet.redbelly.network
Testnet Chain ID: 153
Currency: RBNT
Testnet Explorer: https://redbelly.testnet.routescan.io/

Redbelly's current developer environment identifies Testnet as chain ID 153 with the canonical RPC endpoint above.

Table of Contents

• Quick Reference Index
• Before Troubleshooting

• Network and RPC

  • 1. Routescan API Returns 429 Too Many Requests
  • 2. RPC Endpoint Times Out or Does Not Respond
  • 3. Wrong or Outdated Redbelly RPC Endpoint
  • 4. Chain ID Mismatch
  • 5. JSON-RPC Error Before Wallet Activation

• Wallet and MetaMask

  • 6. MetaMask Does Not Detect Redbelly
  • 7. RBNT Appears on Explorer but Not in MetaMask
  • 8. Ledger + MetaMask Returns Internal JSON-RPC Error

• Transactions and Gas

  • 9. Insufficient RBNT for Deployment
  • 10. Cannot Estimate Gas
  • 11. Insufficient Contract Balance
  • 12. Nonce Too Low
  • 13. Transaction Remains Pending

• Smart Contract Deployment and Verification

  • 14. Hardhat Deployment Uses the Wrong Network
  • 15. Contract Verification Fails

• EligibilitySDK

  • 16. EligibilitySDK Package Cannot Be Installed
  • 17. Missing REDBELLY_API_KEY
  • 18. EligibilitySDK Test Credential Faucet Is Unavailable
  • 19. Local EligibilitySDK Callback Does Not Work
  • 20. Developer Cannot Determine a Wallet's On-Chain Eligibility

• Verification Matrix

• Community Validation

• Sources and References

Quick Reference Index

Before Troubleshooting

Always confirm the environment first.

Redbelly Testnet

Network:   Redbelly Testnet
RPC:       https://governors.testnet.redbelly.network
Chain ID:  153
Currency:  RBNT
Explorer:  https://redbelly.testnet.routescan.io/

Check the RPC directly:

curl -s -X POST https://governors.testnet.redbelly.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

Expected result:

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

0x99 is hexadecimal for chain ID 153.

Network and RPC

1. Routescan API Returns 429 Too Many Requests

Symptom

The explorer API returns:

HTTP 429
Too Many Requests
rate-limit

A Discord developer reported:

The HTTP server response is not ok. Status code: 429

Another developer independently reported that Routescan was repeatedly rate-limiting API requests.

Root Cause

Routescan applies request-per-second and daily call limits. A 429 means the API limit has been exceeded.

Routescan currently documents a keyless free tier of 2 requests/second and 10,000 calls/day. A registered free API key increases this to 5 requests/second and 100,000 calls/day.

Solution

Reduce request frequency and implement retry backoff.

Example:

async function fetchWithBackoff(url, options = {}, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const delay = Math.min(1000 * 2 ** attempt, 10000);
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error("Routescan API rate limit exceeded");
}

For applications making frequent API calls, use a registered Routescan API key and send it in the apikey header:

curl \
  -H "apikey: YOUR_API_KEY" \
  "https://api.routescan.io/v2/network/testnet/evm/153/etherscan/api?module=account&action=balance&address=YOUR_ADDRESS"

Routescan recommends backoff/retry or a higher-limit plan when the limit is exceeded.

Prevention

• Cache explorer/API responses.
• Do not poll continuously when event subscriptions or longer intervals are sufficient.
• Implement exponential backoff.
• Use a registered API key for applications with sustained API usage.
• Never expose an API key in frontend code.

2. RPC Endpoint Times Out or Does Not Respond

Symptom

Typical symptoms include:

RPC timeout
connection timed out
Internal JSON-RPC error
Failed to fetch

or a request simply hangs.

Root Cause

Possible causes include:

• Incorrect RPC URL.
• Temporary network/service interruption.
• Local proxy/VPN problems.
• Application configured for an obsolete endpoint.
• Incorrect environment configuration.

Solution

First test the RPC outside your application:

curl -s -X POST https://governors.testnet.redbelly.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

If the result is 0x99, the endpoint is responding correctly.

If it fails:

1. Confirm the URL.
2. Try another network connection.
3. Temporarily disable a VPN/proxy.
4. Check Redbelly announcements for service interruptions.
5. Retry with the canonical endpoint.

Prevention

Keep the RPC URL in one environment variable rather than hardcoding different URLs throughout the project.

REDBELLY_TESTNET_RPC=https://governors.testnet.redbelly.network

3. Wrong or Outdated Redbelly RPC Endpoint

Symptom

A tutorial or existing project uses an endpoint that no longer responds.

Root Cause

Developer documentation and older projects can contain legacy network configuration.

The current Redbelly Developer Portal identifies:

Testnet:
https://governors.testnet.redbelly.network

with chain ID 153.

Solution

Update the RPC everywhere it is configured:

networks: {
  redbellyTestnet: {
    url: "https://governors.testnet.redbelly.network",
    chainId: 153
  }
}

Also update:

• Hardhat
• Foundry
• wagmi/viem
• MetaMask
• deployment scripts
• .env files

Prevention

Before using an older tutorial, verify the network parameters against the current Redbelly Developer Portal.

4. Chain ID Mismatch

Symptom

Errors may include:

chain ID mismatch
network changed
wrong network
Unrecognized chain ID

Root Cause

Redbelly Mainnet and Testnet use different chain IDs:

Mainnet: 151
Testnet: 153

Using Mainnet configuration with Testnet RPC, or vice versa, causes network mismatches.

Solution

Check the actual RPC chain ID:

curl -s -X POST https://governors.testnet.redbelly.network \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

For Testnet, configure:

chainId: 153

In MetaMask, switch to the same network.

Prevention

Define network configuration once and reuse it across the application, deployment scripts and wallet configuration.

5. JSON-RPC Error Before Wallet Activation

Symptom

A developer connects to Redbelly but receives a JSON-RPC error when attempting network operations.

Root Cause

Community support reports have identified incomplete KYC/account activation as a cause of transaction-related RPC errors for accounts that have not been enabled for Redbelly access.

Solution

1. Complete the required Redbelly access/KYC process.
2. Connect the same wallet used by the dApp.
3. Confirm the wallet is enabled.
4. Switch back to Redbelly Testnet/Mainnet.
5. Retry the transaction.

Do not assume every Internal JSON-RPC error is caused by KYC. First verify the RPC endpoint and chain ID, then verify wallet/account activation.

Prevention

Add an account-activation check to developer onboarding before debugging application code.

Wallet and MetaMask

6. MetaMask Does Not Detect Redbelly

Symptom

Redbelly does not appear as the active network, or the dApp cannot switch the wallet to Redbelly.

Root Cause

The wallet is not configured with the correct Redbelly network parameters.

Solution

For Testnet use:

Network Name: Redbelly Testnet
RPC URL: https://governors.testnet.redbelly.network
Chain ID: 153
Currency Symbol: RBNT
Explorer: https://redbelly.testnet.routescan.io/

A dApp can request a network switch:

await window.ethereum.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x99" }]
});

If the network does not exist in the wallet, add it first through the wallet's network configuration.

Prevention

Use wallet network switching rather than asking users to manually edit configuration whenever possible.

7. RBNT Appears on Explorer but Not in MetaMask

Symptom

The developer can see RBNT associated with the address on the Redbelly explorer, but the wallet balance appears empty.

Root Cause

The wallet may be connected to a different network or using incorrect network configuration.

Solution

Confirm:

Network: Redbelly Network Mainnet or Redbelly Testnet
Chain ID: correct for the environment
RPC: correct for the environment
Currency: RBNT

For Testnet:

RPC: https://governors.testnet.redbelly.network
Chain ID: 153
Symbol: RBNT

Then restart/reconnect MetaMask and verify the same address is selected.

Prevention

Always display the connected chain ID and wallet address in the dApp during development.

8. Ledger + MetaMask Returns Internal JSON-RPC Error

Symptom

A Ledger user connected through MetaMask cannot submit transactions and receives:

Internal JSON-RPC error

or the transaction does not respond.

Root Cause

The error is not specific enough to identify a single cause. It can result from:

• wrong network configuration;
• account not enabled;
• RPC problems;
• hardware-wallet signing configuration;
• transaction parameters rejected by the wallet.

Solution

Troubleshoot in this order:

1. Verify the Redbelly RPC responds with the expected chain ID.
2. Confirm MetaMask is on the correct Redbelly network.
3. Confirm the Ledger account is the account selected in MetaMask.
4. Confirm the account has sufficient RBNT.
5. Confirm the account is enabled for Redbelly transactions.
6. Retry a simple transaction before testing a complex contract call.
7. If the same account works with another supported wallet while Ledger does not, isolate the issue to the Ledger/MetaMask path.

Prevention

Test the complete wallet stack with a simple transaction before integrating contract deployment or application-specific transaction flows.

Transactions and Gas

9. Insufficient RBNT for Deployment

Symptom

Deployment fails with:

insufficient funds

or the developer cannot pay transaction gas.

Root Cause

The deploying account does not hold enough RBNT to cover the transaction.

A Discord developer reported being blocked from running deployment scripts because their Redbelly Testnet RBNT balance was insufficient.

Solution

Check the wallet balance:

const balance = await provider.getBalance(wallet.address);
console.log(balance);

For Testnet, obtain RBNT through the current official testnet funding mechanism.

Do not use Mainnet RBNT for Testnet gas.

Prevention

Check the deployer balance before deployment:

const balance = await provider.getBalance(wallet.address);

if (balance === 0n) {
  throw new Error("Deployer has no RBNT");
}

For repeated automated deployments, budget testnet RBNT before running deployment scripts.

10. Cannot Estimate Gas

Symptom

The wallet or SDK reports:

cannot estimate gas
transaction may fail or may require manual gas limit

Root Cause

Gas estimation executes the transaction simulation before sending it. If the simulated call would revert, the estimator can fail.

Common causes include:

• contract state does not satisfy the function requirements;
• contract lacks required balance;
• wrong parameters;
• caller lacks permission;
• wrong network;
• contract address is incorrect.

Solution

First inspect the complete revert message.

Then simulate the call directly with the same:

• sender;
• recipient;
• calldata;
• value.

Do not immediately solve the error by arbitrarily increasing the gas limit.

If the revert indicates insufficient contract balance, fix the contract balance first.

Prevention

Test contract preconditions before sending transactions and surface readable revert messages in the frontend.

11. Insufficient Contract Balance

Symptom

Browser console or wallet output contains:

execution reverted: Insufficient contract balance

and may also contain:

cannot estimate gas

Root Cause

The contract does not have enough RBNT/value to satisfy the operation being requested.

Gas estimation fails because the simulated transaction would revert.

Solution

Check the contract balance:

const balance = await provider.getBalance(contractAddress);
console.log(balance.toString());

If the contract is expected to hold RBNT, fund it with the required amount.

Then retry gas estimation.

Prevention

Before calling a payout, withdrawal or value-dependent contract function:

const balance = await provider.getBalance(contractAddress);

if (balance < requiredAmount) {
  throw new Error("Contract balance is insufficient");
}

12. Nonce Too Low

Symptom

The transaction fails with:

nonce too low

or another transaction using the same nonce is already pending/mined.

Root Cause

The application submitted a transaction with a nonce lower than the account's current pending nonce.

This commonly happens when:

• transactions are submitted rapidly;
• a stale nonce is cached;
• multiple scripts use the same account;
• a previous transaction is still pending.

Solution

Read the pending nonce rather than a stale confirmed nonce:

const nonce = await provider.getTransactionCount(
  wallet.address,
  "pending"
);

When using ethers, prefer the library's nonce management where possible instead of manually incrementing nonces.

Prevention

Avoid hardcoding nonces and do not let multiple independent processes submit sequential transactions from the same account without nonce coordination.

13. Transaction Remains Pending

Symptom

A transaction stays pending for an unusually long time and never receives a receipt.

Root Cause

Possible causes include:

• stale RPC connection;
• incorrect nonce;
• competing pending transactions;
• transaction replacement;
• application waiting on the wrong provider/network.

Solution

Check the transaction:

const tx = await provider.getTransaction(txHash);
console.log(tx);

Check the receipt:

const receipt = await provider.getTransactionReceipt(txHash);
console.log(receipt);

Then verify:

wallet address
chain ID
RPC endpoint
nonce

Do not blindly submit the same transaction repeatedly. Repeated submissions can create additional nonce conflicts.

Prevention

Use a single transaction queue for automated workloads and monitor both transaction hash and receipt status.

Smart Contract Deployment and Verification

14. Hardhat Deployment Uses the Wrong Network

Symptom

Deployment fails because Hardhat connects to the wrong chain or cannot reach the expected Redbelly environment.

Root Cause

The network configuration does not match the Redbelly environment.

Solution

Configure Testnet explicitly:

module.exports = {
  networks: {
    redbellyTestnet: {
      url: "https://governors.testnet.redbelly.network",
      chainId: 153,
      accounts: process.env.PRIVATE_KEY
        ? [process.env.PRIVATE_KEY]
        : []
    }
  }
};

Deploy using the exact configuration key:

npx hardhat run scripts/deploy.js --network redbellyTestnet

Before deployment, confirm the RPC chain ID.

Prevention

Keep the network URL and chain ID in one configuration source and validate environment variables before deployment.

15. Contract Verification Fails

Symptom

The contract is deployed successfully but source-code verification fails on the block explorer.

Root Cause

Verification requires the explorer to reproduce the deployed bytecode. Common causes include:

• wrong compiler version;
• wrong optimization settings;
• incorrect constructor arguments;
• wrong contract path/name;
• wrong network;
• incorrect explorer API configuration.

Solution

First confirm the deployed contract is on Redbelly Testnet:

Chain ID: 153
Explorer: https://redbelly.testnet.routescan.io/

Then reproduce the exact deployment settings:

Solidity compiler version
Optimizer enabled/disabled
Optimizer runs
Contract path
Contract name
Constructor arguments

Do not change compiler settings after deployment and expect the bytecode to remain identical.

For Routescan API access, remember that API requests use the current Routescan API format and a 429 indicates rate limiting.

Prevention

Save deployment configuration and constructor arguments alongside every deployment.

EligibilitySDK

16. EligibilitySDK Package Cannot Be Installed

Symptom

Installation fails with errors such as:

403 Forbidden
401 Unauthorized
package not found

or npm cannot resolve:

@redbellynetwork/eligibility-sdk

Root Cause

The SDK is distributed through GitHub Packages and requires authentication with a GitHub Personal Access Token that has read:packages permission.

Solution

Create .npmrc:

@redbellynetwork:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true

Set the token:

export GITHUB_TOKEN="YOUR_GITHUB_TOKEN"

Then install:

npm install @redbellynetwork/eligibility-sdk

The current official Quickstart also requires a GitHub account with a Personal Access Token having read:packages.

Prevention

Never commit .npmrc containing a literal secret.

Use environment variables or your CI/CD secret manager.

17. Missing REDBELLY_API_KEY

Symptom

The SDK Quickstart cannot complete the verifier flow because:

REDBELLY_API_KEY

is missing.

Root Cause

The verifier service requires an API key.

The current Redbelly Quickstart explicitly instructs developers to configure REDBELLY_API_KEY and says to contact support if they do not have one.

Solution

Create .env.local:

REDBELLY_API_KEY="your_api_key_goes_here"
ALLOWED_ISSUER_DID="did:receptor:redbelly:testnet:31K82iKCtE6ciDc7oAr3T5EpjZb4S1EFM7c4xJaWkM2"

Never put the secret API key in frontend code.

If no API key has been issued to your project, follow the current support/onboarding process rather than inventing a key.

Prevention

Validate required environment variables when the backend starts:

if (!process.env.REDBELLY_API_KEY) {
  throw new Error("Missing REDBELLY_API_KEY");
}

18. EligibilitySDK Test Credential Faucet Is Unavailable

Symptom

The EligibilitySDK Quickstart instructs developers to obtain a test KYC credential from a demo credential faucet, but the faucet is shown as:

under development

Root Cause

The current Quickstart itself documents the demo credential faucet as under development.

This was also raised directly by a developer in the Redbelly Discord.

Solution

Do not build a production integration around an unavailable demo service.

For development:

1. Confirm whether Redbelly has provided an alternative test-credential issuance path.
2. Obtain the required test credential through the currently supported Redbelly developer process.
3. Do not substitute a production credential or issuer without updating the configured issuer DID.
4. Confirm the credential issuer matches the configured ALLOWED_ISSUER_DID.

Prevention

Before starting an end-to-end SDK integration, verify that:

API key
SDK package access
test credential
issuer DID
backend callback

are all available.

19. Local EligibilitySDK Callback Does Not Work

Symptom

The SDK starts locally but the wallet cannot complete the verification callback.

Typical setup:

http://localhost:3000

works in the browser, but the mobile identity wallet cannot reach the callback.

Root Cause

The mobile wallet cannot directly reach a developer's local machine through localhost.

The current Redbelly Quickstart explicitly instructs developers to expose the local application through an ngrok tunnel for the callback flow.

Solution

Start the application:

npm run dev

Then expose port 3000:

ngrok http 3000

Use the generated public HTTPS URL as the callback/base URL.

Example:

https://randomstring.ngrok.io

Prevention

Use a reachable HTTPS endpoint for wallet callbacks during development.

For production, deploy the verifier backend to a stable HTTPS domain rather than relying on a temporary tunnel.

20. Developer Cannot Determine a Wallet's On-Chain Eligibility

Symptom

A developer wants to enforce KYC/eligibility before allowing a wallet to interact with a smart contract, but does not know whether to query an API, registry or contract.

Root Cause

There are two separate concerns:

1. Eligibility proof/verification flow
2. On-chain chain-permission lookup

They should not be treated as the same operation.

The current EligibilitySDK documentation exposes useHasChainPermission(address) for checking chain permission from the client integration.

Solution

For a React application, configure the EligibilitySDK provider and use the documented hook:

import {
  EligibilityWidget,
  useHasChainPermission
} from "@redbellynetwork/eligibility-sdk";

Then query the connected address:

const { data: hasPermission } =
  useHasChainPermission(address);

Use the result as the application's eligibility signal according to the current SDK documentation.

For actual transaction enforcement, do not rely only on frontend logic. The contract/backend architecture must enforce the required permission independently.

Prevention

Document clearly whether each application check is:

Frontend eligibility UX
Backend proof verification
On-chain permission enforcement

Do not assume that hiding a button in the frontend provides smart-contract security.

Verification Matrix

The following verification matrix should be completed before claiming the wiki has passed the technical-accuracy benchmark.

Do not mark an item as "tested" until the result has actually been reproduced.

Community Validation

The issue inventory was built from recurring developer questions observed in Redbelly community channels, including reports concerning Routescan rate limits, EligibilitySDK credentials and package access, test credential availability, KYC/eligibility integration, wallet/RPC failures, MetaMask configuration, gas estimation, contract balance and Testnet RBNT availability.

Before final submission, the draft must be posted in the Redbelly developer Discord and reviewed by at least three active developers.

Record their feedback using this format:

Validation rule

Do not claim community validation is complete until the draft has actually been shared and three active developers have provided feedback.

Sources and References

• Redbelly Network environment configuration: current Mainnet/Testnet RPCs and chain IDs.
• Redbelly EligibilitySDK Installation: GitHub Packages authentication and SDK installation.
• Redbelly EligibilitySDK Getting Started: API key, test credentials, ngrok callback and end-to-end flow.
• Redbelly EligibilitySDK Backend Setup: required verifier endpoints and Testnet configuration.
• Redbelly EligibilitySDK React integration and useHasChainPermission.
• Routescan API rate limits and API-key documentation.

Maintenance

This wiki should be treated as a living developer resource.

When Redbelly changes:

• RPC endpoints
• chain IDs
• Testnet faucet procedures
• EligibilitySDK package access
• API-key requirements
• contract addresses
• explorer APIs
• wallet requirements

the corresponding troubleshooting entry should be reviewed and updated before developers rely on it.

Last reviewed: August 2026