---
name: Chainstack
description: Use when deploying blockchain nodes, managing RPC endpoints, querying blockchain data, building Web3 applications, or automating infrastructure with the Chainstack platform API. Agents should reach for this skill when users need to access blockchain networks, configure nodes, manage projects, or integrate blockchain data into applications.
metadata:
    mintlify-proj: chainstack
    version: "1.0"
---

# Chainstack Skill

## Product summary

Chainstack is a managed blockchain infrastructure platform supporting 70+ blockchain networks (Ethereum, Solana, Polygon, Bitcoin, TON, and others). Agents use Chainstack to deploy RPC nodes, access blockchain data via JSON-RPC APIs, manage infrastructure programmatically, and build Web3 applications.

**Key entry points:**
- **Console:** https://console.chainstack.com — deploy nodes, manage projects, view credentials
- **Platform API:** https://api.chainstack.com — v2 (recommended) and v1 endpoints for programmatic infrastructure management
- **RPC endpoints:** Each node provides HTTPS, WSS (WebSocket), or gRPC endpoints for blockchain queries
- **MCP server:** https://mcp.chainstack.com — AI agent integration for deployment, docs search, faucets, pricing
- **Docs:** https://docs.chainstack.com — comprehensive guides, API reference, tutorials

**Core files and config:**
- API keys: Created at console.chainstack.com/user/settings/api-keys (required for Platform API and MCP server)
- Node endpoints: Found in console under project > network > node name (HTTPS, WSS, or gRPC URLs with auth)
- Environment variables: Store API keys and endpoints securely (never commit to version control)

**CLI commands:** No native CLI; use curl, SDKs (web3.js, ethers.js, web3.py), or the MCP server for automation.

## When to use

Reach for this skill when:

- **Deploying nodes:** User wants to set up a blockchain node (Global, Unlimited, Trader, or Dedicated)
- **Querying blockchain data:** Building a dApp, indexing events, monitoring transactions, or analyzing on-chain data
- **Managing infrastructure:** Creating/updating/deleting projects, nodes, or networks programmatically
- **Accessing testnet faucets:** Requesting tokens for Sepolia, Hoodi, Base Sepolia, Amoy, Solana devnet, etc.
- **Optimizing costs:** Choosing between node types, understanding request unit (RU) billing, or monitoring usage
- **Integrating with AI:** Using the MCP server to deploy nodes or search docs from an AI agent
- **Troubleshooting:** Checking node sync status, latency, or error responses from RPC calls
- **Securing endpoints:** Setting up authentication (key-protected or password-protected URLs)

## Quick reference

### Node types and use cases

| Node Type | Deployment | Latency | Cost | Best for |
|-----------|-----------|---------|------|----------|
| **Global Node** | Instant (seconds) | Low (geo-routed) | Pay-per-RU | Production dApps, global users, high availability |
| **Unlimited Node** | 3–6 min | Medium | Flat monthly fee (RPS-tiered) | High-volume subscriptions, sustained WebSocket connections |
| **Trader Node** | 3–6 min | Low | Pay-per-RU | High-frequency trading, MEV protection, Warp transactions |
| **Dedicated Node** | 10–30 min | Lowest | Monthly + compute | Archive queries, debug/trace APIs, custom configs |

### Request unit (RU) billing

| Request Type | Cost | Notes |
|--------------|------|-------|
| Full request | 1 RU | Recent data (< 127 blocks old on EVM) |
| Archive request | 2 RUs | Historical data (≥ 127 blocks old on EVM) |
| Debug/trace methods | 2 RUs | Always 2 RUs: `debug_*`, `trace_*`, `eth_callMany` |
| WebSocket subscription | 1 RU setup + 1 RU per push | Each event/block notification counts as a request |

**Example:** `eth_getLogs` querying blocks from 1 month ago = archive (2 RUs). Same call on recent blocks = full (1 RU).

### Authentication methods

| Method | Format | Use case |
|--------|--------|----------|
| **Key-protected** | `https://nd-xxx.p2pify.com/YOUR_KEY` | Stateless, rotate easily, no password in logs |
| **Password-protected** | `https://user:pass@nd-xxx.p2pify.com` | Legacy, less secure, avoid in production |
| **gRPC x-token** | Metadata header `x-token: YOUR_TOKEN` | Sui, Solana, TON gRPC endpoints |

