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 licensing@velobpa.com.

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:
licensing@velobpa.com

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