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
| Error / Keyword | Likely Cause | Jump To |
|---|---|---|
429 Too Many Requests |
Routescan API rate limit | #1 |
timeout / RPC not responding
|
Endpoint, network or service issue | #2 |
rpc-testnet.redbelly.network |
Outdated endpoint | #3 |
chain ID / 153 / 151
|
Network mismatch | #4 |
Internal JSON-RPC error |
Account/network/transaction configuration | #5 |
| MetaMask cannot find Redbelly | Network not configured | #6 |
| RBNT not visible in wallet | Token/network configuration | #7 |
| Ledger + MetaMask | Hardware-wallet/RPC/network issue | #8 |
insufficient funds |
Wallet lacks RBNT for gas | #9 |
cannot estimate gas |
Transaction would revert or required state is invalid | #10 |
Insufficient contract balance |
Contract lacks required RBNT/value | #11 |
nonce too low |
Stale or reused transaction nonce | #12 |
pending / stuck transaction |
RPC, nonce or replacement issue | #13 |
| Hardhat deployment failure | Wrong network/configuration | #14 |
| Contract verification failure | Wrong chain, compiler or constructor settings | #15 |
npm install / 403 / package unavailable |
GitHub Packages authentication | #16 |
REDBELLY_API_KEY |
Missing verifier API credential | #17 |
| Test credential faucet | Demo credential faucet unavailable | #18 |
localhost / callback failure |
Mobile wallet cannot reach local server | #19 |
hasChainPermission / KYC |
Eligibility integration uncertainty | #20 |
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:
- Confirm the URL.
- Try another network connection.
- Temporarily disable a VPN/proxy.
- Check Redbelly announcements for service interruptions.
- 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
-
.envfiles
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
- Complete the required Redbelly access/KYC process.
- Connect the same wallet used by the dApp.
- Confirm the wallet is enabled.
- Switch back to Redbelly Testnet/Mainnet.
- 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:
- Verify the Redbelly RPC responds with the expected chain ID.
- Confirm MetaMask is on the correct Redbelly network.
- Confirm the Ledger account is the account selected in MetaMask.
- Confirm the account has sufficient RBNT.
- Confirm the account is enabled for Redbelly transactions.
- Retry a simple transaction before testing a complex contract call.
- 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:
- Confirm whether Redbelly has provided an alternative test-credential issuance path.
- Obtain the required test credential through the currently supported Redbelly developer process.
- Do not substitute a production credential or issuer without updating the configured issuer DID.
- 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:
- Eligibility proof/verification flow
- 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.
| Issue | Verification Method | Status |
|---|---|---|
| RPC chain ID |
curl → eth_chainId
|
Verify |
| Routescan 429 | Controlled request-rate test | Verify |
| Wrong chain ID | Testnet RPC + Hardhat config | Verify |
| MetaMask network | Manual wallet configuration | Verify |
| Insufficient RBNT | Test deployment with unfunded account | Verify |
| Gas estimation | Reproduce failing contract state | Verify |
| Contract balance | Reproduce insufficient-balance revert | Verify |
| Hardhat deployment | Test deployment to Testnet | Verify |
| Routescan verification | Verify a test contract | Verify |
| SDK package installation | Fresh project + GitHub token | Verify |
| API key configuration | Fresh .env.local setup |
Verify |
| SDK callback | Local app + ngrok + wallet | Verify |
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:
| Reviewer | Role / Community Activity | Feedback | Change Made |
|---|---|---|---|
| Developer 1 | Redbelly developer/community contributor | [Insert feedback] | [Insert change] |
| Developer 2 | Redbelly developer/community contributor | [Insert feedback] | [Insert change] |
| Developer 3 | Redbelly developer/community contributor | [Insert feedback] | [Insert change] |
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
Top comments (0)