DOCSEARCHbyAlgolia
Submit Docs

Hgraph Documentation

website·Indexed 32 days ago

https://docs.hgraph.com

Documentation for Hgraph, providing REST and GraphQL API endpoints for accessing indexed Hedera mirror node blockchain data. Includes guides on authentication, endpoint structure, and managing organizations, projects, and API keys via the Hgraph App.

Tokens
2K
Snippets
10
Records
20
Agent score
59%

What's inside Hgraph

  1. Authenticate Hgraph API requests

    Every request requires an API key. You can provide the key using one of three identical methods across GraphQL, REST, and JSON-RPC APIs. For security, store keys in environment variables and never expose them in frontend code or public repositories.

    1. X-API-KEY Header

    X-API-KEY: <YOUR_API_KEY>

    2. Authorization Header

    Authorization: Bearer <YOUR_API_KEY>

    OR

    Authorization: <YOUR_API_KEY>

    3. Path-based Authentication

    Insert /v1/<YOUR_API_KEY> before the API path. This is useful for clients that cannot set headers (e.g., ethers.JsonRpcProvider).

    APIHeader URLPath-based URL
    JSON-RPChttps://ethereum.hgraph.com/rpchttps://ethereum.hgraph.com/v1/<KEY>/rpc
    GraphQLhttps://hedera.hgraph.com/v1/graphqlhttps://hedera.hgraph.com/v1/<KEY>/graphql
    RESThttps://hedera.hgraph.com/api/v1/accountshttps://hedera.hgraph.com/v1/<KEY>/api/v1/accounts

  2. Create an Hgraph account

    To create an account, visit app.hgraph.com and sign in using one of three passwordless methods: GitHub, Google, or Email (via a magic link). If it is your first time signing in, an account is created automatically.

  3. Create and manage Hgraph organizations

    Organizations serve as the top-level container for projects, API keys, teams, and members. To create one:

    1. Click Create Organization in the Hgraph App.
    2. Provide a name and a URL slug.
    3. Click Create.

  4. Choose between REST and GraphQL APIs

    Both APIs read the same indexed data, but serve different use cases:

    • Use REST for fast lookups of well-known records (accounts, transactions, tokens) where the standard response contains all required fields. It is the standard for most existing Hedera tooling.
    • Use GraphQL for complex queries requiring specific fields, relational data (traversing related records in one trip), live updates via subscriptions, or access to specialized tables like the ERC indexer, DEX, lending, and oracle schemas.

  5. Access the Hgraph REST API

    Hgraph provides a hosted version of the Hedera mirror node REST API. Because it follows the upstream mirror node specification, any code written for a public mirror node is compatible with Hgraph by swapping the host URL and adding an API key for authentication. Hgraph currently serves mirror node REST v0.163.1.
    curl -s -H "X-API-KEY: <YOUR_API_KEY>" \
  https://hedera.hgraph.com/api/v1/accounts/0.0.800

  6. Access specialized ERC-20 and ERC-721 token data

    For comprehensive data regarding pure ERC token contracts (ERC-20 and ERC-721) on Hedera, Hgraph provides a dedicated section with specialized queries and schemas specifically designed for ERC token data.

  7. Migrate from deprecated Hedera hosts

    Old .io and .dev domains are deprecated. New integrations should use hgraph.com. This is a host-only swap; API paths remain unchanged.
    DeprecatedCurrent
    mainnet.hedera.api.hgraph.io, .devhedera.hgraph.com
    testnet.hedera.api.hgraph.io, .devhedera-testnet.hgraph.com

  8. Obtain an Hgraph API key

    API keys can be generated by creating an account at app.hgraph.com. Production keys are prefixed with pk_prod_. You can use a direct link to prefill the key creation form for specific projects and networks.

    Key Creation Link

    https://app.hgraph.com/keys/new?name=<project>&network=<mainnet|testnet>

    Example .env Setup

    HEDERA_MIRROR_URL=https://hedera-testnet.hgraph.com/api/v1
HGRAPH_API_KEY=<your key>

  9. Create and organize Hgraph projects

    Projects are contained within organizations and allow for the separation of environments (e.g., production, staging, development) through independent API keys and usage tracking.

    To create a project:

    1. Navigate to Projects in the sidebar.
    2. Click Create Project.
    3. Enter a name, URL slug, and an optional description.
    4. Click Create.

    Note: The free tier includes 1 project; paid plans support additional projects.

  10. Explore the Hgraph GraphQL schema

    The Hgraph GraphQL API consists of 105 tables across 8 schemas. Developers can explore the schema using the following resources:

    • Schema Reference: A comprehensive list of queryable tables, columns, types, and required subscription plans.
    • Interactive Playground: Available in the Hgraph App, allowing for live schema introspection and relationship mapping between tables.

  11. Generate and secure Hgraph API keys

    API keys are managed at the project level. Each key consists of a Publishable Key (prefix pk_prod_) and a Secret Key (prefix sk_prod_). Both keys grant identical access and must be treated as secrets: store them in environment variables and never commit them to version control or include them in client-side code.

    To create a new API key:

    1. Go to Projects in the sidebar and select the desired project.
    2. Click Create API Key.
    3. Optionally provide a nickname for the key.
    4. Copy and store the key values securely.

  12. Query Hgraph via JSON-RPC

    Every chain serves Ethereum-compatible JSON-RPC at the /rpc path.
    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