---
name: Chainstack
description: Use when deploying blockchain RPC nodes, managing node infrastructure, configuring API endpoints, monitoring node usage, implementing authentication and access controls, choosing between node types (Global, Dedicated, Trader, Unlimited), understanding request unit billing, and troubleshooting blockchain API errors.
metadata:
    mintlify-proj: chainstack
    version: "1.0"
---

# Chainstack Skill

## Product summary

Chainstack is a managed blockchain infrastructure platform supporting 70+ networks with RPC nodes, APIs, and self-hosted deployment options. Agents use Chainstack to deploy and manage blockchain nodes, configure endpoints for dApps and services, monitor usage metrics, implement security controls, and handle billing across multiple subscription tiers. The platform exposes nodes via HTTPS, WebSocket (WSS), and gRPC endpoints. Key files: console at https://console.chainstack.com, API reference at https://docs.chainstack.com/reference, platform API for programmatic management. CLI commands are not primary; the platform is console-driven or API-driven.

## When to use

Reach for this skill when:
- **Deploying nodes** — user needs a blockchain RPC endpoint for a specific network (Ethereum, Solana, Polygon, etc.)
- **Choosing node types** — deciding between Global Node (default, per-request billing), Dedicated Node (exclusive compute, monthly billing), Trader Node (regional, low-latency), or Unlimited Node add-on (flat-fee, RPS-capped)
- **Configuring endpoints** — setting up authentication (key-protected or password-protected), access rules (IP allowlist, origin allowlist), and WebSocket subscriptions
- **Managing billing** — understanding request units (RUs), quotas, plan limits, and when to upgrade or add the Unlimited Node add-on
- **Monitoring usage** — viewing request metrics, method call breakdowns, response codes, and organization-wide statistics
- **Troubleshooting errors** — interpreting HTTP status codes (401, 429, 504), JSON-RPC error codes (-32000, -32601), and WebSocket close codes (1006)
- **Implementing security** — configuring access rules, managing API keys, and using authentication methods for different scenarios
- **Real-time data** — setting up WebSocket subscriptions for logs, new blocks, pending transactions, or using Geyser plugins for Solana

## Quick reference

### Node types and billing

| Node Type | Distribution | Billing | Best for |
|-----------|--------------|---------|----------|
| **Global Node** | Geo-distributed | Per request (RUs) | Default choice, variable load, global reach |
| **Dedicated Node** | Geo-specific | Monthly compute + storage | Sustained heavy load, custom configs, debug/trace APIs |
| **Trader Node** | Regional | Per request (RUs) | Latency-critical, Warp transactions, regional workloads |
| **Unlimited Node** (add-on) | Any node | Flat monthly fee (RPS tier) | Predictable costs, steady high traffic, subscriptions |

### Request unit (RU) costs

- **Full request**: 1 RU (recent blocks, within 127 blocks of tip)
- **Archive request**: 2 RUs (historical blocks, 127+ blocks behind tip)
- **Debug/trace methods**: Always 2 RUs (e.g., `debug_traceTransaction`, `trace_block`)
- **WebSocket subscriptions**: 1 RU to subscribe + 1 RU per push notification

### Endpoint formats

```
HTTPS (key-protected):
https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d

HTTPS (password-protected):
https://user-name:password@nd-123-456-789.p2pify.com

WebSocket (key-protected):
wss://ws-nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d

gRPC (Solana, Sui, etc.):
sui-mainnet.core.chainstack.com:443
(with x-token in request metadata)
```

### HTTP error codes and fixes

| Code | Cause | Fix |
|------|-------|-----|
| 400 | Malformed JSON/RPC envelope | Validate JSON structure and JSON-RPC format |
| 401 | Wrong endpoint key or password | Verify credentials in console node details |
| 404 | Endpoint path doesn't exist | Check URL; contact support if correct |
| 413 | Request body > 1 MB | Paginate `eth_getLogs`, batch fewer calls |
| 429 | Rate limit hit (RPS or connection) | Upgrade plan, use Unlimited Node, or implement backoff |
| 499 | Client closed connection | Increase client-side timeout |
| 500 | Server error | Retry with exponential backoff |
| 502 | Node unreachable | Retry; contact support if persistent |
| 503 | Node under resource pressure | Retry with backoff; consider Dedicated Node |
| 504 | Gateway timeout | Paginate heavy methods; move to Dedicated Node |

