HookOS RPC

§01What HookOS RPC is

HookOS RPC is a key-gated, rate-limited JSON-RPC gateway for EVM chains. Every request is authenticated against an API key you create in the dashboard, routed to a HookOS-operated node, and served with shared, reorg-aware caching.

What makes it different:

• Self-hosted nodes, data sovereignty. Requests are served by nodes HookOS runs on its own hardware — not resold third-party infrastructure. Your traffic and access patterns stay inside HookOS's control plane.
• Multi-chain from one surface. One base URL, one key format; you select the chain with a numeric chain id in the path.
• Flat, predictable pricing. Fixed monthly tiers with a request-rate ceiling per tier (see Rate limits & tiers). No per-request surprises inside your tier's ceiling.
• Safe method surface. Node-admin, signing, and debug namespaces are blocked at the gateway (see Method support & restrictions).

§02Getting an API key

1. Go to app.hookos.cloud and sign in.
2. Open API Keys.
3. Click Create key.
4. Copy the key immediately — it is shown once. It is not retrievable later; if you lose it, delete the key and create a new one.

Keys look like hk_live_…. Treat a key as a secret: it grants billed access to your account. Prefer server-side use and the header form of auth (below) so the key never lands in URLs, browser history, or proxy logs.

You can create multiple keys, disable a key instantly, or move a key between tiers from the dashboard. A tier or enable/disable change can take up to ~30 seconds to take effect at the gateway (validated keys are briefly cached).

§03Endpoint & authentication

Endpoint format

https://rpc.hookos.cloud/public/evm/<chainId>

• public is the fixed project id — it is a literal path segment, not your key. Every customer request uses public.
• <chainId> is the numeric chain id of the target chain, e.g. Base = 8453.

Example (Base): https://rpc.hookos.cloud/public/evm/8453

All calls are standard JSON-RPC 2.0 over HTTP POST with Content-Type: application/json.

Authentication

Send your API key one of two ways. The header form is preferred — it keeps the key out of URLs and server logs.

Both forms authenticate against the same key store. Do not put the key in the URL path — the path segment is the project id (public), and a key placed there will 404.

§04Supported chains

Only chains marked Live are callable today. "Coming soon" chains are planned and appear in the dashboard, but do not yet have a deployed node — calling them will not return chain data.

§05Rate limits & tiers

Each API key is assigned a tier. The tier sets a per-key requests-per-second (RPS) ceiling, enforced at the gateway across all gateway replicas (the counter is shared, so the limit is global, not per-connection). Exceeding it returns HTTP 429.

Notes:

• The RPS ceiling is per key, counted per second. Bursting above it trips 429 for the requests over the limit; retry with backoff.
• Tiers also differ on monthly usage allowances, key/project counts, and access to heavier method classes (e.g. archive/trace) — see the dashboard for the current plan matrix. Archive/trace method availability is on the roadmap and not guaranteed on the live service today (see §07).
• If your workload needs a higher sustained rate than Business, contact us about Enterprise.

§06Code examples

All examples target Base (chainId 8453) using the preferred header auth. Replace hk_live_xxx with your key.

curl

eth_blockNumber (latest block height):

curl -s -X POST 'https://rpc.hookos.cloud/public/evm/8453' \
  -H 'content-type: application/json' \
  -H 'X-ERPC-Secret-Token: hk_live_xxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

eth_getBalance:

curl -s -X POST 'https://rpc.hookos.cloud/public/evm/8453' \
  -H 'content-type: application/json' \
  -H 'X-ERPC-Secret-Token: hk_live_xxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBalance","params":["0x4200000000000000000000000000000000000006","latest"]}'

eth_call (read a contract — here symbol() on WETH, selector 0x95d89b41):

curl -s -X POST 'https://rpc.hookos.cloud/public/evm/8453' \
  -H 'content-type: application/json' \
  -H 'X-ERPC-Secret-Token: hk_live_xxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_call","params":[{"to":"0x4200000000000000000000000000000000000006","data":"0x95d89b41"},"latest"]}'

eth_getLogs (bounded block range — always cap the range):

