Overview
Establish transport, authentication, chain identity, response shape, and tip movement with raw JSON-RPC before adding an SDK. This keeps the first proof deterministic and prevents a client-library configuration error from looking like an endpoint outage.
Prerequisites
- A secret reference for the QuickNode endpoint and token
- The expected chain, network, protocol, and chain identifier
- A non-sensitive read method supported by that chain
Instructions
Step 1: Inspect the integration
Use Read and Grep to find the endpoint variable, expected chain ID, timeout, and current client wrapper. Stop if source or logs contain a literal QuickNode token.
Step 2: Define the probe
Use Write or Edit to create a small fixture containing only JSON-RPC version, a read method, empty parameters when valid, and a stable request ID. For EVM, pair eth_chainId with eth_blockNumber; do not submit a transaction.
Step 3: Call through the secret boundary
Use Bash(curl:*) with a timeout, JSON content type, and the endpoint injected by the runtime. Suppress verbose output because the URL may contain a token.
curl --silent --show-error --max-time 10 \
--header 'content-type: application/json' \
--data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
"$QUICKNODE_ENDPOINT"
Step 4: Validate semantics
Require HTTP success, matching JSON-RPC id, exactly one of result or error, and the expected chain ID. Parse hexadecimal block numbers explicitly rather than comparing their strings.
Step 5: Prove liveness
Read the latest block twice with a chain-appropriate interval. Tip movement is useful evidence but is not universal during quiet or halted networks, so compare against the chain status before declaring failure.
Step 6: Capture a safe receipt
Record timestamp, chain, network, method, latency, HTTP status, JSON-RPC error code if any, and redacted endpoint identity. Never retain the endpoint URL.
Tool Discipline
Use Read and Grep for configuration discovery, Write and Edit for a non-secret probe fixture, and Bash(curl:*) for bounded reads. Do not use this workflow for writes, signing, or funded keys.
Output
- Endpoint contract and expected chain identity
- Redacted transport and JSON-RPC receipt
- Liveness result with chain-status context
- Clear owner for any failed layer
Examples
An Ethereum mainnet endpoint returns chain ID 0x1 and a valid block number. A response from a testnet is rejected even though transport and authentication succeeded.
Error Handling
| Failure | Response |
|---|---|
| HTTP 401 or 403 | Check token type, security filters, and secret injection |
| JSON-RPC error | Preserve code and message after redaction; do not flatten it to HTTP |
| Wrong chain ID | Stop deployment and correct endpoint selection |
| Timeout | Compare provider status and a second bounded read before escalation |