n8n-nodes-thegraph

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for The Graph Protocol, providing seamless access to decentralized blockchain indexing. Query any blockchain data from subgraphs including Uniswap, Aave, Compound, ENS, and thousands more with built-in support for filtering, pagination, time-travel queries, and full-text search.

Features

• Execute GraphQL Queries: Run raw GraphQL queries against any subgraph
• Entity Operations: Get single entities by ID or multiple entities with filtering
• Advanced Filtering: Support for all Graph filter operators (_gt, _lt, _in, _contains, etc.)
• Pagination: First/skip pattern with configurable page sizes up to 1000
• Time-Travel Queries: Query historical blockchain state at specific blocks
• Full-Text Search: Search across entity fields with text matching
• Subgraph Metadata: Get indexing status, latest block, and deployment info
• Schema Introspection: Discover available entities and fields
• Network Data: Query indexers, curators, delegators, and subgraph metrics
• Studio Integration: Manage deployments and view usage statistics
• Popular Subgraphs: Pre-configured IDs for Uniswap, Aave, Compound, Lido, ENS, and more
• Error Handling: Automatic retry logic with rate limit handling

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install
3. Enter n8n-nodes-thegraph in the npm package name field
4. Click Install

Manual Installation

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the package
npm install n8n-nodes-thegraph

# Restart n8n

Development Installation

# Clone the repository
git clone https://github.com/Velocity-BPA/n8n-nodes-thegraph.git
cd n8n-nodes-thegraph

# Install dependencies
npm install

# Build the project
npm run build

# Link to n8n
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-thegraph

# Restart n8n

Credentials Setup

The Graph API (Decentralized Network)

| Field | Description | |-------|-------------| | API Key | Your API key from The Graph Studio | | Gateway URL | Default: https://gateway.thegraph.com/api | | Default Subgraph ID | Optional default subgraph deployment ID |

The Graph Studio (Development)

| Field | Description | |-------|-------------| | Deploy Key | Your deploy key from The Graph Studio | | Studio API URL | Default: https://api.studio.thegraph.com/query | | Owner | Your Studio username or organization |

Hosted Service (Legacy)

| Field | Description | |-------|-------------| | Access Token | Optional access token for private subgraphs | | Default Subgraph Name | Format: owner/subgraph-name |

Resources & Operations

Query Resource

| Operation | Description | |-----------|-------------| | Execute Query | Run a raw GraphQL query with optional variables | | Get Entity | Retrieve a single entity by ID | | Get Entities | Get multiple entities with filtering and pagination | | Time Travel | Query historical state at a specific block | | Search | Full-text search across entities | | Count | Count entities matching filter criteria |

Subgraph Resource

| Operation | Description | |-----------|-------------| | Get Metadata | Get _meta including block info and deployment ID | | Check Status | Check if subgraph has indexing errors | | Get Schema | Introspect the GraphQL schema |

Network Resource

| Operation | Description | |-----------|-------------| | List Subgraphs | Browse subgraphs on The Graph Network | | Get Details | Get detailed subgraph information | | Get Indexer Info | Query indexer stats and allocations | | Get Curator Info | Query curator signals and rewards | | Get Delegator Info | Query delegator stakes and rewards |

Studio Resource

| Operation | Description | |-----------|-------------| | Get Deployments | List deployment versions | | Get Usage | View API usage statistics |

Usage Examples

Query Uniswap V3 Pools

// Get top 10 pools by TVL
{
  "resource": "query",
  "operation": "getEntities",
  "entity": "pools",
  "fields": "id, token0 { symbol }, token1 { symbol }, totalValueLockedUSD",
  "first": 10,
  "orderBy": "totalValueLockedUSD",
  "orderDirection": "desc"
}

Get Token Holders

// Get ERC-20 token holders with balance > 0
{
  "resource": "query",
  "operation": "getEntities",
  "entity": "accountBalances",
  "fields": "id, account { id }, amount",
  "filterField": "amount_gt",
  "filterValue": "0",
  "first": 100
}

Time-Travel Query

// Query pool state at block 18000000
{
  "resource": "query",
  "operation": "timeTravel",
  "entity": "pools",
  "fields": "id, totalValueLockedUSD, volumeUSD",
  "blockNumber": 18000000,
  "first": 10
}