curl -s -X POST 'https://rpc.hookos.cloud/public/evm/8453' \
  -H 'content-type: application/json' \
  -H 'X-ERPC-Secret-Token: hk_live_xxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs","params":[{"fromBlock":"0x1500000","toBlock":"0x1500064","address":"0x4200000000000000000000000000000000000006"}]}'

ethers v6 (JavaScript / TypeScript)

Set the auth header on the transport with FetchRequest:

import { ethers, FetchRequest } from "ethers";

const req = new FetchRequest("https://rpc.hookos.cloud/public/evm/8453");
req.setHeader("X-ERPC-Secret-Token", "hk_live_xxx");

const provider = new ethers.JsonRpcProvider(req, 8453, { staticNetwork: true });

const block = await provider.getBlockNumber();
const balance = await provider.getBalance(
  "0x4200000000000000000000000000000000000006"
);

console.log(block, ethers.formatEther(balance));

viem (JavaScript / TypeScript)

Pass the header via the transport's fetchOptions:

import { createPublicClient, http } from "viem";
import { base } from "viem/chains";

const client = createPublicClient({
  chain: base,
  transport: http("https://rpc.hookos.cloud/public/evm/8453", {
    fetchOptions: {
      headers: { "X-ERPC-Secret-Token": "hk_live_xxx" },
    },
  }),
});

const block = await client.getBlockNumber();
const balance = await client.getBalance({
  address: "0x4200000000000000000000000000000000000006",
});

console.log(block, balance);

web3.py (Python)

from web3 import Web3

w3 = Web3(Web3.HTTPProvider(
    "https://rpc.hookos.cloud/public/evm/8453",
    request_kwargs={"headers": {"X-ERPC-Secret-Token": "hk_live_xxx"}},
))

print(w3.eth.block_number)
print(w3.eth.get_balance("0x4200000000000000000000000000000000000006"))

web3.js (JavaScript / TypeScript)

web3.js v4 accepts custom headers on the HTTP provider config:

import { Web3 } from "web3";

const web3 = new Web3(
  new Web3.providers.HttpProvider("https://rpc.hookos.cloud/public/evm/8453", {
    providerOptions: {
      headers: { "X-ERPC-Secret-Token": "hk_live_xxx" },
    },
  })
);

console.log(await web3.eth.getBlockNumber());
console.log(
  await web3.eth.getBalance("0x4200000000000000000000000000000000000006")
);

§07Method support & restrictions

HookOS RPC serves the standard EVM read and transaction-submission methods (eth_*, net_*, web3_*), including eth_call, eth_getLogs, eth_getBalance, eth_sendRawTransaction, and the block/transaction/receipt getters.

Denied at the gateway. The following namespaces are blocked on every upstream and will not be served — they cover node administration, signing, and debug/internal surfaces that must never be exposed to customers:

Calling a denied method returns a JSON-RPC error rather than node data.

Archive & trace. Archive-grade state and trace_* / debug_* tracing are on the roadmap and are not guaranteed on the live service today (debug_* and trace_* are currently in the deny list above). Do not build against them yet; watch the dashboard for availability and tier gating.

§08Errors

HTTP-level

JSON-RPC errors

Successful HTTP requests can still return a standard JSON-RPC 2.0 error object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32600, "message": "..." }
}

Common cases: -32700 parse error, -32600 invalid request, -32601 method not found (including denied namespaces), -32602 invalid params, -32603 internal error, and -32000-range server errors (e.g. execution reverted, timeout). Always check for an error field even on HTTP 200.

§09Best practices

• Use header auth (X-ERPC-Secret-Token) and keep keys server-side.
• Rotate keys you suspect are exposed — disable/recreate from the dashboard.
• Handle 429 with backoff (exponential + jitter); stay under your tier RPS.
• Bound eth_getLogs ranges and paginate large scans.
• Cache-friendly by design: finalized data is cached indefinitely at the gateway, so repeated historical reads are cheap; head/realtime data has a short TTL and reflects reorgs.

§10Links

• Dashboard / keys: app.hookos.cloud
• RPC base URL: https://rpc.hookos.cloud
• Support / updates: @hookosfun