Home

Goldsky Go SDK

goldsky-go is an idiomatic, dependency-free Go client for the Goldsky platform. It lets Go services operate Goldsky resources through the REST control plane, query indexed Subgraph data through GraphQL, and call EVM networks through Edge JSON-RPC. The client is designed to make the safe path clear: contexts flow through every request, retry behavior is explicit, pagination is cursor-aware, and credentials are never emitted in SDK errors or logs.

Choose this SDK when your Go application needs to create or operate Goldsky pipelines, subgraphs, webhooks, or Edge endpoints; query a Goldsky Subgraph; or make HTTP JSON-RPC calls through a Goldsky Edge endpoint.

Start here

The fastest route to a working integration is to install the module, export a project API token, construct one reusable client, and make a read-only call.

go get github.com/tigusigalpa/goldsky-go
export GOLDSKY_API_KEY="your_project_api_token"

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    goldsky "github.com/tigusigalpa/goldsky-go"
)

func main() {
    client, err := goldsky.NewClient(os.Getenv("GOLDSKY_API_KEY"))
    if err != nil {
        log.Fatal(err)
    }

    page, err := client.Pipelines.List(context.Background(), goldsky.ListPipelinesOptions{})
    if err != nil {
        log.Fatal(err)
    }
    for _, pipeline := range page.Data {
        fmt.Printf("%s: %s\n", pipeline.Name, pipeline.Status)
    }
}

For a complete setup walkthrough, open Getting Started. For client options, custom transports, timeouts, and retry configuration, open Client Configuration.

What the client covers

Area	Goldsky capability	Main Go entry point	Typical use
REST control plane	Turbo Pipelines	client.Pipelines	Create, validate, inspect, pause, resume, restart, and monitor pipelines.
REST control plane	Subgraphs	client.Subgraphs	Deploy bundles; manage versions, tags, endpoints, logs, and lifecycle.
REST control plane	Entity webhooks	client.Webhooks	Create, list, and delete webhooks for subgraph entity changes.
REST control plane	Edge endpoint management	client.Edge	Create and administer Edge endpoints, access keys, and metrics.
REST control plane	Catalogs	client.Catalogs	Discover supported subgraph chains, Edge networks, and Edge Data sources.
Data plane	Subgraph GraphQL	client.GraphQL	Query public or private GraphQL endpoints.
Data plane	Edge RPC	client.RPC	Make single or batch HTTPS JSON-RPC 2.0 calls to EVM networks.

The REST API is the management interface for resources. GraphQL and Edge RPC are data planes: they are intended for application reads rather than resource administration. The SDK keeps those paths separate so that their credentials and failure modes remain unambiguous.

Documentation map

Foundation

Page	Read it when you need to
Getting Started	Install the module, obtain credentials, and make a first request.
Client Configuration	Configure timeouts, an HTTP transport, user agent, REST base URL, or retry policy.
REST Control Plane	Understand shared request conventions and discover the REST services.
Errors, Retries, and Pagination	Build predictable error handling, backoff, and full-list iteration.
Security	Store and rotate the three secret types safely.

Build with Goldsky

Page	Read it when you need to
Pipelines	Author, validate, create, operate, and inspect Turbo Pipelines.
Subgraphs	Deploy and run subgraph versions and tags.
Webhooks	React safely to subgraph entity changes.
Edge Endpoints	Provision and manage Edge endpoints and observe their metrics.
GraphQL	Query public or private subgraph data.
Edge RPC	Call EVM JSON-RPC methods through Edge.

Reference and operations

Page	Read it when you need to
Examples and Recipes	Start from a focused, production-oriented Go pattern.
API Coverage	Locate a Go method for each REST operation.
Development and Contributing	Run checks, understand contract coverage, or contribute.
Migration and Upgrades	Upgrade the SDK or track a Goldsky OpenAPI change.
Troubleshooting	Diagnose common configuration, HTTP, GraphQL, RPC, and webhook issues.

Design principles

The library does not require third-party runtime packages. NewClient validates options but performs no network I/O, which makes application startup deterministic. A client is intended to be created once and reused for the lifetime of an application.

Every public API operation accepts a context.Context. Give each unit of work a deadline at the call site, rather than relying solely on a global HTTP timeout. REST reads receive bounded automatic retry by default; REST mutations do not, because Goldsky does not document idempotency keys. Streaming subgraph deployments are always single-attempt because an arbitrary io.Reader cannot be safely replayed.

Runnable examples

The repository includes small programs that compile without any external Go dependencies. They cover listing pipelines, pagination, validation, a guarded pipeline creation, GraphQL, Edge RPC, webhook verification, and typed error handling.

# Run from a checkout of this repository.
go run ./examples/01-list-pipelines
go run ./examples/02-paginate-subgraphs
go run ./examples/06-edge-rpc

The mutation example refuses to run unless GOLDSKY_RUN_MUTATIONS=1 is set deliberately. See Examples and Recipes for a guide to choosing an example and adapting it safely.

Support boundaries

This wiki documents the Go SDK. Goldsky product configuration, service limits, supported chains, and resource behavior are governed by Goldsky’s live documentation and API contract. The SDK’s REST implementation is built against the Goldsky REST API v1.2.0 and maps all 40 operations in that reference at the time of writing. API Coverage records the precise mapping.

References