---
name: Chainstack
description: Use when deploying blockchain nodes, managing RPC endpoints, querying blockchain data, configuring network access, or building Web3 applications. Agents should reach for this skill when users need to set up infrastructure for 70+ blockchain networks, authenticate API requests, handle blockchain queries, or troubleshoot node connectivity issues.
metadata:
    mintlify-proj: chainstack
    version: "1.0"
---

# Chainstack Skill

## Product summary

Chainstack is a managed blockchain infrastructure platform providing RPC access to 70+ blockchain networks (Ethereum, Solana, Bitcoin, Polygon, and others). Deploy a node from the console to get an HTTPS or WebSocket endpoint in seconds, or run the same stack on your own Kubernetes cluster with Chainstack Self-Hosted. Agents interact with Chainstack through:

- **Console**: https://console.chainstack.com/ — deploy nodes, manage projects, view credentials
- **Platform API v2**: Programmatically manage projects and nodes (recommended)
- **Platform API v1**: Legacy API for organizations, networks, nodes, and faucets
- **Node RPC endpoints**: Standard JSON-RPC, WebSocket, or gRPC (protocol-dependent)
- **Faucet API**: Request testnet tokens via RPC method or web interface

Key files and paths:
- Node credentials: HTTPS endpoint (key-protected or password-protected), WebSocket endpoint, gRPC endpoint (Sui, Solana)
- Authentication: API key (URL-based), basic auth (username/password), or x-token (gRPC)
- Billing: Request units (RUs) — 1 RU for full node, 2 RUs for archive queries

## When to use

Reach for this skill when:

- **Deploying infrastructure**: User needs a blockchain node for a specific network (Ethereum, Solana, Polygon, etc.)
- **Configuring endpoints**: User needs to connect a Web3 library (ethers.js, web3.js, web3.py) to a Chainstack node
- **Managing access**: User needs to set up authentication, rotate credentials, or configure access rules (IP whitelist, origin restrictions)
- **Querying blockchain data**: User needs to call RPC methods (eth_call, getBalance, getTransaction, etc.) and needs to understand request unit costs
- **Troubleshooting connectivity**: User encounters HTTP errors (401, 429, 504), WebSocket disconnects, or JSON-RPC errors
- **Migrating workloads**: User is moving from another provider (Infura, Alchemy, Syndica, Grove) and needs endpoint swap guidance
- **Billing and quotas**: User needs to understand pricing, request units, or plan limits

## Quick reference

### Node types

| Type | Use case | Deployment | Cost |
|------|----------|-----------|------|
| **Global Node** | High availability, global distribution, instant access | Seconds | Per-request (RUs) |
| **Unlimited Node** | Sustained high throughput (3000+ RPS) | Minutes | Per-request + premium |
| **Trader Node** | MEV-protected transactions, Warp support | 3-6 minutes | Per-request + premium |
| **Dedicated Node** | Custom config, debug/trace APIs, archive mode | Hours | Hourly compute + storage |

### Authentication methods

| Method | Format | Security | Use case |
|--------|--------|----------|----------|
| **Key auth** | `https://nd-xxx.p2pify.com/KEY` | Lower — URL visible | Development, public endpoints |
| **Basic auth** | `https://user:pass@nd-xxx.p2pify.com` | Higher — header-based | Production, private endpoints |
| **x-token (gRPC)** | Passed in request metadata | Higher — not in URL | Sui, Solana gRPC endpoints |

### Request unit costs

| Request type | Cost | Example |
|--------------|------|---------|
| Full node query | 1 RU | `eth_call` on recent block, `getBalance` |
| Archive query | 2 RUs | `eth_call` on old block, `getTransaction` from months ago |
| Solana archive | 2 RUs | `getTransaction` on slot below pruning boundary |
| TRON (all) | 1 RU | All TRON requests (no archive split) |

### Common HTTP error codes

| Code | Cause | Fix |
|------|-------|-----|
| `401` | Wrong key or password | Verify credentials in console |
| `413` | Request body > 1 MB | Paginate eth_getLogs, batch fewer calls |
| `429` | Rate limit hit | Reduce RPS or upgrade to Unlimited Node |
| `504` | Gateway timeout | Paginate heavy queries (traces, wide logs) or use Dedicated Node |
| `502` / `503` | Server-side issue | Retry with backoff; contact support if persistent |

