Endpoints & Authorization

Every Hgraph endpoint follows one URL structure, and a single API key authenticates across all of them — every network, every API.

Endpoint structure

https://{chain}[-{network}].hgraph.com/{path}

• {chain} — the chain name: ethereum, base, arbitrum, polygon, hedera, and more.
• {network} — omitted for mainnet, appended for every other network: base-sepolia, ethereum-hoodi, hedera-testnet.
• {path} — selects the API.

Path	API	Available on
/rpc	JSON-RPC	Every chain
/v1/graphql	GraphQL	Hedera
/beta/graphql	GraphQL	Ethereum (beta)
/api/v1/...	REST	Hedera
/mcp	MCP	mcp.hgraph.com — see the MCP server docs

For the full per-chain host list, see the JSON-RPC endpoints table.

---

Authentication

Every request needs an API key. Provide it by any of the three methods below — they work identically across GraphQL, REST, and JSON-RPC.

1. X-API-KEY header

X-API-KEY: <YOUR_API_KEY>

2. Authorization header

With or without the Bearer prefix:

Authorization: Bearer <YOUR_API_KEY>

Authorization: <YOUR_API_KEY>

3. Path-based

Insert /v1/<YOUR_API_KEY> ahead of the API path. Use this when your client can't set request headers — ethers.JsonRpcProvider, for example, takes a bare URL string.

API	Header auth	Path auth
JSON-RPC	https://ethereum.hgraph.com/rpc	https://ethereum.hgraph.com/v1/<KEY>/rpc
GraphQL	https://hedera.hgraph.com/v1/graphql	https://hedera.hgraph.com/v1/<KEY>/graphql
REST	https://hedera.hgraph.com/api/v1/accounts	https://hedera.hgraph.com/v1/<KEY>/api/v1/accounts

Include the full path after your key

Path-based auth replaces nothing — the API path still follows your key. Note that GraphQL uses /v1/<KEY>/graphql, not /v1/<KEY>/v1/graphql.

warning

Never expose your API key in a public repository or in frontend code. Store it in an environment variable.

---

GraphQL

https://hedera.hgraph.com/v1/graphql
https://hedera-testnet.hgraph.com/v1/graphql
https://ethereum.hgraph.com/beta/graphql

The fastest way to explore the schema is the GraphQL playground in the Hgraph App.

curl -s \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -d '{"query":"{ transaction(limit: 1, order_by: {consensus_timestamp: desc}) { consensus_timestamp } }"}' \
  https://hedera.hgraph.com/v1/graphql

{
  "data": {
    "transaction": [
      {
        "consensus_timestamp": "1738616017995472000"
      }
    ]
  }
}

Subscriptions use the same URL over WebSocket — see Subscriptions.

---

REST

Hedera mirror node REST endpoints are served under /api/v1.

curl -s \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  https://hedera.hgraph.com/api/v1/accounts

See the REST API overview for available resources.

---

JSON-RPC

Every chain serves Ethereum-compatible JSON-RPC at /rpc.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"eth_chainId","params":[]}' \
  https://base.hgraph.com/v1/<YOUR_API_KEY>/rpc

See the JSON-RPC overview for the full host list, supported methods, and library setup for ethers.js and viem.

---

Rate limits

Rate limits are enforced per API key, by your plan — one requests-per-second budget shared across all networks and all APIs, not a separate allowance per chain or endpoint. See Rate Limits & Quotas for each plan's limits.

---

Deprecated hosts

The former Hedera hosts still resolve and are not scheduled for removal, but new integrations should use hedera.hgraph.com:

Deprecated	Current
mainnet.hedera.api.hgraph.io, .dev	hedera.hgraph.com
testnet.hedera.api.hgraph.io, .dev	hedera-testnet.hgraph.com

Paths are unchanged, so migrating is a host swap. The .dev and .io domains no longer represent separate staging and production environments — hgraph.com is the only host, and non-mainnet networks are their own subdomains.

---

Obtaining an API key

Create an account to get a free API key. Production keys start with pk_prod_.

Review the plans for rate limits and features, or contact us about custom solutions.

Questions? Reach out to support.