API integration

Use this reference to configure endpoints, shape requests, match batch responses, and handle errors. GraphOps RPC exposes Ethereum-compatible JSON-RPC over HTTPS and WebSocket, plus Bitcoin JSON-RPC over HTTPS. For individual methods, see Supported methods.

Endpoint patterns

https://rpc.graphops.xyz/v1/evm/<chainId>
wss://rpc.graphops.xyz/v1/evm/<chainId>

Use the concrete URL for your target chain in application configuration or client setup.

See Supported networks for current query endpoints and archive coverage.

Bitcoin endpoints

Bitcoin RPC uses HTTPS and a network name instead of an EVM chain ID. The endpoint route is:

/v1/bitcoin/<network>[/API_KEY]

For example, an authenticated Bitcoin mainnet request looks like this:

curl "https://rpc.graphops.xyz/v1/bitcoin/mainnet" \
  -H "Authorization: Bearer <GRAPHOPS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getblockchaininfo",
    "params": []
  }'

Clients that cannot attach headers can use the route-token form instead:

https://rpc.graphops.xyz/v1/bitcoin/mainnet/<GRAPHOPS_API_KEY>

Authentication

Authenticate with an organization-scoped API key. RPC supports header authentication and route-token authentication. See Authentication for key creation, rotation, WebSocket connections, and secret handling.

Request envelope

Every EVM and Bitcoin JSON-RPC call uses the standard request envelope. Method names and parameter formats are network-specific; the examples in this section use EVM methods.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_blockNumber",
  "params": []
}

HTTPS requests

HTTPS requests use POST with Content-Type: application/json. The examples below use Ethereum mainnet.

curl "https://rpc.graphops.xyz/v1/evm/1" \
  -H "Authorization: Bearer <GRAPHOPS_API_KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  }'

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

const client = createPublicClient({
  chain: mainnet,
  transport: http("https://rpc.graphops.xyz/v1/evm/1", {
    fetchOptions: {
      headers: {
        Authorization: "Bearer <GRAPHOPS_API_KEY>",
      },
    },
  }),
});

const blockNumber = await client.getBlockNumber();
console.log(blockNumber);

import { ethers } from "ethers";

const request = new ethers.FetchRequest("https://rpc.graphops.xyz/v1/evm/1");
request.setHeader("Authorization", "Bearer <GRAPHOPS_API_KEY>");

const provider = new ethers.JsonRpcProvider(request);
const blockNumber = await provider.getBlockNumber();

console.log(blockNumber);

from web3 import Web3

w3 = Web3(
    Web3.HTTPProvider(
        "https://rpc.graphops.xyz/v1/evm/1",
        request_kwargs={
            "headers": {
                "Authorization": "Bearer <GRAPHOPS_API_KEY>",
            },
        },
    )
)

print(w3.eth.block_number)

Batch requests

Batch requests are supported. Use them when several independent calls can share one HTTP round trip. Do not use a batch when later calls depend on earlier results.

[
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_blockNumber",
    "params": []
  },
  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "eth_chainId",
    "params": []
  },
  {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "eth_getBalance",
    "params": ["0xnot-an-address", "latest"]
  }
]

The third call has an invalid address, so only that item fails:

[  { "jsonrpc": "2.0", "id": 2, "result": "0x1" },eth_chainId: Ethereum mainnet  { "jsonrpc": "2.0", "id": 1, "result": "0x112a880" },eth_blockNumber, after id 2  {    "jsonrpc": "2.0",    "id": 3,Only this call failed    "error": { "code": -32602, "message": "invalid argument 0" }Invalid params; a retry fails again  }]

Match responses by id; do not rely on response ordering. Retry only the failed items that are retryable, as a smaller batch or as single requests.

WebSocket connections

Use WebSocket endpoints for subscriptions and long-lived event streams. Route-token authentication works with WebSocket clients that cannot attach custom headers during the handshake.

import WebSocket from "ws";

const socket = new WebSocket(
  "wss://rpc.graphops.xyz/v1/evm/1/<GRAPHOPS_API_KEY>",
);

See Authentication for header authentication, route-token authentication, and security guidance.

WebSocket subscriptions

GraphOps supports standard Ethereum subscription flows over WebSocket:

Persist the last processed block or log cursor in your application. If a WebSocket disconnects, use WebSocket subscriptions for recovery patterns.

Error responses

JSON-RPC errors use the standard error object in place of result:

{  "jsonrpc": "2.0",  "id": 1,The call that failed  "error": {Present instead of result    "code": -32602,Invalid params; see the table below    "message": "invalid argument 0"Points at the first parameter  }}

Common error classes:

Next steps