Goldsky Subgraphs
Subgraphs are hosted GraphQL APIs that index onchain events and expose them via a queryable endpoint. They are best for frontend applications and dApps that need flexible GraphQL queries over structured onchain data.
Could a Turbo pipeline solve this instead?
If your goal is to stream raw onchain data into a database (PostgreSQL, ClickHouse, Kafka, S3) — not query via GraphQL — a Turbo pipeline is faster, cheaper, and requires no custom indexing code. Say "help me build a Turbo pipeline" and the turbo-builder skill will guide you.
When to Use Subgraphs
| Use case | Best tool |
|---|
| Frontend / dApp needs a GraphQL API | Subgraphs |
| Custom business logic in indexing handlers | Subgraphs |
| Migrate existing TheGraph subgraph | Subgraphs |
| Stream raw blockchain data to a database | Turbo pipelines |
| Real-time analytics in ClickHouse or Kafka | Turbo pipelines |
| Sync subgraph data into your own database | Mirror + subgraph source |
Initialize a Subgraph
Scaffold a new subgraph project locally:
bash
goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph
Key init flags
| Flag | Description |
|---|
| Directory to write subgraph files to |
| Path to instant subgraph JSON configuration file |
| ABI source for contract(s) |
| Contract address(es) to watch |
--contract-events <names>
| Event names to index |
| Call names to index |
| Name of the contract(s) |
| Network for contract(s) — see docs for supported networks |
| Block to start indexing from |
| Subgraph description |
| Enable call handlers |
| Build the subgraph after writing files |
| Deploy the subgraph after build |
| Overwrite existing files at the target path |
Deploy a Subgraph
Goldsky supports multiple deployment paths:
From source (most common)
Requires a compiled subgraph in a local directory.
bash
# Install CLI and log in
curl https://goldsky.com | sh
goldsky login
# Deploy from local build output
goldsky subgraph deploy my-subgraph/1.0.0 --path ./build
From ABI (instant subgraph)
Generate and deploy a subgraph directly from a contract ABI — no AssemblyScript needed:
bash
goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json
From IPFS hash
Deploy a subgraph already published to IPFS:
bash
goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...
Use
to specify a custom gateway (defaults to
https://ipfs.network.thegraph.com
).
No-code (dashboard wizard)
Use the Goldsky dashboard to deploy pre-built subgraphs for common standards (ERC-20, ERC-721, etc.) without writing code. Navigate to app.goldsky.com → Subgraphs → Create.
Migrate from The Graph
One-step migration — no code changes needed:
bash
goldsky subgraph deploy my-subgraph/1.0.0 \
--from-url <your-thegraph-deployment-url>
Deploy flags reference
| Flag | Description |
|---|
| Path to compiled subgraph directory |
| GraphQL endpoint of a publicly deployed subgraph (The Graph migration) |
| IPFS hash of a publicly deployed subgraph |
| Generate a subgraph from an ABI file |
| Custom IPFS gateway (default: https://ipfs.network.thegraph.com
|
| Tag the subgraph after deployment (comma-separated for multiple) |
| Override start block |
--graft-from <name/version>
| Graft from the latest block of an existing subgraph |
| Remove grafts from the subgraph prior to deployment |
| Enable call handlers (only with ) |
| Description/notes for the subgraph |
Note: ,
,
, and
are mutually exclusive — use only one.
GraphQL Endpoints
Every deployed subgraph gets a public GraphQL endpoint:
https://api.goldsky.com/api/public/<project-id>/subgraphs/<name>/<version>/gn
To get your endpoint URL:
Public vs. private endpoints
By default endpoints are public. To control endpoint visibility:
bash
# Disable public endpoint
goldsky subgraph update my-subgraph/1.0.0 --public-endpoint disabled
# Enable private endpoint (requires API key)
goldsky subgraph update my-subgraph/1.0.0 --private-endpoint enabled
To require an API key for private endpoints:
- Go to app.goldsky.com → Settings → API Keys and create a key.
- Add the header to requests:
Authorization: Bearer <your-api-key>
Subgraph Tags
Tags pin a human-readable alias (like
) to a specific subgraph version, so your frontend URL never changes when you redeploy.
bash
# Create or update a tag
goldsky subgraph tag create my-subgraph/1.0.0 --tag prod
# Tagged endpoint:
# https://api.goldsky.com/api/public/<project-id>/subgraphs/my-subgraph/prod/gn
# Delete a tag
goldsky subgraph tag delete my-subgraph/1.0.0 --tag prod
You can also tag at deploy time:
bash
goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod
Webhooks
Subgraph webhooks send a payload to an HTTP endpoint on every entity change (
,
,
). Useful for notifications and push-based flows.
bash
# Create a webhook
goldsky subgraph webhook create my-subgraph/1.0.0 \
--name my-webhook \
--url https://example.com/hook \
--entity Transfer \
--secret my-secret
# List all webhooks
goldsky subgraph webhook list
# List available entities for a subgraph
goldsky subgraph webhook list-entities my-subgraph/1.0.0
# Delete a webhook
goldsky subgraph webhook delete my-webhook
| Flag | Description |
|---|
| Webhook name (must be unique) — required |
| URL to send events to — required |
| Subgraph entity to send events for — required |
| Secret included with each webhook request |
Tip: If you need guaranteed delivery to a database, use Mirror to sync subgraph data instead of webhooks — it's more reliable.
Managing Subgraphs
List subgraphs
bash
# List all subgraphs
goldsky subgraph list
# List a specific subgraph
goldsky subgraph list my-subgraph/1.0.0
# Show only tags or deployments
goldsky subgraph list --filter tags
goldsky subgraph list --filter deployments
# Summary view
goldsky subgraph list --summary
Update a subgraph
bash
goldsky subgraph update my-subgraph/1.0.0 \
--public-endpoint enabled \
--private-endpoint disabled \
--description "Production deployment"
| Flag | Values | Description |
|---|
| / | Toggle public endpoint visibility |
| / | Toggle private endpoint (requires API key) |
| text | Description/notes for the subgraph |
Pause and resume
bash
# Pause a subgraph (stops indexing)
goldsky subgraph pause my-subgraph/1.0.0
# Resume a paused subgraph
goldsky subgraph start my-subgraph/1.0.0
Delete a subgraph
bash
goldsky subgraph delete my-subgraph/1.0.0
# Skip confirmation prompt
goldsky subgraph delete my-subgraph/1.0.0 --force
Logs and Debugging
Tail a subgraph's logs to diagnose issues:
bash
# View recent logs
goldsky subgraph log my-subgraph/1.0.0
# Logs from the last hour, errors only
goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error
# JSON format for parsing
goldsky subgraph log my-subgraph/1.0.0 --format json
| Flag | Default | Description |
|---|
| | Show logs newer than duration (e.g. , , ) |
| | Output format: , , or |
| | Minimum log level: , , , |
| — | Explicit comma-separated log levels to include |
| | Seconds between log checks |
Stalled subgraphs
If a subgraph stops progressing, Goldsky auto-pauses it and sends an email notification. To diagnose:
- Check logs:
goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error
- Look for handler errors, RPC timeouts, or out-of-memory issues
- Fix the issue and redeploy, or contact support@goldsky.com
Cross-Chain Subgraphs
To index the same contract across multiple chains, deploy separate subgraphs per chain, then use a Mirror pipeline to merge them into one database table.
CLI Command Reference
| Action | Command |
|---|
| Initialize subgraph | goldsky subgraph init <name/version>
|
| Deploy from source | goldsky subgraph deploy <name/version> --path .
|
| Deploy from The Graph | goldsky subgraph deploy <name/version> --from-url <url>
|
| Deploy from ABI | goldsky subgraph deploy <name/version> --from-abi <path>
|
| Deploy from IPFS | goldsky subgraph deploy <name/version> --from-ipfs-hash <hash>
|
| List subgraphs | |
| Delete subgraph | goldsky subgraph delete <name/version>
|
| Pause subgraph | goldsky subgraph pause <name/version>
|
| Start subgraph | goldsky subgraph start <name/version>
|
| Update subgraph | goldsky subgraph update <name/version> --public-endpoint enabled
|
| Tail logs | goldsky subgraph log <name/version>
|
| Create tag | goldsky subgraph tag create <name/version> --tag <tag>
|
| Delete tag | goldsky subgraph tag delete <name/version> --tag <tag>
|
| Create webhook | goldsky subgraph webhook create <name/version> --name <n> --url <u> --entity <e>
|
| List webhooks | goldsky subgraph webhook list
|
| Delete webhook | goldsky subgraph webhook delete <webhook-name>
|
| List webhook entities | goldsky subgraph webhook list-entities <name/version>
|
Related
- — Build a streaming pipeline to a database instead of a GraphQL API
- Goldsky docs: docs.goldsky.com/subgraphs/introduction