subgraphs

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:

goldsky subgraph init my-subgraph/1.0.0 --target-path ./my-subgraph

Key init flags

Flag	Description
--target-path <path>	Directory to write subgraph files to
--from-config <path>	Path to instant subgraph JSON configuration file
--abi <source>	ABI source for contract(s)
--contract <address>	Contract address(es) to watch
--contract-events <names>	Event names to index
--contract-calls <names>	Call names to index
--contract-name <name>	Name of the contract(s)
--network <network>	Network for contract(s) — see docs for supported networks
--start-block <block>	Block to start indexing from
--description <text>	Subgraph description
--call-handlers	Enable call handlers
--build	Build the subgraph after writing files
--deploy	Deploy the subgraph after build
--force	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.

# 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:

goldsky subgraph deploy my-subgraph/1.0.0 --from-abi ./MyContract.json

From IPFS hash

Deploy a subgraph already published to IPFS:

goldsky subgraph deploy my-subgraph/1.0.0 --from-ipfs-hash QmXyz...

Use --ipfs-gateway <url> 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:

goldsky subgraph deploy my-subgraph/1.0.0 \
  --from-url <your-thegraph-deployment-url>

See docs.goldsky.com/subgraphs/deploying-subgraphs.

Deploy flags reference

Flag	Description
--path <dir>	Path to compiled subgraph directory
--from-url <url>	GraphQL endpoint of a publicly deployed subgraph (The Graph migration)
--from-ipfs-hash <hash>	IPFS hash of a publicly deployed subgraph
--from-abi <path>	Generate a subgraph from an ABI file
--ipfs-gateway <url>	Custom IPFS gateway (default: https://ipfs.network.thegraph.com)
--tag <tags>	Tag the subgraph after deployment (comma-separated for multiple)
--start-block <number>	Override start block
--graft-from <name/version>	Graft from the latest block of an existing subgraph
--remove-graft	Remove grafts from the subgraph prior to deployment
--enable-call-handlers	Enable call handlers (only with --from-abi)
--description <text>	Description/notes for the subgraph

Note: --path, --from-url, --from-ipfs-hash, and --from-abi 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:

goldsky subgraph list

Public vs. private endpoints

By default endpoints are public. To control endpoint visibility:

# 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:

1. Go to app.goldsky.com → Settings → API Keys and create a key.
2. Add the Authorization header to requests:

   Authorization: Bearer <your-api-key>
   

---

Subgraph Tags

Tags pin a human-readable alias (like prod) to a specific subgraph version, so your frontend URL never changes when you redeploy.

# 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:

goldsky subgraph deploy my-subgraph/2.0.0 --path ./build --tag prod

See docs.goldsky.com/subgraphs/tags.

---

Webhooks

Subgraph webhooks send a payload to an HTTP endpoint on every entity change (INSERT, UPDATE, DELETE). Useful for notifications and push-based flows.

# 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
--name <name>	Webhook name (must be unique) — required
--url <url>	URL to send events to — required
--entity <entity>	Subgraph entity to send events for — required
--secret <secret>	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.

See docs.goldsky.com/subgraphs/webhooks.

---

Managing Subgraphs

List subgraphs

# 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

goldsky subgraph update my-subgraph/1.0.0 \
  --public-endpoint enabled \
  --private-endpoint disabled \
  --description "Production deployment"

Flag	Values	Description
--public-endpoint	enabled / disabled	Toggle public endpoint visibility
--private-endpoint	enabled / disabled	Toggle private endpoint (requires API key)
--description	text	Description/notes for the subgraph

Pause and resume

# 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

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:

# 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
--since <duration>	1m	Show logs newer than duration (e.g. 5s, 2m, 3h)
--format <format>	text	Output format: pretty, json, or text
--filter <level>	info	Minimum log level: error, warn, info, debug
--levels <levels>	—	Explicit comma-separated log levels to include
--interval <seconds>	5	Seconds between log checks

Stalled subgraphs

If a subgraph stops progressing, Goldsky auto-pauses it and sends an email notification. To diagnose:

1. Check logs: goldsky subgraph log my-subgraph/1.0.0 --since 1h --filter error
2. Look for handler errors, RPC timeouts, or out-of-memory issues
3. Fix the issue and redeploy, or contact [email protected]

---

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.

See docs.goldsky.com/subgraphs/introduction.

---

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	goldsky subgraph list
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

• /turbo-builder — Build a streaming pipeline to a database instead of a GraphQL API
• Goldsky docs: docs.goldsky.com/subgraphs/introduction