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 --fail-with-body --silent --show-error "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": []
}

{  "jsonrpc": "2.0",JSON-RPC version  "id": 1,Matches the id you sent  "result": "0x1908d5f"Latest block in decimal: 26,250,591}

HTTPS requests

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

curl --fail-with-body --silent --show-error "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": []
  }'

{  "jsonrpc": "2.0",JSON-RPC version  "id": 1,Matches the id you sent  "result": "0x1908d5f"Latest block in decimal: 26,250,591}

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"]
  }
]

[  {    "jsonrpc": "2.0",    "id": 1,    "result": "0x1908d62"eth_blockNumber in decimal: 26,250,594  },  {    "jsonrpc": "2.0",    "id": 2,    "result": "0x1"Ethereum mainnet chain ID: 1  },  {    "jsonrpc": "2.0",    "id": 3,    "error": {      "code": -32602,Only this call failed: invalid parameters      "message": "Invalid params",      "data": "invalid string length at line 1 column 18"    }  }]

In the output, the third call fails because its address is invalid; the other two succeed.

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";

// Route-token URL: the API key is the final path segment.
const socket = new WebSocket(
  `wss://rpc.graphops.xyz/v1/evm/1/${process.env.GRAPHOPS_API_KEY}`,
);

socket.once("error", (error) => { throw error; });
socket.once("open", () => {
  console.log(JSON.stringify({ connected: true }));
  socket.close();
});

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,
  "method": "eth_getBalance",
  "params": [
    "invalid-address",
    "latest"
  ]
}

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

Common error classes:

Next steps