### Common RPC methods by protocol

| Protocol | Key Methods | Docs |
|----------|------------|------|
| **Ethereum** | `eth_blockNumber`, `eth_call`, `eth_getLogs`, `eth_sendRawTransaction`, `eth_subscribe` | `/reference/ethereum-getting-started` |
| **Solana** | `getBalance`, `getTransaction`, `getBlock`, `sendTransaction`, `logsSubscribe` | `/reference/solana-getting-started` |
| **Polygon** | Same as Ethereum (EVM-compatible) | `/reference/polygon-getting-started` |
| **Bitcoin** | `getblock`, `getrawtransaction`, `getblockchaininfo` | `/reference/bitcoin-api-reference` |
| **TON** | `getAddressInformation`, `getTransactions`, `runGetMethod` | `/reference/getting-started-ton` |

### Platform API v2 endpoints (recommended)

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/v2/deployment-options` | GET | List available blockchains, clouds, regions |
| `/v2/projects` | GET/POST | List or create projects |
| `/v2/projects/{id}` | GET/PATCH/DELETE | Manage a project |
| `/v2/nodes` | GET/POST | List or deploy nodes |
| `/v2/nodes/{id}` | GET/PATCH/DELETE | Manage a node |

**Authentication:** Add header `Authorization: Bearer YOUR_API_KEY`

## Decision guidance

### When to use Global Node vs Dedicated Node

| Scenario | Global Node | Dedicated Node |
|----------|-------------|----------------|
| Production dApp with global users | ✓ | — |
| Need archive data or debug APIs | — | ✓ |
| High-frequency trading (MEV protection) | ✓ | — |
| Custom client config or private deployment | — | ✓ |
| Budget-conscious, pay-per-request | ✓ | — |
| Sustained WebSocket subscriptions | — | ✓ (Unlimited better) |

### When to use HTTP vs WebSocket

| Use case | HTTP | WebSocket |
|----------|------|-----------|
| One-off queries (balance, block height) | ✓ | — |
| Real-time event monitoring | — | ✓ |
| Batch requests (multiple calls) | ✓ | — |
| Sustained subscriptions (24/7 listening) | — | ✓ (use Unlimited Node) |
| Low latency critical | — | ✓ |

### When to use full vs archive nodes

| Data | Full Node | Archive Node |
|------|-----------|--------------|
| Current balance, recent transactions | ✓ | ✓ |
| Historical state (1+ month old) | — | ✓ |
| Debug/trace calls | — | ✓ |
| Cost-sensitive queries | ✓ | — |

## Workflow

### 1. Deploy a node and get endpoints

1. **Sign up:** Go to https://console.chainstack.com/user/account/create
2. **Create a project:** Console > Projects > Create Project
3. **Add a network:** Click your project > Join Network > Select protocol (Ethereum, Solana, etc.) and network (Mainnet, Sepolia, etc.)
4. **Deploy a node:** Click Get Started > Select node type (Global, Unlimited, Trader, Dedicated) > Configure > Deploy
5. **Wait for sync:** Status changes from Pending to Running (Global: seconds, Dedicated: 10–30 min)
6. **Get credentials:** Click the node name > Copy HTTPS, WSS, or gRPC endpoint and auth token
7. **Store securely:** Add to `.env` file (never commit to git):
   ```
   ETHEREUM_RPC_URL=https://nd-xxx.p2pify.com/YOUR_KEY
   ETHEREUM_WSS_URL=wss://ws-nd-xxx.p2pify.com/YOUR_KEY
   ```

### 2. Query blockchain data

1. **Choose a library:** web3.js, ethers.js, web3.py, or curl
2. **Connect to endpoint:**
   ```javascript
   const ethers = require('ethers');
   const provider = new ethers.JsonRpcProvider(process.env.ETHEREUM_RPC_URL);
   ```
3. **Make a call:**
   ```javascript
   const balance = await provider.getBalance('0x...');
   const block = await provider.getBlock('latest');
   ```
4. **Monitor RUs:** Check console > node > Metrics to see request costs
5. **Optimize:** Use archive nodes only when needed; batch requests; cache results

### 3. Manage infrastructure programmatically

1. **Create an API key:** Console > Settings > API Keys > Create Key
2. **Store securely:** Add to `.env`:
   ```
   CHAINSTACK_API_KEY=your-key-here
   ```
3. **List projects:**
   ```bash
   curl -H "Authorization: Bearer $CHAINSTACK_API_KEY" \
     https://api.chainstack.com/v2/projects
   ```
4. **Deploy a node:**
   ```bash
   curl -X POST -H "Authorization: Bearer $CHAINSTACK_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"projectId":"...","protocol":"ethereum","network":"mainnet","nodeType":"global"}' \
     https://api.chainstack.com/v2/nodes
   ```
5. **Check status:** Poll `/v2/nodes/{id}` until `status` is `running`

### 4. Use the MCP server (AI agents)

1. **Install as a skill:**
   ```bash
   mkdir -p ~/.claude/skills/chainstack
   curl -o ~/.claude/skills/chainstack/SKILL.md https://mcp.chainstack.com/skill
   export CHAINSTACK_API_KEY="your-key"
   ```
2. **Or register as MCP server:** Add to agent config (Claude, Cursor, Windsurf, etc.)
3. **Use tools:**
   - `search_docs` — Find documentation
   - `get_deployment_options` — List blockchains/clouds
   - `create_node` — Deploy a node
   - `list_nodes` — Check node status
   - `request_testnet_funds` — Get faucet tokens

## Common gotchas

- **API key exposure:** Never commit `.env` files or API keys to git. Use `.gitignore` and rotate keys regularly.
- **Block age and RU cost:** Querying old blocks (> 127 blocks on EVM) costs 2 RUs, not 1. Check `eth_blockNumber` first to predict cost.
- **WebSocket subscription costs:** Each push notification counts as 1 RU. A 24/7 subscription can cost thousands of RUs/day. Use Unlimited Node for sustained subscriptions.
- **Node sync lag:** Global Nodes auto-failover if lagging > 40 blocks. Dedicated Nodes may lag during initial sync. Check node status before querying.
- **Authentication format:** Key-protected URLs use `/KEY` at the end; password-protected use `user:pass@`. Don't mix them.
- **gRPC vs HTTP:** Solana, Sui, TON support gRPC. Use `x-token` header, not URL auth. Different endpoint format.
- **Archive data limits:** Archive nodes have a retention window. Very old data (years) may not be available. Check protocol docs.
- **Rate limits:** Global Nodes have built-in load balancing. Dedicated Nodes may have RPS limits depending on tier. Monitor 429 errors.
- **Testnet faucets:** Sepolia, Hoodi, Base Sepolia, Amoy, BNB testnet, Solana devnet are available. Request via console or MCP server.
- **Deprecated methods:** Some protocols deprecate RPC methods. Check release notes and error responses for `method not found`.

## Verification checklist

Before submitting work:

- [ ] Node is in `running` state (check console or API)
- [ ] Endpoint URL is correct (HTTPS, WSS, or gRPC format)
- [ ] Authentication token/key is included and not expired
- [ ] RU cost is acceptable for the query (full vs archive)
- [ ] Error handling is in place (retry logic, fallback endpoints)
- [ ] Sensitive data (API keys, endpoints) is in `.env`, not hardcoded
- [ ] WebSocket subscriptions are closed properly (no resource leaks)
- [ ] Request is tested on testnet before mainnet
- [ ] Metrics show expected request volume (no unexpected spikes)
- [ ] Node latency is acceptable (< 1s for most queries)

## Resources

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

**Critical docs:**
1. [Platform introduction](https://docs.chainstack.com/docs/platform-introduction) — Overview of Chainstack, node types, regions
2. [Ethereum API reference](https://docs.chainstack.com/reference/ethereum-getting-started) — JSON-RPC methods, Beacon Chain API, examples
3. [Platform API v2](https://docs.chainstack.com/reference/platform-api-getting-started) — Programmatic node and project management
4. [Request units](https://docs.chainstack.com/docs/request-units) — RU billing rules, full vs archive, per-protocol thresholds
5. [Best practices handbook](https://docs.chainstack.com/docs/chainstack-web3-development-best-practices) — Error handling, load balancing, WebSocket, security
6. [Chainstack MCP server](https://docs.chainstack.com/docs/chainstack-mcp-server) — AI agent integration, tool reference, setup

---

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