Client Configuration

goldsky.NewClient constructs the top-level SDK client. The constructor performs no network call, so it is appropriate to run it during application startup. Pass the required project API token first and then zero or more functional options.

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithTimeout(30*time.Second),
    goldsky.WithUserAgent("my-service/1.0"),
)
if err != nil {
    return err
}

Create one client per credential and reuse it. The services on that client share a configured *http.Client and are designed for concurrent use. The Edge API key can be rotated at runtime with SetEdgeAPIKey.

Required and optional configuration

Item	Default	Use it for	Important behavior
Project API token	Required	REST and private GraphQL authentication	Empty or whitespace-only tokens are rejected locally.
WithTimeout(d)	Go client timeout of 60 seconds	A total HTTP request timeout	A negative duration is rejected. The provided HTTP client is cloned before its timeout is changed.
WithHTTPClient(h)	SDK-managed http.Client	Custom transport, proxy, TLS, tracing, or connection pooling	A nil client falls back to the default managed client.
WithUserAgent(ua)	goldsky-go/1.0.0	Identifying your integration	Applied to REST, GraphQL, and RPC requests.
WithRetryPolicy(p)	3 attempts; 500 ms initial backoff; 30 s cap	Fine-grained retry behavior	See Errors, Retries, and Pagination.
WithRetryMaxAttempts(n)	3	Disabling or limiting retries	1 disables automatic retries.
WithRetryMutations()	Disabled	Opting into retrying replayable mutations	Unsafe unless your business workflow handles duplicates.
WithEdgeAPIKey(key)	Empty	Initial Edge JSON-RPC key	Required before RPC.Call or RPC.Batch.
WithBaseURL(url)	Goldsky REST v1 base URL	Controlled test or proxy endpoint	URL must be absolute HTTP(S), without query or fragment.
WithEdgeBaseURL(url)	Goldsky Edge RPC base URL	Controlled test or proxy endpoint	URL must be absolute HTTP(S), without query or fragment.
WithLogger(l)	Discarding logger	Retry diagnostics	Retry log messages do not include credentials.

The default REST base URL is https://api.goldsky.com/api/v1. The GraphQL service uses its own documented base path, while Edge RPC uses its own HTTPS base URL. In normal production code, leave all three at their defaults.1

Context deadline versus HTTP timeout

Use both carefully. The HTTP client timeout is a global ceiling for every request made through the client. A context deadline is a per-operation budget and is usually the better way to express the work’s real requirement.

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithTimeout(45*time.Second),
)
if err != nil {
    return err
}

ctx, cancel := context.WithTimeout(parentCtx, 8*time.Second)
defer cancel()

pipeline, err := client.Pipelines.Get(ctx, "daily-swaps")

If the context expires first, the call returns a *goldsky.TransportError that wraps the context error. Do not set a global timeout so short that legitimate deploys or large responses are predictably interrupted.

Custom transport, proxy, and observability

Supply a custom HTTP client when your environment needs a proxy, private root CA, connection limits, or OpenTelemetry-compatible transport. The SDK shallow-copies the supplied client; applying WithTimeout therefore does not mutate the object your other packages use.

transport := &http.Transport{
    Proxy: http.ProxyFromEnvironment,
    MaxIdleConns: 100,
    MaxIdleConnsPerHost: 20,
    IdleConnTimeout: 90 * time.Second,
}

httpClient := &http.Client{Transport: transport}

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithHTTPClient(httpClient),
    goldsky.WithTimeout(30*time.Second),
    goldsky.WithUserAgent("ledger-indexer/2.3"),
)

Do not log full HTTP request URLs at a generic transport layer if that layer may observe Edge RPC traffic. Edge credentials are included in the RPC URL query string by Goldsky’s endpoint design. See Security.

Retry configuration

The default retry policy applies to safe REST methods (GET, HEAD, and OPTIONS) when a transport failure occurs or when Goldsky returns HTTP 429, 500, 502, 503, or 504. It uses capped exponential backoff with full jitter and honors a longer Retry-After value.

policy := goldsky.RetryPolicy{
    MaxAttempts:    4,                 // total attempts, including the first
    InitialBackoff: 250 * time.Millisecond,
    MaxBackoff:     10 * time.Second,
}

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithRetryPolicy(policy),
)

To disable retries globally, set the total attempt count to one.

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithRetryMaxAttempts(1),
)

REST mutations are not retried by default. If a create request reaches the server but the response is lost, replaying it may create a second resource. Only enable mutation retries when the application can identify and recover from duplicate effects.

client, err := goldsky.NewClient(
    os.Getenv("GOLDSKY_API_KEY"),
    goldsky.WithRetryMutations(), // deliberate opt-in
)

Streaming multipart subgraph deployments are never retried automatically, even with this option. Reopen the bundle and retry manually only after checking whether the first deployment succeeded.

Edge API-key rotation

The Edge key is stored separately from the project token. Update it without rebuilding the client when your key-rotation process supplies a replacement.

client.SetEdgeAPIKey(nextEdgeKey)

This setter is safe while other goroutines use the client. It affects subsequent RPC calls; it does not modify the REST token or GraphQL authorization.

Test configuration

WithBaseURL and WithEdgeBaseURL are useful for httptest.Server contract tests. Keep such overrides in tests or development configuration rather than shipping them as an uncontrolled environment variable in production.

server := httptest.NewServer(handler)
defer server.Close()

client, err := goldsky.NewClient(
    "test-token",
    goldsky.WithBaseURL(server.URL),
    goldsky.WithEdgeBaseURL(server.URL),
    goldsky.WithRetryMaxAttempts(1),
)

The SDK also exposes WithClock and WithSleeper for deterministic retry tests. Most applications should not replace those defaults.

References