Full-Text Search

// Search for tokens containing "swap"
{
  "resource": "query",
  "operation": "search",
  "searchEntity": "tokenSearch",
  "searchText": "swap",
  "fields": "id, name, symbol",
  "first": 20
}

Get Subgraph Metadata

// Check indexing status
{
  "resource": "subgraph",
  "operation": "metadata",
  "subgraphId": "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV"
}
// Returns: { block: { number, hash, timestamp }, deployment, hasIndexingErrors }

Raw GraphQL Query

// Execute custom query with variables
{
  "resource": "query",
  "operation": "execute",
  "query": "query GetPool($id: ID!) { pool(id: $id) { id, token0 { symbol }, token1 { symbol } } }",
  "variables": "{\"id\": \"0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8\"}"
}

The Graph Concepts

Subgraph

A subgraph defines what data to index from a blockchain and how to transform it. Each subgraph has a unique deployment ID (starting with Qm for IPFS).

Entity

An entity is a data type defined in a subgraph's schema. For example, Uniswap V3 has entities like Pool, Token, Swap, and Position.

Indexer

Indexers are node operators who run Graph Nodes to index subgraphs and serve queries. They stake GRT to participate in the network.

Curator

Curators signal on subgraphs to indicate quality and help indexers discover valuable subgraphs. They deposit GRT to signal.

Delegator

Delegators stake GRT to indexers without running infrastructure themselves. They earn a portion of query fees and indexing rewards.

Query Fee

Queries on the decentralized network cost GRT. Fees are paid to indexers serving the data.

Pre-configured Subgraphs

| Name | Network | Description | |------|---------|-------------| | Uniswap V3 | Mainnet | Decentralized exchange pools and swaps | | Uniswap V3 | Arbitrum | Uniswap on Arbitrum L2 | | Aave V3 | Mainnet | Lending protocol positions | | Compound V3 | Mainnet | Lending and borrowing markets | | Lido | Mainnet | Liquid staking protocol | | ENS | Mainnet | Ethereum Name Service domains | | Balancer V2 | Mainnet | Weighted pools and swaps | | Curve Finance | Mainnet | Stablecoin pools | | SushiSwap | Mainnet | DEX protocol data | | OpenSea | Mainnet | NFT marketplace activity |

Filter Operators

| Operator | Description | Example | |----------|-------------|---------| | (none) | Equals | symbol: "USDC" | | _not | Not equals | symbol_not: "ETH" | | _gt | Greater than | amount_gt: 1000 | | _lt | Less than | amount_lt: 100 | | _gte | Greater than or equal | balance_gte: 0 | | _lte | Less than or equal | price_lte: 1 | | _in | In array | token_in: ["USDC", "USDT"] | | _not_in | Not in array | status_not_in: ["closed"] | | _contains | String contains | name_contains: "swap" | | _contains_nocase | Contains (case insensitive) | name_contains_nocase: "SWAP" | | _not_contains | Does not contain | symbol_not_contains: "TEST" | | _starts_with | Starts with | id_starts_with: "0x" | | _ends_with | Ends with | name_ends_with: "LP" |

Error Handling

The node handles common errors automatically:

• Rate Limiting: Automatic retry with exponential backoff
• Authentication Errors: Clear messages for invalid API keys
• Subgraph Not Found: Helpful suggestions for deployment IDs
• Indexing Errors: Reports when subgraphs have indexing issues
• Query Validation: Validates GraphQL syntax before execution

Security Best Practices

1. Store API Keys Securely: Use n8n credentials storage, never hardcode keys
2. Use Decentralized Network: Prefer the decentralized network for production
3. Monitor Usage: Track query costs in The Graph Studio
4. Validate Input: Always validate user-provided query parameters
5. Rate Limit Awareness: Implement appropriate delays for bulk operations

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code:

• Passes all tests (npm test)
• Passes linting (npm run lint)
• Includes appropriate documentation
• Follows existing code style

Support

• Documentation: The Graph Docs
• Issues: GitHub Issues
• Discord: The Graph Discord

Acknowledgments

• The Graph Foundation for the decentralized indexing protocol
• n8n for the workflow automation platform
• The Web3 community for building open infrastructure