### JSON-RPC error codes

| Code | Meaning | Action |
|------|---------|--------|
| -32700 | Parse error | Validate JSON syntax |
| -32600 | Invalid Request | Check `jsonrpc`, `method`, `id` fields |
| -32601 | Method not found | Verify method is enabled; check debug/trace APIs |
| -32602 | Invalid params | Check parameter types and values |
| -32603 | Internal error | Wraps a `-32000` error; check message |
| -32000 | Server error (node-specific) | Read message for details (e.g., "missing trie node", "nonce too low") |
| -32612 | Custom tracers disabled | Use Dedicated Node for custom JavaScript tracers |

## Decision guidance

### When to use Global Node vs Dedicated Node

| Scenario | Use Global Node | Use Dedicated Node |
|----------|-----------------|-------------------|
| Variable or unpredictable traffic | ✓ | |
| Sustained high throughput (heavy subscriptions, traces) | | ✓ |
| Need debug/trace APIs | | ✓ (always enabled) |
| Cost-sensitive, low-to-medium traffic | ✓ | |
| Custom node configuration required | | ✓ |
| Compliance or data isolation needed | | ✓ |
| Global geographic distribution required | ✓ | |

### When to use Unlimited Node add-on

| Scenario | Use per-request billing | Use Unlimited Node |
|----------|------------------------|-------------------|
| Unpredictable request volume | ✓ | |
| Sustained subscriptions (eth_subscribe logs, newHeads) | | ✓ |
| Predictable, steady high traffic | | ✓ |
| Occasional spikes acceptable | ✓ | |
| Want flat monthly cost | | ✓ |
| RPS tier (25–1000) matches your needs | | ✓ |

### Full vs Archive request classification (EVM)

| Scenario | Classification | Cost |
|----------|----------------|------|
| Query recent block (within 127 blocks of tip) | Full | 1 RU |
| Query historical block (127+ behind tip) | Archive | 2 RU |
| `eth_getLogs` with `fromBlock` far in past | Archive | 2 RU |
| `debug_traceTransaction` any block | Always archive | 2 RU |
| `eth_call` on recent block | Full | 1 RU |
| `eth_call` on historical block | Archive | 2 RU |

## Workflow

### 1. Deploy a node

1. **Log in** to https://console.chainstack.com
2. **Create or select a project** (Projects > Create Project if new)
3. **Click Get Started** (new project) or **Join Network** (existing project)
4. **Choose protocol and network** (Ethereum Mainnet, Solana Mainnet, etc.)
5. **Select node type**:
   - Global Node (default, per-request)
   - Dedicated Node (exclusive, monthly)
   - Trader Node (regional, low-latency)
6. **Pick node mode**: Full (recent data) or Archive (all historical data)
7. **Choose cloud provider** (AWS, GCP, Azure, etc.)
8. **Name the node** and review monthly cost
9. **Click Deploy** — wait for email notification when ready

### 2. Access your node

1. **In console**, navigate to Project > Network > Node name
2. **Copy endpoint credentials**:
   - HTTPS endpoint (key or password protected)
   - WebSocket endpoint (for subscriptions)
   - gRPC endpoint (if available for protocol)
3. **Store credentials securely** (environment variables, secrets manager)
4. **Test connectivity** with a simple RPC call (e.g., `eth_blockNumber`)

### 3. Configure security

1. **Set authentication**:
   - Key-protected: token in URL path
   - Password-protected: username:password in URL
2. **Add access rules** (if Global Node):
   - IP allowlist: restrict to backend IPs
   - Origin allowlist: restrict to dApp domain
3. **Rotate credentials** periodically via console

### 4. Monitor usage

1. **In console**, go to Project > Network > Node > Metrics
2. **View charts**:
   - Requests made (HTTP + WebSocket over time)
   - Method calls breakdown (HTTP only)
   - Response codes (HTTP only)
3. **Download aggregate data** via hamburger menu
4. **Check organization-wide stats** in Statistics section
5. **Set up billing alerts** to track quota usage

### 5. Troubleshoot errors

1. **Identify error type**:
   - HTTP status code (400–504) → check request/server
   - JSON-RPC error code (-32000 to -32700) → check method/params
   - WebSocket close code (1006) → reconnect
