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 patternsCopy Anchor Link

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

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 endpointsCopy Anchor Link

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

https://rpc.graphops.xyz/v1/bitcoin/<NETWORK>

For example, this request reads Bitcoin mainnet chain information. EVM client libraries do not support Bitcoin JSON-RPC, so the programs use an HTTP client:

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 envelopeCopy Anchor Link

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": "0x191161d"Latest block in decimal: 26,285,597}

HTTPS requestsCopy Anchor Link

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": "0x191161d"Latest block in decimal: 26,285,597}

Batch requestsCopy Anchor Link

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": "0x191f63a"eth_blockNumber in decimal: 26,342,970  },  {    "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"    }  }]

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 connectionsCopy Anchor Link

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 subscriptionsCopy Anchor Link

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 responsesCopy Anchor Link

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. GraphOps error responses carry a code; look it up in the gateway errors or API key errors reference.

Next stepsCopy Anchor Link