### JSON-RPC error codes

| Code | Meaning | Fix |
|------|---------|-----|
| `-32601` | Method not found | Check protocol reference; enable debug/trace APIs if needed |
| `-32602` | Invalid params | Validate parameter types and values |
| `-32000` | Node error (e.g., "missing trie node") | See error message; may need archive node or different query |

## Decision guidance

### When to use Global Node vs Dedicated Node

| Criteria | Global Node | Dedicated Node |
|----------|-------------|----------------|
| **Throughput** | Up to ~3000 RPS | Unlimited (custom resource allocation) |
| **Latency** | Low (global distribution) | Very low (dedicated hardware) |
| **Cost model** | Per-request (RUs) | Hourly compute + storage |
| **Debug/trace APIs** | Limited | Full access (custom tracers) |
| **Setup time** | Seconds | Hours |
| **Best for** | Most dApps, public endpoints | High-volume trading, indexers, custom needs |

### When to use key auth vs basic auth

| Scenario | Key auth | Basic auth |
|----------|----------|-----------|
| **Development** | ✓ Simpler setup | — |
| **Production** | — | ✓ More secure (not in URL) |
| **Public endpoint** | ✓ Acceptable | — |
| **Private endpoint** | — | ✓ Recommended |
| **Rotation frequency** | High (URL-based) | Low (header-based) |

### When to use Full vs Archive node mode

| Need | Full node | Archive node |
|------|-----------|--------------|
| **Recent state queries** | ✓ 1 RU | 2 RUs (wasteful) |
| **Historical state** | ✗ Fails ("missing trie node") | ✓ 2 RUs |
| **Indexing from genesis** | ✗ Can't query old blocks | ✓ Required |
| **Cost-sensitive** | ✓ Cheaper | — |

## Workflow

### Deploy a node and get an endpoint

1. **Create a project** (if needed):
   - Log in to https://console.chainstack.com/
   - Click "Create project", provide name and optional description
   - Note the project ID

2. **Deploy a node**:
   - Click "Get Started" (new project) or "Join Network" (existing)
   - Select protocol (Ethereum, Solana, Polygon, etc.) and network (mainnet, testnet)
   - Choose node type: Global Node (default), Dedicated, Unlimited, or Trader
   - Select node mode: Full (recent state) or Archive (all history)
   - Pick cloud provider (AWS, Azure, Google Cloud, VZO)
   - Name the node and review monthly cost
   - Click "Deploy" and wait for status to change from "Pending" to "Running"

3. **Retrieve credentials**:
   - Click your project → network → node name
   - Copy HTTPS endpoint (key-protected or password-protected)
   - Copy WebSocket endpoint (if needed for subscriptions)
   - Copy gRPC endpoint and x-token (if protocol supports it)

4. **Test connectivity**:
   - Use curl or Postman to call a simple method:
     ```bash
     curl -X POST https://nd-xxx.p2pify.com/KEY \
       -H "Content-Type: application/json" \
       -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
     ```
   - Expect a JSON-RPC response with a result or error

### Connect a Web3 library

1. **ethers.js** (recommended):
   ```javascript
   const { ethers } = require("ethers");
   const provider = new ethers.JsonRpcProvider("https://nd-xxx.p2pify.com/KEY");
   const balance = await provider.getBalance("0x...");
   ```

2. **web3.js** (deprecated; use ethers.js for new projects):
   ```javascript
   const Web3 = require("web3");
   const web3 = new Web3("https://nd-xxx.p2pify.com/KEY");
   const balance = await web3.eth.getBalance("0x...");
   ```

3. **web3.py**:
   ```python
   from web3 import Web3
   w3 = Web3(Web3.HTTPProvider("https://nd-xxx.p2pify.com/KEY"))
   balance = w3.eth.get_balance("0x...")
   ```

### Rotate credentials