2. **For 401 errors**: Verify endpoint key/password in console
3. **For 429 errors**: Check RPS limits; consider Unlimited Node
4. **For 504 errors**: Paginate `eth_getLogs`; move to Dedicated Node
5. **For -32000 errors**: Read message (e.g., "missing trie node" = use archive node)
6. **Contact support** if error persists after retry

## Common gotchas

- **Archive vs Full confusion**: A request to a block 127+ blocks behind the tip is archive (2 RUs), even if you don't explicitly ask for archive. Check `eth_blockNumber` to determine the tip.
- **WebSocket subscription costs**: Each push notification counts as 1 RU. A subscription to `eth_subscribe logs` on a busy contract can cost thousands of RUs/day. Use Unlimited Node for sustained subscriptions.
- **Request body size limit**: Default 1 MB cap. Paginate `eth_getLogs` ranges or batch fewer JSON-RPC calls per request.
- **Filter not found errors**: WebSocket filters expire after idle timeout. Implement automatic reconnect logic.
- **Missing trie node on full node**: Querying historical state on a full node fails. Use an archive node or Dedicated Node with archive mode.
- **Nonce too low**: Transaction nonce already mined. Always fetch the latest nonce with `eth_getTransactionCount(address, "latest")`.
- **Rate limit (429)**: Hit RPS limit or connection limit. Implement exponential backoff; upgrade plan or use Unlimited Node.
- **Timeout (504)**: Heavy methods like `debug_traceTransaction` or wide-range `eth_getLogs` can exceed gateway timeout. Paginate or move to Dedicated Node.
- **Wrong endpoint for protocol**: Solana has no chain ID; point to cluster (mainnet/devnet). TON uses v2/v3 REST or JSON-RPC envelope. Check protocol-specific docs.
- **gRPC authentication**: Uses `x-token` in request metadata, not URL-based auth like HTTPS.

## Verification checklist

Before submitting work with Chainstack:

- [ ] **Node deployed and running** — status shows "Running" in console, not "Pending"
- [ ] **Endpoint credentials copied** — HTTPS/WSS/gRPC endpoint and auth token/password stored
- [ ] **Connectivity tested** — simple RPC call (e.g., `eth_blockNumber`) returns success
- [ ] **Node type matches workload** — Global for variable load, Dedicated for sustained high throughput, Trader for low-latency
- [ ] **Node mode correct** — Full for recent data, Archive for historical queries
- [ ] **Access rules configured** — IP/origin allowlist set if needed
- [ ] **Billing understood** — RU cost per request calculated; quota limits checked
- [ ] **Error handling in place** — retry logic with backoff for 5xx errors, timeout handling for 504
- [ ] **WebSocket reconnect logic** — automatic reconnect on close code 1006
- [ ] **Credentials secured** — stored in environment variables or secrets manager, not hardcoded

## Resources

**Comprehensive navigation**: https://docs.chainstack.com/llms.txt — page-by-page listing of all documentation.

**Critical pages**:
1. [Platform Introduction](https://docs.chainstack.com/docs/platform-introduction) — overview of Chainstack, supported networks, regions, and faucets
2. [Manage Your Node](https://docs.chainstack.com/docs/manage-your-node) — view credentials, monitor metrics, manage node lifecycle
3. [Request Units](https://docs.chainstack.com/docs/request-units) — billing model, full vs archive classification by protocol, WebSocket subscription costs
4. [Error Reference](https://docs.chainstack.com/docs/error-reference) — HTTP, JSON-RPC, and WebSocket error codes with fixes
5. [Dedicated Node](https://docs.chainstack.com/docs/dedicated-node) — exclusive compute, debug/trace APIs, monthly billing
6. [Global Node](https://docs.chainstack.com/docs/global-elastic-node) — load-balanced, geo-distributed, per-request billing
7. [Access Rules](https://docs.chainstack.com/docs/access-rules) — IP and origin allowlists for endpoint security
8. [Best Practices for Securing Your Endpoint](https://docs.chainstack.com/docs/best-practices-for-securing-your-chainstack-endpoint) — authentication, access rules, rate limiting
9. [Platform API Getting Started](https://docs.chainstack.com/reference/platform-api-getting-started) — programmatic node management
10. [Limits](https://docs.chainstack.com/docs/limits) — RPS limits, custom tracer availability, archive method availability by protocol

---

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