---
name: Chainstack
description: Use when deploying blockchain nodes, managing RPC endpoints, configuring infrastructure for 70+ blockchain networks, integrating with Web3 applications, or managing blockchain projects and billing. Agents should reach for this skill when users need to set up blockchain infrastructure, access RPC endpoints, deploy nodes, manage projects, or troubleshoot blockchain connectivity issues.
metadata:
    mintlify-proj: chainstack
    version: "1.0"
---

# Chainstack Skill

## Product summary

Chainstack is a managed blockchain infrastructure platform supporting 70+ networks (Ethereum, Solana, Bitcoin, Polygon, and others) with RPC node deployment, APIs, and self-hosted options. Agents use Chainstack to deploy nodes, manage projects, configure endpoints, and access blockchain data. Key resources: **Chainstack Console** (https://console.chainstack.com) for node management, **Platform API** for programmatic infrastructure control, **RPC endpoints** (HTTPS/WSS) for blockchain access, and **authentication tokens** for endpoint security. Primary docs: https://docs.chainstack.com

## When to use

Deploy this skill when:
- A user needs to deploy a blockchain node on a specific network (Ethereum, Solana, Polygon, etc.)
- Setting up RPC endpoints for a Web3 application or DApp
- Managing projects, networks, and nodes through the Chainstack console or API
- Configuring node types (Global Node, Dedicated Node, Trader Node, Unlimited Node)
- Troubleshooting blockchain connectivity, authentication, or rate limit issues
- Choosing between node types based on workload (high-throughput, latency-critical, sustained load)
- Integrating Web3 libraries (ethers.js, web3.js, web3.py) with Chainstack endpoints
- Monitoring node usage, metrics, and billing
- Migrating from another blockchain infrastructure provider

## Quick reference

### Node types and use cases

| Node Type | Billing | Best For | Deployment |
|-----------|---------|----------|-----------|
| **Global Node** | Per-request (RUs) | Default choice, global distribution, scales to any traffic | Instant (seconds) |
| **Dedicated Node** | Monthly compute + storage | Sustained heavy load, customization, specialized configs | 3-6 minutes |
| **Trader Node** | Per-request (RUs) | Latency-critical, regional, Warp transactions | 3-6 minutes |
| **Unlimited Node** | Flat monthly fee (RPS tier) | Predictable billing, high sustained traffic | Varies |

### Node modes

- **Full**: Recent blockchain state only; limited historical data
- **Archive**: Full blockchain data + historical state from genesis; 2x RU cost
- **Trader**: High-speed transaction propagation to mempool (Ethereum, Solana, BNB)

### Authentication methods

| Method | Format | Use Case |
|--------|--------|----------|
| **Key-protected** | `https://endpoint/AUTH_TOKEN` | Default; token in URL path |
| **Basic auth** | `https://user:pass@endpoint` | Alternative; credentials in URL |
| **gRPC x-token** | Metadata header `x-token: TOKEN` | Sui, Solana gRPC endpoints |

### Essential endpoints

- **HTTPS**: `https://nd-xxx.p2pify.com/AUTH_TOKEN` (JSON-RPC)
- **WSS**: `wss://ws-nd-xxx.p2pify.com/AUTH_TOKEN` (WebSocket subscriptions)
- **gRPC**: `protocol-network.core.chainstack.com:443` (select protocols)

### Billing units

- **Request Unit (RU)**: Measures request complexity
  - Full node request: 1 RU
  - Archive node request: 2 RUs
- **RPS limits**: Developer (25), Growth (250), Pro (400), Business (600), Enterprise (unlimited)
- **Quotas**: Monthly RU allowance per plan; extra usage auto-charges if enabled

### Common RPC methods

| Method | Purpose | Example |
|--------|---------|---------|
| `eth_blockNumber` | Get latest block | `{"method":"eth_blockNumber"}` |
| `eth_getBalance` | Account balance | `{"method":"eth_getBalance","params":["0x...","latest"]}` |
| `eth_call` | Read contract state | `{"method":"eth_call","params":[{...},"latest"]}` |
| `eth_sendRawTransaction` | Broadcast signed tx | `{"method":"eth_sendRawTransaction","params":["0x..."]}` |
| `eth_getLogs` | Query events | `{"method":"eth_getLogs","params":[{...}]}` |

## Decision guidance

### When to use X vs Y

| Scenario | Choose | Why |
|----------|--------|-----|
| New project, unknown traffic | Global Node | Scales elastically, instant deployment, no upfront cost |
| Sustained high throughput (>100 RPS) | Dedicated Node or Unlimited | Per-request billing becomes expensive; fixed monthly cost is cheaper |
| Latency-critical, regional workload | Trader Node | Regional deployment, optional dedicated gateway, Warp support |
| Predictable monthly budget | Unlimited Node add-on | Flat fee tied to RPS tier; no surprise overages |
| Historical data queries (past blocks) | Archive mode | Full mode has limited history; archive costs 2x RUs but enables all queries |
| Development/testing | Global Node on testnet | Free tier available; low cost for experimentation |
| Production with high security | Dedicated Node | Exclusive resources, customization, monitoring, dedicated gateway option |

### HTTP vs WebSocket

| Use Case | Protocol | Reason |
|----------|----------|--------|
| One-off queries, block data | HTTPS | Stateless, simple, no connection overhead |
| Real-time event monitoring | WSS | Persistent connection, subscriptions (newHeads, logs, pending txs) |
| High-frequency polling | HTTPS with batching | Batch multiple calls per request to reduce RPS |

## Workflow

### 1. Deploy a node and get an endpoint

1. **Sign up**: Go to https://console.chainstack.com and create an account
2. **Create project**: Click "Create project", provide name and optional description
3. **Add network**: In the project, click "Join Network" or "Get Started"
4. **Choose protocol and network**: Select blockchain (Ethereum, Solana, etc.) and network (mainnet, testnet)
5. **Select node type**: Pick Global Node (default), Dedicated, or Trader based on workload
6. **Configure node**: Choose mode (Full or Archive), cloud provider, region
7. **Deploy**: Click "Deploy"; status changes from Pending → Running (seconds to minutes)
8. **Get credentials**: Click the node name; copy HTTPS endpoint, WSS endpoint, and auth token
9. **Test endpoint**: Make a test RPC call (e.g., `eth_blockNumber`) to verify connectivity

### 2. Integrate with a Web3 application

1. **Choose library**: ethers.js (recommended), web3.js, or web3.py
2. **Install library**: `npm install ethers` or `pip install web3`
3. **Create provider**: Pass Chainstack endpoint to library constructor
4. **Set auth**: Include auth token in endpoint URL or use basic auth
5. **Make calls**: Use library methods to query blockchain (balances, contracts, events)
6. **Handle errors**: Implement retry logic for 429 (rate limit), 502 (gateway), 504 (timeout)
7. **Monitor usage**: Check node metrics in console to track RU consumption

### 3. Manage billing and quotas

1. **Check plan**: Go to Billing → Plan to see current subscription and RU quota
2. **Monitor usage**: View node metrics (Requests made, Method calls, Response codes)
3. **Enable extra usage**: If quota exceeded, toggle "Extra usage" to auto-charge overages
4. **Upgrade plan**: Click "Change" next to Plan to move to higher tier
5. **Review costs**: Understand RU pricing (full vs archive), Warp transaction costs, Dedicated Node hourly rates
6. **Set billing threshold**: Configure auto-charge trigger to prevent service interruption

### 4. Troubleshoot connectivity issues

1. **Verify endpoint**: Copy exact endpoint from console (includes auth token)
2. **Test with curl**: `curl -X POST ENDPOINT -H 'Content-Type: application/json' --data '{"method":"eth_blockNumber","jsonrpc":"2.0","params":[],"id":1}'`
3. **Check auth**: Confirm token/password is correct; 401 means auth failed
4. **Check rate limits**: 429 error means RPS or RU quota exceeded; reduce request rate or upgrade
5. **Check node status**: Console shows node status (Running, Pending, Failed); contact support if Failed
6. **Increase timeout**: 504 Gateway Timeout often means client timeout too short; increase to 30+ seconds
7. **Check request size**: 413 error means payload >1 MB; split large eth_getLogs into smaller ranges
8. **Verify network**: Confirm chain ID matches network (use `eth_chainId` to verify)

## Common gotchas

- **Auth token in URL is sensitive**: Treat endpoint URLs like passwords; never commit to git or expose in frontend code. Use environment variables.
- **Archive mode costs 2x RUs**: Querying historical blocks on Full mode fails silently or returns limited data; use Archive if you need past state.
- **RPS limits are per plan, not per node**: Multiple nodes on same plan share the RPS quota; upgrade plan if adding nodes.
- **WebSocket subscriptions count as requests**: Each `eth_subscribe` call and each event pushed counts toward RU quota.
- **Batch requests reduce RPS but not RU cost**: Batching 10 calls in one HTTP request counts as 10 RUs, not 1; use for throughput, not cost savings.
- **Warp transactions route through bloXroute**: `eth_sendRawTransaction` bypasses Chainstack and goes directly to bloXroute; other calls still use Chainstack.
- **Dedicated Node provisioning takes 3-6 minutes**: Global Node is instant; plan accordingly for production deployments.
- **Filter not found errors on Ethereum**: Filters expire after ~5 minutes of inactivity; recreate filter if needed.
- **Missing trie node errors**: Occur on Full nodes querying very old blocks; use Archive mode or Dedicated Node with full history.
- **Testnet faucets have rate limits**: Request tokens from https://faucet.chainstack.com; some networks have daily limits.

## Verification checklist

Before submitting work with Chainstack:

- [ ] Endpoint URL is correct and includes auth token (or basic auth credentials)
- [ ] Node status is "Running" (not Pending, Failed, or Stopped)
- [ ] Test RPC call succeeds (e.g., `eth_blockNumber` returns a valid block number)
- [ ] Auth method matches endpoint type (key-protected vs basic auth)
- [ ] Node mode (Full vs Archive) matches query requirements (historical data needs Archive)
- [ ] RPS and RU quotas are sufficient for expected traffic; extra usage enabled if needed
- [ ] Timeout is set to 30+ seconds for heavy operations (traces, wide eth_getLogs)
- [ ] Error handling includes retry logic for 429, 502, 503, 504 errors
- [ ] Sensitive credentials (tokens, passwords) are in environment variables, not hardcoded
- [ ] WebSocket subscriptions are properly unsubscribed to avoid connection leaks
- [ ] Billing threshold is configured to prevent service interruption
- [ ] Node is deployed in appropriate region for latency requirements

## Resources

- **Comprehensive navigation**: https://docs.chainstack.com/llms.txt (compact index) or https://docs.chainstack.com/llms-full.txt (full portal)
- **Platform introduction**: https://docs.chainstack.com/docs/platform-introduction
- **Node types and pricing**: https://docs.chainstack.com/docs/pricing-introduction
- **Supported networks**: https://docs.chainstack.com/docs/protocols-networks
- **Authentication methods**: https://docs.chainstack.com/docs/authentication-methods-for-different-scenarios
- **Platform API reference**: https://docs.chainstack.com/reference/platform-api-getting-started
- **Error reference**: https://docs.chainstack.com/docs/error-reference
- **Best practices**: https://docs.chainstack.com/docs/chainstack-web3-development-best-practices
- **Web3 libraries guide**: https://docs.chainstack.com/reference/web3-libraries

---

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