1. Navigate to your node in the console
2. Click "Edit" → "Rotate key" (for key auth) or "Rotate password" (for basic auth)
3. Copy the new credential
4. Update your application environment variables
5. Verify connectivity before removing old credential

### Handle rate limits (429 errors)

1. **Identify the limit**: Check your plan's RPS limit in console → project → statistics
2. **Reduce load**:
   - Batch JSON-RPC calls (up to ~50 per request)
   - Paginate eth_getLogs queries (narrow block ranges)
   - Implement exponential backoff on 429 responses
3. **Upgrade if needed**:
   - Switch to Unlimited Node for sustained high throughput
   - Contact support for custom rate limits

### Troubleshoot "missing trie node" error

1. **Cause**: Querying historical state on a full node
2. **Fix**:
   - Switch to Archive node mode (costs 2 RUs per query)
   - Or query only recent state (last ~128 blocks on Ethereum)
   - Or use a Dedicated Node with custom configuration

## Common gotchas

- **Credentials in version control**: Never commit API keys or passwords to git. Use environment variables (`.env` file, secrets manager).
- **URL-based auth is visible**: Key auth appears in URLs and logs. Use basic auth for production or rotate keys frequently.
- **1 MB request body limit**: Batch fewer JSON-RPC calls or paginate eth_getLogs. Split large payloads.
- **WebSocket idle timeout**: Implement automatic reconnect (1006 close code). See Handle real-time data with WebSockets.
- **Archive queries cost 2 RUs**: Full node queries cost 1 RU. Querying old state on full node fails with "missing trie node".
- **Nonce too low**: Use `eth_getTransactionCount(..., "latest")` to get the current nonce, not a cached value.
- **Replacement transaction underpriced**: Bump gas price by at least 10% when replacing a pending transaction.
- **Custom tracers disabled by default**: Debug/trace APIs (debug_traceTransaction, trace_call) need a Dedicated Node or explicit enablement.
- **Warp transactions are separate billing**: Warp (MEV-protected) transactions are charged separately from regular RUs.
- **Solana pruning boundary**: Solana full nodes prune old slots; queries below the boundary cost 2 RUs. Check the ledger size and safety buffer.

## Verification checklist

Before submitting work with Chainstack:

- [ ] Node status is "Running" (not "Pending", "Failed", or "Stopped")
- [ ] Endpoint is reachable: curl or Postman test succeeds
- [ ] Credentials are correct: key or password matches console
- [ ] Authentication method matches use case (key for dev, basic auth for prod)
- [ ] Node mode is appropriate: Full for recent queries, Archive for historical
- [ ] Request body is under 1 MB (split if needed)
- [ ] RPS is below plan limit (check statistics in console)
- [ ] Error handling includes retry logic with backoff
- [ ] WebSocket clients implement automatic reconnect
- [ ] Credentials are not in version control (use .env or secrets manager)
- [ ] Billing threshold is set to prevent unexpected charges
- [ ] For Dedicated Nodes: debug/trace APIs are enabled if needed

## Resources

- **Full documentation**: https://docs.chainstack.com/llms.txt — compact index of all sections
- **Complete portal**: https://docs.chainstack.com/llms-full.txt — entire documentation in one file
- **Critical pages**:
  - [Platform introduction](https://docs.chainstack.com/docs/platform-introduction) — overview of products and getting started
  - [Manage your node](https://docs.chainstack.com/docs/manage-your-node) — view credentials, monitor metrics, delete nodes
  - [Error reference](https://docs.chainstack.com/docs/error-reference) — HTTP, WebSocket, and JSON-RPC error codes with fixes
  - [Pricing and request units](https://docs.chainstack.com/docs/pricing-introduction) — billing, quotas, and cost model
  - [Authentication methods](https://docs.chainstack.com/docs/authentication-methods-for-different-scenarios) — key auth vs basic auth
  - [Available node methods](https://docs.chainstack.com/docs/available-node-methods) — RPC methods by protocol
  - [Platform API getting started](https://docs.chainstack.com/reference/platform-api-getting-started) — programmatic node management

---

> For additional documentation and navigation, see: https://docs.chainstack.com/llms.txt