DEV Community: Igor

Stop Hand-Writing DefiLlama URLs: Meet defillama-go, a Go SDK for the Full API Surface

Igor — Wed, 23 Sep 2026 10:35:37 +0000

If you are building a Go service around DeFi data, the first prototype is usually straightforward: make an HTTP request, decode JSON, and move on. The friction arrives later. One endpoint lives on a different host. A token identifier needs path escaping. A rate limit needs a sensible response. A Pro key must not leak into application logs. An upstream API adds a field that your struct did not expect.

That is the gap defillama-go is designed to close. It is a small, idiomatic Go client for DefiLlama’s Free and Pro APIs that gives applications one context-aware interface for protocol TVL, token prices, stablecoins, yields, volumes, fees, bridges, real-world assets, equities, and more. Rather than presenting a thin collection of handwritten URLs, the library turns the API’s documented GET surface into discoverable Go services and methods. 1

The headline is substantial but carefully scoped: the project maps all 132 GET operations in its pinned DefiLlama OpenAPI snapshot—31 Free operations and 101 Pro operations—across 21 services. The route registry, generated service methods, and API index are kept in step by contract tests. That does not mean an SDK can eliminate the need to understand data semantics, but it does remove a surprising amount of transport plumbing from a production Go codebase. 1

The problem is not simply “make a request”

DefiLlama’s API is broad by design. Its documentation spans TVL, coins, stablecoins, yields, DEX and derivatives volumes, fees and revenue, bridges, protocol metrics, equities, pre-IPO data, and RWA endpoints. Some Free endpoints are served from api.llama.fi; others use dedicated origins such as coins.llama.fi, stablecoins.llama.fi, or yields.llama.fi. Pro routes use pro-api.llama.fi. 4

When that variety is handled ad hoc, every consumer makes its own decisions about URL construction, timeouts, parameter validation, error interpretation, retries, and authentication. Those choices are easy to get almost right and difficult to keep consistent. A client library earns its place when it centralizes those decisions without forcing a heavy framework on the rest of the application.

defillama-go takes that approach. The package has no runtime dependencies outside Go’s standard library, uses the API’s per-operation origin rather than one assumed base URL, and lets callers inject their own *http.Client when they need a proxy, tracing, custom TLS, or a shared timeout policy. The result is deliberately ordinary Go: construct a client, pass a context.Context, call a service method, and handle a typed result or error. 1

Start with useful Free data

The shortest path into the SDK requires no API key. Install it into a Go 1.22+ module:

go get github.com/tigusigalpa/defillama-go

Then create a client and ask for protocol data and current prices. A request-scoped deadline is included because it is a good default for any network-facing service.

package main

import (
    "context"
    "fmt"
    "log"
    "time"

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

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    client, err := defillama.New(defillama.WithTimeout(10 * time.Second))
    if err != nil {
        log.Fatal(err)
    }

    protocols, err := client.TVL().GetProtocols(ctx)
    if err != nil {
        log.Fatal(err)
    }
    if len(protocols) > 0 {
        fmt.Printf("%s TVL: $%.0f\n", protocols[0].Name, protocols[0].TVL)
    }

    prices, err := client.Prices().GetCurrentPrices(ctx, []string{
        "coingecko:bitcoin",
        "ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    })
    if err != nil {
        log.Fatal(err)
    }

    if btc, ok := prices["coingecko:bitcoin"]; ok {
        fmt.Printf("BTC: $%.2f\n", btc.Price)
    }
}

This example illustrates the API shape that carries through the package. Client exposes data domains such as TVL(), Prices(), Stablecoins(), Yields(), Volumes(), and Fees(). Methods accept context.Context first. The client constructor does not make a network request, so invalid options fail early and constructing a shared client does not produce unexpected I/O. 1

For a Free endpoint, callers do not need to remember which DefiLlama host owns the operation. The route metadata does that work. This is a small convenience in a sample program and a meaningful reduction in copy-paste risk once a product needs price lookups, historical charts, pool data, and protocol summaries from the same service.

Broad coverage without a flat, unwieldy API

A full endpoint count is useful only if the interface remains navigable. defillama-go groups its 132 mapped operations into 21 client-owned services. The following are representative starting points rather than a replacement for the full endpoint index. 1

Need	Service accessor	Example method
Protocols, chains, TVL, and TVL charts	`TVL()`	`GetProtocols(ctx)`
Current and historical coin prices	`Prices()`	`GetCurrentPrices(ctx, coins)`
Supply and chart data for stablecoins	`Stablecoins()`	`GetStablecoins(ctx, opts)`
Free pools and Pro earn/borrow data	`Yields()`	`GetPools(ctx)`
DEX, options, and derivatives activity	`Volumes()`	`GetDEXOverview(ctx, opts)`
Fees and revenue summaries	`Fees()`	`GetOverview(ctx, opts)`
Bridges and transaction data	`Bridges()`	`GetBridgeTransactions(ctx, id, opts)`
ETFs, DAT, equities, pre-IPO, and RWA	`ETFs()`, `DAT()`, `Equities()`, `PreIPO()`, `RWA()`	`GetSnapshot(ctx)`, `GetInstitutions(ctx)`

The package documentation also covers treasury, oracle, fork, narrative, emissions, ecosystem, dimensions, financial-statement, and account-usage services. Each API operation has a corresponding entry in the project’s generated index, with the Go method and a link to the relevant official DefiLlama documentation. That index is especially helpful when moving from an API reference page to an implementation task. 2

Typed models where the API is stable, raw payloads where it is not

There is an important design choice behind a data client: pretending that every response is permanently stable can be as harmful as returning map[string]any everywhere. defillama-go uses typed models for response shapes that are stable enough to benefit from them, including Protocol, Chain, CoinPrice, Stablecoin, and YieldPool. The package also preserves the complete raw payload on its stable typed models. 1

For endpoints whose responses are intentionally evolving, the library makes that flexibility explicit with clearly named map[string]any or []any returns. For example, the Pro earn-pool query is exposed as a query-oriented result rather than a falsely rigid struct. That trade-off makes an upgrade less urgent when an upstream API adds a field, while still making the common, durable response shapes pleasant to use.

The same restraint applies to numerical values. The client decodes API-supplied numbers as float64 transport values. That is appropriate for moving JSON across the boundary, but it is not a recommendation to use binary floating point for every monetary calculation. If an application needs exact rounding or auditable financial arithmetic, convert prices, TVL, and percentages to a decimal representation at the application boundary. DefiLlama’s data and metrics also follow DefiLlama’s own methodology; the SDK is a transport layer, not financial advice. 1

Options make optional parameters visible

Query-string work is where otherwise clean integrations often become opaque. This package uses option structs so that optional values are declared in Go rather than assembled as strings. Pointer fields are omitted when they are nil, and the SDK validates declared enum values and required parameters before sending a request where applicable. 1

Here is a concise example that asks for stablecoin pools on Ethereum with a minimum TVL threshold:

result, err := client.Yields().QueryEarnPools(ctx, defillama.EarnPoolsQuery{
    Chain:      defillama.Ptr("Ethereum"),
    Stablecoin: defillama.Ptr(true),
    MinTVL:     defillama.Ptr(1_000_000.0),
    Page:       defillama.Ptr(int64(1)),
    Limit:      defillama.Ptr(int64(50)),
})
if err != nil {
    return err
}

fmt.Printf("received %d top-level fields\n", len(result))

This does not make every business rule automatic, nor should it. It does provide a reviewable declaration of what the request means. It also avoids serializing optional fields just because their Go zero value happens to be present.

Production behavior is part of the API

A library’s happy path is only half its value. In a service that calls remote data providers, cancellation, rate limits, transient failures, and actionable diagnostics should be designed rather than improvised.

Every network method in defillama-go accepts a context, and the constructed client is safe to share between goroutines. Retries are off by default, which is an appropriately conservative choice for a library. When enabled with WithRetryPolicy, retries are restricted to GET requests and retryable conditions: transient transport failures, HTTP 429 responses, and HTTP 5xx responses. The policy uses capped backoff, can add jitter, honors Retry-After when it is longer, and stops when the context is cancelled or reaches its deadline. Ordinary 4xx responses and JSON decode errors are not retried. 1

The error model is similarly specific. Applications can use errors.As to distinguish a missing resource, a rate limit, another API response, a transport failure, a malformed successful response, or an attempted Pro call without a key.

_, err := client.TVL().GetProtocol(ctx, "not-a-real-protocol")

var (
    notFound  *defillama.NotFoundError
    rateLimit *defillama.RateLimitError
    apiErr    *defillama.APIError
    transport *defillama.TransportError
)

switch {
case errors.As(err, &notFound):
    // HTTP 404: the requested protocol was not found.
case errors.As(err, &rateLimit):
    // HTTP 429: rateLimit.RetryAfter may be non-zero.
case errors.As(err, &apiErr):
    // Another non-2xx status with a redacted URL and response diagnostics.
case errors.As(err, &transport):
    // DNS, TLS, timeout, or cancellation. errors.Is reaches the cause.
case err != nil:
    return err
}

This error taxonomy matters in operations. A 404 may be a valid absence. A 429 may justify queueing or delaying work. A timeout might point to an overloaded dependency or an overly aggressive deadline. Treating all three as the same error string makes monitoring and recovery much harder than they need to be.

Pro API support that treats the key as sensitive

DefiLlama Pro authenticates requests with the API key in the URL path. That detail deserves care because URLs often surface in logs, traces, proxy diagnostics, and wrapped network errors. The official documentation identifies pro-api.llama.fi as the Pro request origin, and the SDK places the key in one escaped path segment as required by that convention. 4

The library’s design goes beyond merely avoiding a custom header. Calling a Pro method without WithAPIKey returns *ProAPIKeyRequiredError before the SDK builds or sends a request. When a key is configured, the implementation redacts it from URLs, response diagnostics, headers, bodies, and nested transport errors. It also refuses to follow a redirect to a different origin for a Pro request, preventing the path-embedded credential from being forwarded elsewhere. Same-origin redirects can still work. 1

Creating a Pro client remains a normal Go configuration step:

client, err := defillama.New(
    defillama.WithAPIKey(os.Getenv("DEFILLAMA_API_KEY")),
    defillama.WithTimeout(10*time.Second),
    defillama.WithRetryPolicy(defillama.RetryPolicy{
        MaxAttempts: 3,
        BaseDelay:  250 * time.Millisecond,
        MaxDelay:   2 * time.Second,
        Jitter:     true,
    }),
)
if err != nil {
    return err
}

chart, err := client.TVL().GetProtocolTVLChart(ctx, "aave", nil)

There is also an explicit WithPreferProForFree(true) option. If a Pro key is available, it routes the 31 Free operations that have an official Pro mapping through their Pro equivalents. The important word is explicit: configuring a key alone does not silently change the default routing behavior. 1

What to expect from a young library

The project’s changelog identifies v0.1.0 as the initial release, so the right way to evaluate it is not as a decades-old dependency with an enormous ecosystem. Instead, look at whether its scope is honest and whether its maintenance mechanics are visible. The repository includes an MIT license, contribution guidance, a security policy, GitHub Actions for CI, tests, CodeQL, coverage, and releases. Its CI matrix runs formatting checks, go vet, race-enabled tests, coverage, and builds against Go 1.22 and the stable Go release. 1 5

The endpoint coverage is tied to a pinned OpenAPI snapshot. That is good for repeatability, but it also means newly added upstream operations require the SDK to update its snapshot and regenerate the affected route and documentation artifacts. The package currently targets GET operations, so it should not be mistaken for a generalized client for hypothetical future write endpoints. Finally, data fields returned as floats deserve deliberate conversion in code paths where precision matters. These are useful boundaries to understand before adopting any financial-data transport library. 1

A practical starting point

For a dashboard, analytics service, alerting job, portfolio research tool, or backend that needs DefiLlama data in Go, the next step is intentionally small:

git clone https://github.com/tigusigalpa/defillama-go.git
cd defillama-go
go run ./examples/basic

The repository’s basic example calls Free endpoints; the separate Pro example demonstrates environment-based key loading, retry configuration, rate-limit handling, usage retrieval, and a Pro TVL chart request. From there, browse the endpoint index, choose the service that matches the data product you are building, and keep application-specific calculations and validation on your side of the boundary. 1

defillama-go is appealing not because it hides DefiLlama behind magic, but because it makes the integration boring in the best sense of the word. It centralizes API routing, context propagation, parameter encoding, error handling, retries, and key redaction while leaving Go applications in control of their HTTP client, timeouts, precision policy, and domain decisions. For teams that would rather spend time using DeFi data than maintaining endpoint glue, that is a solid foundation.

References

bitquery-go: A Production-Minded Go SDK for Bitquery GraphQL

Igor — Tue, 22 Sep 2026 07:23:28 +0000

Blockchain data services rarely fail because sending a GraphQL request is difficult. They fail at the seams: a token appears in a log, an overloaded endpoint receives an avoidable retry storm, a large on-chain amount is decoded as an imprecise floating-point number, or a reconnecting stream is treated as exactly-once delivery. These are not glamorous problems, but they are the problems that determine whether an integration survives contact with production.

bitquery-go is an MIT-licensed Go SDK for Bitquery GraphQL that takes those seams seriously. Rather than wrapping every possible field in a sprawling generated surface, it combines a small set of practical helpers with a direct, inspectable GraphQL operation API. More importantly, it makes the meaningful boundaries visible: Bitquery V1 and V2 are separate clients, HTTP queries and WebSocket subscriptions are separate workflows, and GraphQL-level errors are not confused with transport failures. 1

This is a library for Go teams building indexers, analytics backends, monitoring services, trading-data pipelines, or internal blockchain-data tools. It does not promise to abstract away the Bitquery schema. It gives developers a clear way to work with that schema while adding the safeguards that should surround an API client in a real service.

Core design choice: V1 and V2 remain distinct contracts. The SDK does not rewrite a GraphQL document, switch endpoints, or silently fall back from one version to the other. 1

Start with the correct API contract

The first useful feature of bitquery-go is also the least flashy: it refuses to pretend that the two Bitquery APIs are interchangeable. The package exposes a v1.Client for the historical HTTPS GraphQL API and a v2.Client for the streaming GraphQL API over HTTPS. Live V2 updates use a separate subscription.Client over WebSocket. That separation matters because the schemas, endpoint families, coverage, and migration expectations differ. 2

For a new integration, V2 is the natural place to begin when the required EVM or Solana data is available. A legacy V1 document remains a valid reason to use V1, but migration should be checked query by query rather than assumed. The SDK helps rather than obstructs this decision: it can surface typed deprecation notices for V1 calls on documented deprecated networks, without blocking a deliberate legacy request. 1

The result is a more honest architecture. A codebase can say exactly which API contract it depends on, instead of hiding an important data decision behind a generic “client.” That makes reviews, upgrades, and incident response easier.

Install once, then keep GraphQL visible

The package requires Go 1.21 or newer and installs in the usual way. Client creation is local; no network request occurs until an operation is executed. 1

go get github.com/tigusigalpa/bitquery-go

A V2 query can remain idiomatic Go without turning GraphQL into string concatenation. The Operation keeps the operation name, query, and variables in separate fields. Values belong in Variables, where they can be encoded safely and inspected independently from the document.

package main

import (
    "context"
    "os"

    bitquery "github.com/tigusigalpa/bitquery-go"
    "github.com/tigusigalpa/bitquery-go/v2"
)

func latestBlocks(ctx context.Context) error {
    provider := bitquery.NewStaticTokenProvider(os.Getenv("BITQUERY_TOKEN"))

    client, err := v2.New(provider, bitquery.WithRegion(bitquery.RegionUS))
    if err != nil {
        return err
    }

    response, err := client.Execute(ctx, bitquery.Operation{
        OperationName: "LatestBlocks",
        Query: `query LatestBlocks($network: evm_network!) {
            EVM(network: $network) {
                Blocks(limit: {count: 3}) { Block { Number Time } }
            }
        }`,
        Variables: map[string]any{"network": "eth"},
    })
    if err != nil {
        return err
    }

    return response.DecodeData(&map[string]any{})
}

This approach is a strong fit for an evolving GraphQL API. The SDK offers thin helpers for common operations, including selected EVM DEX trades, transfers, and transactions, plus selected Solana operations. However, raw Execute remains the primary compatibility escape hatch when a team needs a newer cube or field. Instead of waiting for an SDK release to expose every schema addition, a developer can use the current Bitquery schema and keep the operation under version control. 1

Treat authentication and endpoints as configuration, not application logic

The library supports two safe token paths: a pre-minted access token via NewStaticTokenProvider, or an OAuth client-credentials provider. The latter caches the token and coalesces concurrent refresh work, which is the behavior a multi-goroutine service needs when a token is nearing expiry. 1

Endpoint selection is similarly explicit. Europe is the default region, while Asia and US can be chosen through options. A service can override the HTTP base URL or WebSocket URL for a private proxy or test server, with validation for absolute HTTP(S) and WS(S) URLs. The client will not accept a credential-bearing custom endpoint. 1

That final detail is worth noticing. For WebSocket authentication, Bitquery requires the OAuth token in the URL query string. bitquery-go adds that query parameter internally, redacts it from errors and logger output, and tells callers not to build it into a custom endpoint themselves. This is the type of defensive default that prevents a momentary debugging shortcut from becoming a credential leak. 1

Make errors useful without throwing away GraphQL data

GraphQL changes the usual “non-200 equals failure” mental model. An HTTP 200 response can contain errors[], and it can still contain usable partial data. bitquery-go preserves that distinction.

By default, Execute returns the response even when GraphQL errors are present, allowing application code to inspect response.Errors and decide whether partial data is acceptable. A strict mode is available when the application wants any GraphQL error returned as a typed KindGraphQL error. Crucially, strict-mode errors retain the full response, so partial data is still available for an explicit business decision. 1

Transport and API failures also arrive through *bitquery.Error, enabling code to distinguish authentication, authorization, plan-entitlement, rate-limit, server, GraphQL, subscription, and configuration failures. That is much more actionable than branching on error-message text.

var apiErr *bitquery.Error
if errors.As(err, &apiErr) {
    switch apiErr.Kind {
    case bitquery.KindRateLimited:
        // Respect apiErr.RetryAfter and reduce pressure if needed.
    case bitquery.KindPlanEntitlement:
        // The request is outside the plan; retrying will not help.
    case bitquery.KindAuthentication:
        // Refresh or replace the credentials used by the provider.
    case bitquery.KindServer:
        // Temporary failure: apply service-level observability and policy.
    }
}

The default retry policy is deliberately conservative: up to four attempts with jittered exponential backoff, capped at 60 seconds, with Retry-After taking precedence when the service sends it. It retries transient transport conditions, selected 5xx responses, rate limits, and documented shared-compute blocks. It does not automatically replay mutations or HTTP subscriptions, because repeating those operations may be unsafe for the calling application. 1

This policy is a sensible baseline rather than a hidden “reliability” switch. A workload can disable retries, add a rate limiter, set a timeout, and still use its own worker limits. In particular, the SDK does not fan out expensive queries or invent concurrency on the caller’s behalf. That makes capacity ownership clear.

Preserve numeric precision where blockchain data needs it

On-chain values are a poor match for casual float64 handling. Token amounts, decimals, identifiers, and block heights may exceed the range in which a floating-point representation is exact. bitquery-go deliberately leaves response data as json.RawMessage and uses json.Number when decoding into interface values, so the application can decide whether a field belongs in math/big, a decimal package, or a domain-specific type. 1

This is an understated but important design decision. It avoids a library-level conversion that looks convenient in a demo and quietly corrupts large values in a financial or reconciliation workflow. The caller has a small additional responsibility, but it is the correct responsibility: choose the numeric representation that matches the business meaning of the field.

Build subscriptions as durable workers, not request handlers

The subscription package is equally pragmatic. Live V2 GraphQL subscriptions are exposed by subscription.Client, not bolted onto the ordinary HTTP client. That design communicates the operational reality: a subscription is a long-lived worker with cancellation, reconnection, queueing, and downstream idempotency concerns. 1

A subscription client supports both graphql-transport-ws and the legacy graphql-ws protocol. It handles the protocol lifecycle, keepalives, bounded reconnects, and clean shutdown. Its event queue is bounded so a slow consumer cannot grow memory without limit. Applications can choose drop_oldest, which keeps recent events and exposes a dropped-event count, or fail, which stops the stream with a typed error rather than losing an event silently. 1

workerCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

client, err := subscription.New(provider,
    bitquery.WithSubProtocol(bitquery.SubProtocolGraphQLTransportWS),
    bitquery.WithSubscriptionQueue(500, bitquery.OverflowDropOldest),
)
if err != nil {
    return err
}

stream, err := client.Subscribe(workerCtx, bitquery.Operation{
    Query: `subscription {
        EVM(network: eth) { Blocks { Block { Number Time } } }
    }`,
})
if err != nil {
    return err
}
defer stream.Close()

for event := range stream.Events {
    if event.Type == subscription.EventData {
        // Persist a stable event key before applying the payload.
    }
}
if err := stream.Err(); err != nil {
    return err
}

The final comment is not ceremonial. Realtime messages should be treated as at-least-once, and portions may be unordered. A production consumer should persist a stable, domain-appropriate deduplication key and backfill a missed interval with an HTTP query after a longer outage. The SDK provides the lifecycle machinery, but it does not make an impossible exactly-once guarantee on behalf of a downstream database or business process. 2

Where bitquery-go fits best

bitquery-go is compelling when a Go team wants a dependable client boundary without surrendering control of its GraphQL documents. It suits services that need a straightforward HTTP query path today and may later add live updates. It also suits teams maintaining a V1 integration that need to recognize its legacy status without breaking it through an automatic migration.

It is intentionally not a generated, exhaustive Go model of every Bitquery cube and field. That is a feature for projects where the live schema evolves faster than a typed SDK can be regenerated and reviewed. Use the Bitquery IDE and current schema as the authority for data availability; keep important operations in the application; use this package for authentication, endpoint management, execution, error handling, rate limits, cancellation, and subscriptions. 1

The repository also includes runnable examples for HTTP, OAuth client credentials, subscriptions, V1 historical queries, V2 Solana transfers, and custom endpoints. Examples compile without credentials and only make a live request when the required environment variables are supplied. That makes them practical starting points for an internal spike or a production integration review. 1

A small SDK with the right boundaries

The most valuable API libraries are not those that hide every underlying detail. They are the ones that hide repetitive plumbing while making consequential behavior explicit. bitquery-go does that well: it keeps V1 and V2 honest, keeps GraphQL operations inspectable, protects sensitive token material in diagnostics, treats partial responses correctly, preserves numeric precision, and gives streaming workloads the controls they actually need.

If you are building Bitquery-backed software in Go, start with the README, run the example closest to your workload, and make the version and delivery semantics part of your design from day one. You will spend less time untangling invisible client behavior later—and more time building the blockchain-data product your users actually need. 1

References

Goldsky from Go, Without the Glue Code: Introducing goldsky-go

Igor — Wed, 09 Sep 2026 06:00:37 +0000

If your Go service talks to blockchain data through Goldsky, the hard part should be the product logic—not repeatedly rebuilding HTTP requests, deciding which failures are safe to retry, or chasing pagination tokens across several APIs. goldsky-go is a small, community-maintained Go SDK that packages those integration details into an idiomatic client while deliberately keeping application-defined data flexible.

The library targets the Goldsky REST API v1.2.0 and maps all 40 documented REST operations. It also provides first-class access to Subgraph GraphQL endpoints and Goldsky Edge HTTPS JSON-RPC. That means one Go package can cover the control-plane work of managing pipelines, subgraphs, webhooks, and Edge endpoints, as well as the data-plane work of querying indexed data and calling an RPC endpoint. 1

goldsky-go is a community SDK, not an official Goldsky package. Its purpose is to make the supported APIs pleasant and predictable for Go applications while staying explicit about the boundaries of the underlying platform. 1

Why a Go SDK is useful here

Direct HTTP is always an option. It is also where subtle operational concerns begin to accumulate: authorization headers, escaped path parameters, bounded response bodies, request deadlines, error formats, pagination state, JSON-RPC envelope validation, multipart upload behavior, and retry policy. A thin SDK earns its place when it removes this repeated plumbing without hiding the decisions that matter.

That is the design direction of goldsky-go. Its public methods accept context.Context, its stable API shapes use typed request and response models, and its GraphQL data remains raw JSON because a subgraph schema belongs to the consuming application. The result is Go code that can be concise without pretending that all Web3 data has one static schema. 1

The project also has no third-party runtime dependencies. For services where dependency surface area and deployment simplicity matter, that is a practical advantage: the package is built around the Go standard library rather than a large HTTP abstraction stack. 1

Start with a reusable client

The minimum installation requirement is Go 1.22 or later:

go get github.com/tigusigalpa/goldsky-go

Create the client once, configure an application-appropriate timeout, and reuse it. A project API token authenticates REST calls and private GraphQL queries.

package main

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

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

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

    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    page, err := client.Pipelines.List(ctx, goldsky.ListPipelinesOptions{
        PageSize: 25,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, pipeline := range page.Data {
        fmt.Printf("%-30s %s\n", pipeline.Name, pipeline.Status)
    }
}

This small example illustrates two conventions that scale well in production. The client carries reusable configuration, while each operation receives its own deadline through context.Context. The former sets a safety net; the latter lets a caller budget time according to the job at hand. The constructor validates options but does not make a network call, which also makes application startup and tests more predictable. 1

One package across the Goldsky surface area

goldsky-go organizes its functionality around services rather than requiring callers to assemble endpoint URLs manually. The following table is a useful high-level map.

Service	Typical work
`Pipelines`	Validate, create, inspect, pause, resume, restart, delete, and observe Turbo Pipelines.
`Subgraphs`	Deploy subgraph bundles, manage versions and tags, and read indexing logs or webhook entities.
`Webhooks`	Create, list, and delete entity webhooks.
`Edge`	Manage Edge endpoints, keys, lifecycle actions, and metrics.
`Catalogs`	Discover available subgraph chains, Edge networks, and Edge Data sources.
`GraphQL`	Send public or private Subgraph GraphQL queries.
`RPC`	Make individual or batch JSON-RPC 2.0 calls through Goldsky Edge.

The full method-to-operation mapping is maintained in the repository’s API coverage document. 2 The broader point is convenience with a clear boundary: REST management, GraphQL querying, and HTTPS RPC have different protocols and failure modes, but a Go service can work with each through one familiar client model.

Treat pagination as a protocol, not as a slice

A common integration bug is assuming that a page with fewer records than the requested size must be the last page. Goldsky pagination instead uses a continuation token. goldsky-go exposes pagers for pipelines, subgraphs, and Edge endpoints, and finishes only when there is no next-page token.

pager := client.Subgraphs.NewSubgraphPager(
    goldsky.ListSubgraphsOptions{PageSize: 100},
)

for {
    page, err := pager.NextPage(ctx)
    if err != nil {
        return err
    }

    for _, subgraph := range page.Data {
        fmt.Println(subgraph.Name, subgraph.Version, subgraph.Health)
    }

    if !page.HasMore() {
        break
    }
}

This keeps continuation-token management out of the application loop. The pager also rejects invalid sizes locally, and after it reaches the final page, subsequent calls return an empty page instead of causing needless HTTP requests. Pagers themselves are not intended for concurrent use; the reusable client and its services are safe to share. 1

Deploy subgraphs without first loading the whole bundle

Deployment is one place where the mechanics of an HTTP client matter. Subgraphs.Deploy streams a zip bundle as multipart/form-data, rather than buffering the entire archive in application memory.

bundle, err := os.Open("build.zip")
if err != nil {
    return err
}
defer bundle.Close()

subgraph, err := client.Subgraphs.Deploy(ctx, "my-subgraph", "v1",
    goldsky.DeploySubgraphOptions{
        Bundle:         bundle,
        BundleFilename: "build.zip",
    },
)
if err != nil {
    return err
}

fmt.Println("deployed", subgraph.Name, subgraph.Version)

That streaming behavior is paired with an important safety choice: deployments are not automatically retried. An arbitrary io.Reader cannot necessarily be replayed, and an ambiguous timeout on a mutation can otherwise create duplicate or confusing outcomes. The practical pattern is to reopen the file and retry only after checking whether the first request took effect. This is a good example of the library choosing an explicit operational rule over a superficially convenient one. 1

Query GraphQL, then decode the schema you own

Goldsky’s Subgraph GraphQL endpoints are useful precisely because different subgraphs can expose different entities and fields. Instead of generating brittle universal types, goldsky-go returns GraphQL data as json.RawMessage, alongside errors, headers, and HTTP status. Your application then decodes the query result into the structure it expects.

resp, err := client.GraphQL.QueryPrivate(ctx, projectID, "my-subgraph", "v1",
    goldsky.GraphQLRequest{
        Query: "{ _meta { block { number } } }",
    },
)
if err != nil {
    return err
}
if resp.HasErrors() {
    for _, graphQLError := range resp.Errors {
        fmt.Println(graphQLError.Message)
    }
    return nil
}

var data struct {
    Meta struct {
        Block struct {
            Number int `json:"number"`
        } `json:"block"`
    } `json:"_meta"`
}
if err := json.Unmarshal(resp.Data, &data); err != nil {
    return err
}
fmt.Println("indexed through block", data.Meta.Block.Number)

There are two query paths: QueryPrivate uses the project token, while QueryPublic can be used with a tokenless data client. A tokenless client will reject REST and private GraphQL access locally before any outbound request. This separation makes it easier to issue services the least privilege they need: a public data consumer does not need control-plane credentials. 1

Call Edge JSON-RPC without putting a secret in the URL

For Goldsky Edge, the SDK supports HTTPS JSON-RPC 2.0, including batch calls. The Edge key is sent through X-ERPC-Secret-Token, so it is not placed in a query string or endpoint URL.

rpcClient, err := goldsky.NewDataClient(
    goldsky.WithEdgeAPIKey(os.Getenv("GOLDSKY_EDGE_API_KEY")),
)
if err != nil {
    return err
}

var blockHex string
if err := rpcClient.RPC.Call(ctx, 1, "eth_blockNumber", nil, &blockHex); err != nil {
    return err
}
fmt.Println("latest block:", blockHex)

Batch responses deserve special attention because JSON-RPC permits responses to arrive in any order. RPC.Batch associates responses back to the input calls by request ID and validates malformed envelopes, duplicate IDs, unknown IDs, and invalid result/error combinations. Still, a transport-level success does not guarantee that every batch item succeeded, so applications should inspect each response’s Error field. 1

The current Edge scope is intentionally HTTPS JSON-RPC only; WebSockets and subscriptions are outside the library’s supported surface. Being clear about this limitation helps teams choose the SDK for the right workloads rather than discovering it after an architecture is committed. 1

Errors and retries designed for production decisions

A client library should make failures easier to handle, not just easier to print. REST errors are represented as RFC 9457 problem details, which allows code to branch on a stable problem type or status helper instead of parsing a human-readable error string.

if problem := goldsky.AsProblem(err); problem != nil {
    switch {
    case problem.IsNotFound():
        fmt.Println("resource does not exist")
    case problem.IsRateLimited():
        if seconds, ok := problem.RetryAfter(); ok {
            fmt.Println("retry after", seconds, "seconds")
        }
    default:
        fmt.Println(problem.Type)
    }
}

The retry defaults are conservative. Safe read methods (GET, HEAD, and OPTIONS) may be retried for transport errors and selected transient HTTP statuses, with capped exponential backoff, jitter, and Retry-After support. Mutating requests are not retried unless the application explicitly opts in with WithRetryMutations(). Since Goldsky does not document idempotency keys for those mutations, that default protects callers from accidentally duplicating creates or updates after uncertain network failures. Streaming deployments remain single-attempt even when mutation retries are enabled. 1

Responses are also bounded in memory by default. REST, GraphQL, and RPC bodies are limited to 16 MiB unless the application deliberately chooses a larger maximum. This kind of default is not glamorous, but it is useful protection when a service is exposed to unexpected upstream behavior. 1

Webhooks: verify before you process

Goldsky webhook deliveries include a shared secret in the literal goldsky-webhook-secret header. The package provides constant-time comparison through VerifyWebhookRequest.

func handleWebhook(w http.ResponseWriter, r *http.Request ) {
    if !goldsky.VerifyWebhookRequest(r, storedSecret) {
        http.Error(w, "invalid webhook secret", http.StatusUnauthorized )
        return
    }

    // Cap and read the body, enqueue idempotent work, then acknowledge.
    w.WriteHeader(http.StatusNoContent )
}

The documented header is a shared secret, not an HMAC signature. Therefore, authenticate the request before reading or processing its body, keep the secret protected like any credential, and make downstream handling idempotent because deliveries may be retried. The SDK provides the comparison primitive; reliable event processing remains an application responsibility. 1

A practical fit for Go teams building on Goldsky

goldsky-go will be most useful to Go teams that want a typed, testable client for Goldsky’s supported APIs but do not want a large framework or a generated client dictating every application data shape. It is especially compelling when one service needs to manage infrastructure through REST, deploy or observe subgraphs, query GraphQL, and call Edge RPC from the same codebase.

Its value is not only the number of endpoints covered. The library codifies the unglamorous details that shape reliable integrations: context propagation, escaping, pagination termination, streaming uploads, error categorization, bounded bodies, explicit credentials, redacted diagnostics, and cautious retry behavior. Those decisions leave more room for the part of the service that is actually unique.

To get started, install the package, work through the runnable examples, and consult the API coverage and security notes before enabling mutations in production. The repository is released under the permissive MIT license, and contributions are welcome. 1

Repository: github.com/tigusigalpa/goldsky-goPackage reference: pkg.go.dev/github.com/tigusigalpa/goldsky-goGoldsky API documentation: docs.goldsky.com/api-reference/overview

References

A Production-Minded Go SDK for Social Media Workflows: Introducing socialkit-go

Igor — Sun, 06 Sep 2026 06:31:20 +0000

Social-content integrations often begin with a deceptively small requirement: fetch a transcript, inspect a creator profile, or put engagement figures on a dashboard. The first HTTP request may be easy. The engineering burden arrives later, when an application needs timeouts, cancellation, pagination, rate-limit visibility, secure handling of access keys, retry discipline, and a sensible response to a job that finishes asynchronously.

That is the gap socialkit-go is designed to close. It is a typed Go SDK for the SocialKit REST API, giving Go services a single client surface for social-media and video workflows. Instead of spreading hand-written request construction and JSON decoding throughout an application, a developer calls a service on a client and receives typed data, response metadata, and an idiomatic error value. The repository targets Go 1.21+ and uses only the standard library, which keeps adoption pleasantly lightweight.1

The useful abstraction is not only “an API wrapper.” It is a Go-shaped boundary where request cancellation, response context, operational metadata, and failure semantics are part of the normal call path.

SocialKit itself offers a unified API layer for extracting social-content data such as transcripts, summaries, comments, engagement metrics, profiles, posts, search results, and downloads across YouTube, TikTok, Instagram, Facebook, X/Twitter, LinkedIn, and direct video files.2 socialkit-go brings that surface into a package that feels at home in a Go codebase.

What the SDK puts behind one client

The package exposes a Client with dedicated service fields rather than a one-size-fits-all Do function. This makes intent visible at the call site: client.YouTube, client.TikTok, or client.Downloads says more about the workflow than an endpoint string assembled in business logic. The repository currently maps the following service areas to the underlying API.1

Service area	Examples of supported work	Why it matters in an application
YouTube	Transcripts, summaries, stats, comments, channel stats, search, videos, downloads, and experimental bulk operations	Useful for research products, content intelligence, and creator analytics
TikTok and Instagram	Transcripts, summaries, stats, comments, channel data, search or reels workflows, and downloads	Helps normalize short-form content flows without platform-specific request plumbing
Facebook, X/Twitter, and LinkedIn	Video and content analysis, profile/company data, posts, threads, tweets, and related metadata depending on the platform	Enables wider social context around a campaign, creator, or organization
Direct video	Transcript and summary requests for video-file URLs	Keeps uploaded or externally hosted video in the same workflow
Status, Credits, and Downloads	Service availability, account-credit information, async download jobs and polling	Lets an application account for operational state instead of treating every request as fire-and-forget

This coverage is especially attractive when a team is building a SaaS feature, internal research tool, or AI-assisted workflow that needs data from several platforms. The alternative is usually a growing collection of platform-specific integrations that differ in request formats, response shapes, and edge cases. SocialKit describes its API as a way to avoid maintaining separate scraping infrastructure while returning structured, developer-oriented JSON.3 The Go SDK does not change the external service’s capabilities; it makes the integration contract clearer and more consistent inside Go.

Start with a small, observable integration

Installation is the familiar Go command:

go get github.com/tigusigalpa/socialkit-go

The SDK’s runnable examples expect an access key in SOCIALKIT_ACCESS_KEY, not embedded in source code.1 That is a good default for local development and deployment environments alike. The official authentication guide also recommends sending the key through the x-access-key header and cautions against placing credentials in public repositories, client-side code, logs, or screenshots.4

Here is a compact transcript request that has the operational basics already in place:

package main

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

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

func main() {
    client := socialkit.NewClient(
        os.Getenv("SOCIALKIT_ACCESS_KEY"),
        socialkit.WithTimeout(30*time.Second),
        socialkit.WithRetry(3, time.Second),
        socialkit.WithUserAgent("research-worker/1.0"),
    )

    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    transcript, meta, err := client.YouTube.Transcript(ctx, &socialkit.FetchRequest{
        URL: "https://www.youtube.com/watch?v=YOUR_VIDEO_ID",
    } )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(transcript.Transcript)

    if meta.CreditsUsed != nil {
        fmt.Printf("credits used: %.0f\n", *meta.CreditsUsed)
    }
    if meta.RateLimitRemaining != nil {
        fmt.Printf("rate-limit remaining: %d\n", *meta.RateLimitRemaining)
    }
}

Several small decisions in this example carry real production value. Every SDK request accepts a context.Context, so a worker shutdown, an HTTP request deadline, or a user cancellation can flow through naturally.1 The response is not just content: the companion ResponseMeta exposes available credit and rate-limit headers, so a product can instrument usage or make informed decisions before blindly issuing more work.1

The call also demonstrates why an SDK can be more useful than a copied curl command. Your application code stays focused on the workflow—“obtain a transcript, then use it”—rather than on repeated HTTP mechanics. The same client pattern applies when a product moves from a YouTube prototype to a TikTok search, an Instagram reels workflow, a LinkedIn company lookup, or a direct video-file summary.

Typed operations without hiding the details you need

socialkit-go supplies request and response models for the services it wraps. That helps make optional fields, cursors, limits, and platform-specific inputs visible during implementation. For example, a YouTube summary can be prompted toward a particular perspective, while the response can preserve custom fields in an Extra map. The latter design gives teams a forward-compatible route for custom-response payloads without forcing all future fields into a static struct immediately.1

The service map is intentionally explicit, but it does not prevent developers from seeing important API context. Each successful call returns metadata; errors retain typed information; and options such as WithBaseURL, WithHTTPClient, WithTimeout, and WithUserAgent leave room for test environments, custom transports, observability, or company-wide client policies.1

For teams processing comment feeds, pagination is not a hidden implementation detail. Cursor-based responses expose Cursor and HasMore, which allows the calling service to decide when the next page is worth fetching:

page, _, err := client.TikTok.Comments(ctx, &socialkit.CommentsRequest{
    URL: "https://www.tiktok.com/@creator/video/VIDEO_ID",
} )
if err != nil {
    return err
}

if page.HasMore != nil && *page.HasMore && page.Cursor != nil {
    next, _, err := client.TikTok.Comments(ctx, &socialkit.CommentsRequest{
        URL:    "https://www.tiktok.com/@creator/video/VIDEO_ID",
        Cursor: page.Cursor,
    } )
    if err != nil {
        return err
    }
    _ = next // merge or process the next page in your application layer
}

That separation is deliberate. The SDK handles the contract, while your application retains control over quotas, storage, deduplication, cancellation, and the business decision to continue paginating.

A more defensive path from API response to production behavior

Feature lists are easy to promote. The operational details are the stronger reason to look at this library.

Production concern	How `socialkit-go` addresses it	Practical implication
Credential exposure	The client sends the access key as `x-access-key` by default, and the repository documents automatic redaction of credential values in error output, metadata, and raw bodies.1	Reduces the chance that a diagnostic path turns an incident into a secret leak
Deadlines and cancellation	Every request accepts `context.Context`.1	Workers and HTTP handlers can stop waiting when the caller no longer needs the result
Transient failures	Retries are opt-in through `WithRetry`; the SDK retries 429 and 5xx responses with exponential backoff, jitter, and `Retry-After` handling.1	A temporary upstream problem does not automatically become an application error, while retry policy remains explicit
Non-transient failures	HTTP 400, 401, 403, and 404 are not retried.1	Avoids masking invalid requests or repeating work that cannot succeed without a change
Error handling	Sentinel errors and typed API errors support Go’s `errors.Is` and `errors.As` patterns.1	Calling code can branch on stable semantics rather than brittle error strings
Usage awareness	Response metadata can expose credits used, credits remaining, and rate-limit information.1	Products can meter, alert, or provide useful UX around consumption

One nuance deserves emphasis: retries are not enabled by default. The repository explicitly warns that a repeated POST can be billable and that retrying should be enabled only for operations a team is comfortable repeating.1 That is a mature trade-off. Reliability should not mean silently multiplying cost or repeating a workflow that a caller intended to run once.

Typed errors let application code make this policy visible. A request can distinguish unauthorized access, insufficient credits, a rate limit, a missing resource, and an API error with an HTTP status and error code. In other words, the error value can be treated as a decision surface, not merely as a string to log.

_, _, err := client.YouTube.Transcript(ctx, req)
if err != nil {
    switch {
    case errors.Is(err, socialkit.ErrUnauthorized):
        return fmt.Errorf("check the SocialKit access key: %w", err)
    case errors.Is(err, socialkit.ErrInsufficientCredits):
        return fmt.Errorf("usage budget exhausted: %w", err)
    case errors.Is(err, socialkit.ErrRateLimited):
        return fmt.Errorf("slow down and retry later: %w", err)
    }

    var apiErr *socialkit.APIError
    if errors.As(err, &apiErr) {
        return fmt.Errorf("social API returned HTTP %d: %w", apiErr.StatusCode, err)
    }
    return err
}

The example assumes the usual errors and fmt imports. More importantly, it illustrates a clean boundary: the integration layer translates a known external condition, and the rest of the application can react with an appropriate message, queue policy, or fallback.

Treat downloads as jobs, not as long requests

Media operations can take longer than a normal request-response interaction. For that reason, the SDK provides a v2 asynchronous download service with Start, Get, and Wait. Jobs move through queued, processing, ready, and failed states; Wait polls with caller-controlled interval and backoff while respecting the supplied context.1

job, _, err := client.Downloads.Start(ctx, "youtube", &socialkit.V2DownloadRequest{
    URL:     "https://youtube.com/watch?v=YOUR_VIDEO_ID",
    Format:  "mp4",
    Quality: "720p",
} )
if err != nil {
    return err
}

finalJob, _, err := client.Downloads.Wait(ctx, job.JobID, &socialkit.WaitOptions{
    Interval:      3 * time.Second,
    MaxAttempts:   20,
    BackoffFactor: 1.5,
})
if err != nil {
    return err
}

fmt.Println(finalJob.Status)

This is a much better fit for workers and background pipelines than pretending a download is always instantaneous. If a job fails, the SDK exposes a dedicated asynchronous-job error that can carry a retryability signal, enabling a queue consumer to decide whether to retry, surface a failure, or request human review.1

Where this fits well

The most compelling use cases are workflows where social data must become a dependable input to another system. An AI research assistant can combine a transcript, comments, and channel information into a grounded brief. A marketing intelligence dashboard can keep platform-specific data retrieval outside of its presentation logic. A content-repurposing pipeline can turn authorized source videos into transcripts, summaries, and reviewable editorial inputs. An internal tool can fetch creator, company, or engagement context just when a campaign team needs it.

The common theme is not “collect everything.” It is build a deliberate workflow around data you are authorized to process. The repository’s examples use public placeholders and explicitly remind users to substitute only URLs they are authorized to handle before making billable requests.1 That is the right operational posture: confirm your rights to the content, follow the relevant platform terms and applicable law, and use explicit limits and retention policies in the application you build.

A straightforward next step

If your Go application needs SocialKit data, start with one narrow end-to-end feature: a transcript endpoint feeding an internal search index, a creator-analysis view, or a supervised content workflow. Add a context deadline, record the metadata your product needs, and make retry behavior a conscious choice. Once that is in place, the same client structure can grow with your product rather than becoming another isolated HTTP integration.

socialkit-go is available under the MIT license, includes runnable examples for basic usage, pagination, async downloads, and error patterns, and has tests that use Go’s httptest package without requiring a network connection or a real API key.1 For developers who want a typed and production-aware Go entry point to SocialKit, that makes the library a practical place to begin.

References

Meet Watchdog: A Small, Safe Bash Watchdog for Linux Services

Igor — Wed, 26 Aug 2026 21:47:58 +0000

A service does not have to be large to become operationally important. A small API behind a reverse proxy, a background worker on a virtual machine, or a database listener used by a side project can all fail at inconvenient moments. In many of those environments, the missing piece is not a sprawling observability program. It is a reliable way to answer a narrower question: is the service healthy right now, and what should this host do if it is not?

Watchdog is an open-source, dependency-light Bash program built for exactly that job. It checks websites and services from a YAML configuration and can run a defined remediation sequence after a target remains unavailable through its configured retries. It is deliberately a one-shot tool: invoke it from a systemd timer, cron, or an existing scheduler instead of keeping another permanent daemon alive. The project is MIT-licensed and targets Linux systems with Bash 4.3 or newer. 1

That design is compelling when you own the host, understand the recovery action, and want the behavior to stay visible in a versioned configuration file. Watchdog is not trying to replace metrics, distributed tracing, external uptime checks, or a full incident-management platform. It is a focused, host-level building block for detection, bounded recovery, and signal-rich notifications.

One configuration, three useful health signals

Different outages need different evidence. An HTTP success code says something different from an open TCP socket, and a local process manager may already expose the most authoritative health signal. Watchdog supports all three common forms of check, with shared timeout, retry, and retry-delay controls. It stops retrying as soon as one attempt succeeds; only an exhausted sequence is treated as unavailable. 3

Check type	What it validates	Strong fit
HTTP/HTTPS	A request completes and returns an accepted status code; by default, the final status must be in the 2xx range.	Public APIs, web apps, reverse proxies, and `/health` or `/readyz` endpoints.
TCP	A connection to `host:port` opens before the configured timeout.	Databases, caches, brokers, and other services that must accept connections.
Command	Every configured local command exits successfully, in order.	`systemd`-managed workers, queue probes, or domain-specific local checks.

The distinction matters. A TCP connection is inexpensive and useful, but it does not prove that an application can authenticate, process a query, or serve real traffic. For a public service, an HTTP readiness endpoint is often the better customer-facing signal. For a local worker, systemctl is-active --quiet or a domain-specific probe can be more meaningful. Watchdog lets each service use the check that best represents its actual definition of healthy. 3

Safe automation starts with how commands are represented

The feature that deserves special attention is not merely that Watchdog can restart something. It is how it runs the command. Configured commands are YAML argument arrays rather than shell strings, and the implementation invokes them directly rather than interpreting a configured command through eval or bash -c. This preserves argument boundaries and avoids turning routine configuration text into accidental shell syntax. 1

In practical terms, a remediation action is declared as an executable plus its arguments—not as a fragment of shell code to be re-parsed later. That makes configuration easier to review and reduces a class of quoting and interpolation mistakes in operational workflows. 1

Each command can also have an explicit timeout and, when needed, a working directory. Remediation commands run in order and stop at the first non-zero result. That behavior makes the sequence readable: the YAML describes exactly which corrective steps the host will try, in what order, and for how long. 1

From failed check to verified recovery

Good automation should be deliberate, especially when the corrective action is a restart. Watchdog separates detection from remediation. A service can retry its check before it is declared unavailable; then, if commands are configured and the per-service cooldown permits it, Watchdog executes the ordered remediation sequence. After an optional verify_after delay, it runs the full health check again rather than assuming that a successful restart command automatically means the service recovered. 4

The project also persists per-service state. This allows notifications and hooks to be transition-aware: one failure event appears when a service moves from unknown or healthy to unavailable, repeated runs during the same ongoing outage do not produce duplicate failure events, and a later return to health produces a recovery event. A continuing outage may still receive a later remediation attempt after its cooldown, but it does not flood operators with the same alert every scheduler interval. 4

Control	Why it is useful in production
`attempts` + `retry_delay`	Filters short-lived network or startup blips before marking a service unavailable.
`cooldown`	Sets a minimum interval between remediation attempts for one service, helping to avoid restart loops.
`verify_after`	Leaves time for a restart to settle, then verifies the service with the actual health check.
Persistent state	Makes failure and recovery actions transition-based instead of repetitive.
Non-blocking global lock	Prevents overlapping scheduled invocations when a previous run is still active.

This is a pragmatic balance for small operations: the configuration does not pretend an outage is solved just because a command returned zero, and the alerting model does not confuse persistence with importance. 4

A practical Docker Compose example

Imagine a public API whose health endpoint should return either 200 or 204. The service runs in Docker Compose, and a restart should be attempted only after two failed checks. The following pattern comes directly from Watchdog’s documented examples, with values that you should replace for your own host. 6

services:
  - name: api
    check:
      type: http
      url: https://api.example.com/health
      method: GET
      follow_redirects: true
      success_status: [200, 204]
      timeout: 10
      attempts: 2
      retry_delay: 2

    actions:
      cooldown: 300
      verify_after: 5
      commands:
        - command: [docker, compose, restart, api]
          working_directory: /srv/example-api
          timeout: 120
        - command: [docker, compose, restart, nginx]
          working_directory: /srv/example-api
          timeout: 120

The operational logic is easy to read. First, test the endpoint that users or upstream systems rely on. If the check still fails after the retry policy, attempt a controlled restart from the directory containing the Compose file. Wait five seconds, then check the endpoint again. The cooldown means this should not become a restart-on-every-minute loop during a prolonged dependency failure. For a PostgreSQL listener, a Redis instance, or a message broker, the same model can use a TCP check. For a systemd worker, it can use a command check and an explicit systemctl restart action. 3

Notifications that tell you what changed

Watchdog includes built-in SMTP email and can also execute local failure and recovery hooks. Both mechanisms are transition-based. That lets a small team receive an alert when an incident begins, a recovery message when availability returns, and no redundant notification every time the scheduler observes the same unresolved fault. 5

For SMTP, the documented configuration supports templated subjects and bodies as well as an environment-variable password field. With the packaged systemd service, secrets can be kept in a root-owned environment file rather than committed in YAML. For integrations that belong outside the main configuration, hooks expose contextual environment variables such as the service name, event, check type, diagnostic detail, HTTP status, and timestamp. 5

This approach stays intentionally modest. Instead of embedding every chat or incident-management provider into the watchdog itself, the tool can hand a clean, bounded event to a local wrapper that follows your team’s preferred integration path. That is a useful boundary for a Bash utility: keep the health and remediation engine predictable, while allowing local automation to adapt it to the surrounding environment.

Start conservatively, then schedule it

Watchdog’s recommended workflow is refreshingly operational. Configure one target, validate the configuration in dry-run mode, test a controlled failure and recovery on a non-production service, and only then enable the schedule. The -n flag still validates the configuration and runs health checks, but it skips state changes, remediation, hooks, and transition notifications. The -s option narrows a run to a single configured service, which makes first tests safer and easier to interpret. 4

# Validate one service without changing state or restarting anything.
sudo /opt/service-watchdog/service-watchdog.sh \
  -c /etc/service-watchdog/config.yaml \
  -s api \
  -n

# Once validated, enable the packaged systemd timer.
sudo systemctl enable --now service-watchdog.timer

The repository ships a systemd oneshot service and timer, while cron is also supported when it is the established deployment standard. The packaged timer is configured to run every minute and uses a persistent timer; the paired unit treats Watchdog’s ordinary service-outage/remediation exit result as expected while preserving configuration or environment errors as failures that require investigation. 7

Before setting an interval, take a realistic look at the worst-case time spent in checks, retries, corrective commands, and verification. Watchdog has a non-blocking lock, so it will not overlap invocations; however, repeatedly skipped runs are still a useful signal that cadence or timeout settings need revision. 4

A small tool with a clear operational contract

There is real value in infrastructure tools that have a narrow purpose and state their boundaries clearly. Watchdog gives Linux operators a compact contract: declare health checks in YAML, decide the recovery commands in advance, use retries and cooldowns to keep the actions bounded, verify recovery, and receive notification only when availability actually changes.

If you operate a Docker Compose application, a systemd-managed worker, a local database listener, or a small fleet of Linux services, that can be the right amount of automation. Explore the repository, read the Wiki, and begin with the ready-to-adapt examples. Test against a controlled, non-production target first, then make Watchdog part of a deliberate host-level reliability routine.

References

Stop Hand-Rolling Your Arkham API Client: Meet arkham-go

Igor — Wed, 19 Aug 2026 10:33:35 +0000

Working with on-chain intelligence is rarely difficult because of a single HTTP request. The hard part is everything that surrounds the request: modelling response payloads, handling deadlines, preserving decimal values, applying pagination correctly, reacting to rate limits, keeping an eye on API-credit consumption, and maintaining a separate real-time connection when the product needs live transfer data.

That operational layer is where projects tend to accumulate fragile helpers and repeated boilerplate. A handler builds a URL in one package, a retry loop appears in another, and a stream connection is managed somewhere else entirely. The result may work in development, but it becomes difficult to reason about under load, during a partial outage, or when the API evolves.

arkham-go is designed to remove that friction. It is a production-ready Go SDK for the Arkham Intel API, built around idiomatic Go structures and the standard library. The library covers the documented REST surface and WebSocket v2 transfer streams, giving Go teams a structured foundation for applications that use address, entity, transfer, market, portfolio, risk, and related on-chain intelligence. 1

“It handles the REST endpoints and WebSocket v2 streams for you, so you can focus on building with on-chain intelligence instead of wrestling with HTTP plumbing.” — the project README 1

Why an SDK matters here

The Arkham API guide highlights the integration concerns that appear in real applications: authentication, rate limits, credit pricing, pagination, and a data model spanning addresses, entities, labels, and tags. 2 Those are not incidental details. They affect how reliably an integration behaves and how easily its costs and failure modes can be understood.

arkham-go makes those concerns part of the client contract rather than leaving every application to implement them independently. It does not promise to decide what your product should do with on-chain data; it gives your Go code predictable, typed primitives for retrieving and operationally managing that data.

Integration challenge	What `arkham-go` provides
Request and response decoding	Strongly typed Go structs for documented requests and responses. 1
Cancellation and deadlines	A `context.Context` argument on every network method. 1
Temporary API failures	Exponential backoff with jitter for `429` and `5xx` responses, including support for `Retry-After`. 1
Error classification	Sentinel errors such as `ErrBadRequest`, `ErrUnauthorized`, and `ErrRateLimited`, compatible with `errors.Is` and `errors.As`. 1
Usage observability	Response metadata carrying HTTP details and `X-Intel-Datapoints-*` headers. 1
Large result sets	Caller-controlled offset pagination with explicit limits for items and pages. 1
Live transfer workflows	WebSocket v2 stream creation, connection, reception, reconnection, and deletion helpers. 1

This is a pragmatic design choice. An SDK becomes more valuable when the network is less predictable: a timeout must stop background work, a rate limit must be recognised as a distinct condition, and a delayed response must not turn into unbounded retry traffic. By making these behaviours visible in the API, arkham-go helps keep application-level code focused on business logic.

Get started with a small surface area

The project targets Go 1.21 or newer and requires an Arkham API key. Installation is a normal Go module command: 1

go get github.com/tigusigalpa/arkham-go

Keep the key in an environment variable rather than committing it to source control:

export ARKHAM_API_KEY="your-api-key"

A minimal client can be created either from the key directly or with NewClientFromEnv() when the conventional ARKHAM_API_KEY environment variable is present. The following example looks up intelligence for an address and reads the returned usage metadata.

package main

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

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

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

    address, meta, err := client.Intelligence.Address(
        context.Background(),
        "0x28C6c06298d514Db089934071355E5743bf21d60",
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    if address.ArkhamEntity != nil {
        fmt.Println("Entity:", address.ArkhamEntity.Name)
    }
    fmt.Printf("Usage: %s/%s datapoints\n", meta.IntelDatapointsUsage, meta.IntelDatapointsLimit)
}

The point is not simply that the example is short. It is that the return values make an important operational signal available right next to the decoded domain value. A service call returns *arkham.ResponseMetadata alongside its result, including status information, request duration, final URL, and the relevant datapoint headers. That makes it possible to add usage logging or alerting without manually parsing headers throughout the codebase. 1

Build with types, not scattered query strings

One of the most welcome qualities of Go is that its types make incorrect assumptions harder to hide. arkham-go carries that preference into its filter and service interfaces. For transfer queries, typed option structs are converted into query parameters by the SDK. Decimal fields such as a USD threshold are represented as strings, preserving the decimal form expected by the API. 1

filter := &arkham.TransferFilter{
    Base:    []string{"binance"},
    Chains:  []string{"ethereum", "bitcoin"},
    Flow:    arkham.FlowOut,
    UsdGte:  "100000",
    SortKey: arkham.SortKeyTime,
    SortDir: arkham.SortDirDesc,
    Limit:   25,
    TimeRange: &arkham.TimeRange{
        TimeLast: "24h",
    },
}

transfers, meta, err := client.Transfers.Transfers(ctx, filter)
if err != nil {
    return err
}

fmt.Println("Datapoints remaining:", meta.IntelDatapointsRemaining)

This style has a useful maintenance benefit: intent is obvious at the call site. A reviewer can see the requested chains, flow direction, time range, and sorting policy without having to reconstruct a URL. The library also validates relevant options; for example, the documented transfer filter rules prevent mixing TimeLast with TimeGte or TimeLte. 1

The service surface is broad enough to keep related capabilities inside one client. According to the project documentation, the client exposes services for intelligence, balances, chains, counterparties, historical flows and balances, loans, market data, portfolio snapshots, risk, swaps, tokens, transfers, transactions, users, subscriptions, analytics, and WebSocket streams, among other areas. 1 Whether you are building a monitoring workflow, analytics pipeline, research tool, or internal operations dashboard, that unified structure reduces the need to invent a different integration pattern for every endpoint family.

Reliability should be the default

A thin API wrapper can send requests. A production-oriented SDK should also help callers deal with the response when it is not the one they wanted.

arkham-go accepts functional options for the base URL, timeout, retry count, retry delay, user agent, HTTP client, and logger. 1 This lets teams begin with a concise default client and move toward explicit operational controls as an integration grows.

client, err := arkham.NewClient(
    apiKey,
    arkham.WithTimeout(30*time.Second),
    arkham.WithMaxRetries(3),
    arkham.WithBaseDelay(500*time.Millisecond),
    arkham.WithUserAgent("wallet-monitor/1.0"),
)

The retry policy is intentionally selective. The README documents automatic retries for 429 and 5xx responses on GET requests, with Retry-After honoured when supplied. Mutating requests are not retried unless the SDK knows they are safe to repeat. 1 That distinction respects a basic reliability principle: retrying should improve resilience without quietly multiplying side effects.

Errors are similarly designed for normal Go control flow. Instead of forcing callers to compare incidental error strings, the library offers sentinel errors and a structured APIError. The familiar errors.Is and errors.As pattern remains available.

_, _, err := client.Intelligence.Address(ctx, "0xabc", nil)
if err != nil {
    if errors.Is(err, arkham.ErrRateLimited) {
        // Queue the work, apply a policy, or notify your scheduler.
        return err
    }

    var apiErr *arkham.APIError
    if errors.As(err, &apiErr) {
        log.Printf("API status=%d retry_after=%s", apiErr.StatusCode, apiErr.RetryAfter)
    }
    return err
}

The SDK also wraps transport failures and cancelled contexts in a way that preserves standard error inspection. 1 This matters because application-specific behaviour—such as telling a job runner to retry later or showing a clear error in an operator console—belongs in the application, but it depends on receiving dependable signals from the client.

Pagination without surprises

Offset pagination is easy to make look correct while silently requesting more data than a job can safely process. arkham-go exposes a Paginator for list endpoints that fetches one page at a time and lets the caller cap both the total item count and the number of page requests. It deliberately does not guess that a remote list is exhausted; callers stop when a decoded page is empty. 1

That is a refreshingly explicit contract. It makes resource limits visible in code and prevents hidden work from growing without bound.

pages := arkham.NewPaginator(
    ctx,
    client,
    "/transfers",
    query,
    100, // page size
    500, // maximum items requested; 0 is unlimited
    10,  // maximum requests; 0 is unlimited
)

for pages.HasNext() {
    var page []arkham.Transfer
    if _, err := pages.NextPage(&page); err != nil {
        return err
    }
    if len(page) == 0 {
        break
    }
    // Process the current page before asking for the next one.
}

For ETL-style tasks, backfills, and scheduled monitoring, this kind of control is more useful than a convenience abstraction that hides where the next API request will come from.

Real-time transfer streams, without a separate client

Some workflows cannot wait for the next polling interval. A monitoring service may need to react to qualifying transfers as they arrive. arkham-go includes WebSocket v2 stream management alongside its REST services: create a stream, connect to it, receive messages, reconnect if necessary, and delete the stream when the work is complete. 1

stream, _, err := client.Streams.Create(ctx, &arkham.CreateStreamV2Request{
    Base:   []string{"binance"},
    UsdGte: "500000",
})
if err != nil {
    return err
}

conn, err := client.Streams.Connect(ctx, stream.StreamID)
if err != nil {
    return err
}
defer conn.Close()
defer client.Streams.Delete(ctx, stream.StreamID)

for {
    message, err := conn.ReceiveTyped()
    if err != nil {
        return err
    }
    fmt.Println(message.Type, string(message.Payload))
}

The README documents reconnect support for interrupted connections within the API reactivation window, and it also notes that unused streams should be deleted. 1 Encapsulating this lifecycle within the same SDK is valuable: the real-time path remains consistent with the same authentication, error, context, and configuration conventions used by ordinary client calls.

A clean dependency story

arkham-go has no runtime dependencies outside the Go standard library. 1 For many teams, that is not a philosophical talking point; it is an operational advantage. Fewer dependencies can mean a smaller dependency review surface, simpler vendoring and builds, and less uncertainty when integrating the SDK into a service with strict deployment requirements.

The project is released under the MIT License, which makes it straightforward to evaluate and adopt in a wide range of codebases. 1 Its repository also includes runnable examples for intelligence, transfers, pagination, and WebSocket workflows, plus standard go test ./... and go vet ./... commands for contributors and evaluators. 1

Where to start

If your Go application needs Arkham API capabilities, begin by cloning the smallest possible integration: create a client, pass a context with a deadline, make one typed service call, and record the response metadata. From there, use typed filters as query needs grow, introduce bounded pagination for batch work, and move to a WebSocket v2 stream when the use case is genuinely real-time.

The value of arkham-go is not that it makes every integration decision for you. Its value is that it packages the repeatable, error-prone client work—request plumbing, typed models, retries, errors, pagination, usage metadata, and streams—into a Go-native interface. That leaves you with more time to build the part your users actually notice.

Explore the project, review the examples, and try it in your next Go service:

go get github.com/tigusigalpa/arkham-go

Repository: github.com/tigusigalpa/arkham-go

References

Stop Fighting Generated Code: Introducing a Hand-Crafted Go SDK for KuCoin

Igor — Sun, 09 Aug 2026 12:58:39 +0000

Integrating an exchange API is rarely difficult because an endpoint is missing. It is difficult because the integration becomes part of a system that must behave predictably when the network is slow, when rate limits are reached, when API documentation is ambiguous, and when a number must retain every decimal place. In that environment, convenience wrappers can be expensive: a client that merely exposes every endpoint is not necessarily a client that feels safe to build upon.

That is the motivation behind kucoin-go, an unofficial Go client for KuCoin’s UTA (Unified Trading Account) and Classic API families. The project is built from scratch against KuCoin’s current documentation rather than as a wrapper over the official Universal SDK. Its goal is deliberately narrower: offer a consistent, idiomatic Go experience and expand endpoint coverage method by method, with tests and documentation keeping pace. 1

“We'd rather ship a small, correct surface than a large, half-tested one.” — kucoin-go project README 1

This is not a claim that generated SDKs have no place. If your application needs comprehensive KuCoin coverage immediately, the official client remains the sensible choice. kucoin-go is for Go developers who prefer an explicit, thoughtfully designed API surface—and who value being able to see precisely what is implemented today.

Why a smaller SDK can be a better foundation

An exchange client occupies an awkward but important boundary. On one side are remote API shapes, rate limits, account models, and authentication rules. On the other are your Go services, jobs, alerting pipeline, or trading logic. A useful SDK should make that boundary visible rather than hiding it behind generic types and optimistic defaults.

kucoin-go applies a few clear rules at that boundary. Network calls take a context.Context as their first argument, letting an application define cancellation and timeout behavior using standard Go mechanisms. The client can also receive an injected *http.Client, clock, and logger, which makes it easier to apply a house network policy in production and to write controlled tests. 1

The project keeps KuCoin’s two account models explicit. UTA and Classic expose different permissions, hosts, and response shapes, so the SDK does not flatten them into one misleading abstraction. The current UTA surface is accessed through client.UTA; the Classic service root is planned for later coverage. This distinction is especially helpful when an application needs to reason about which account model a request actually belongs to. 1

Design choice	What it means in practice	Why it matters
Context-first calls	Every network method begins with `context.Context`.	Request deadlines and cancellation stay under application control.
Explicit service roots	UTA and Classic are modeled as separate domains.	Account-specific permissions and payload differences are not blurred.
Injected dependencies	HTTP client, clock, logger, and retry policy are configurable.	Production behavior and testing can be tailored without forking the SDK.
Typed transport errors	Errors work with `errors.Is` and `errors.As`.	Code can branch on meaningful conditions instead of matching strings.

Treat money as data, not as a float

One of the most intentional choices in kucoin-go is deceptively simple: price, quantity, PnL, and fee fields are represented as strings at the transport boundary. 1

That may look less convenient than decoding directly into float64, but it is the correct friction for financial values. Binary floating-point numbers cannot represent many decimal fractions exactly. If a service receives an exchange value, performs arithmetic, and serializes it again, silent rounding can turn an apparently harmless conversion into a difficult reconciliation problem.

The library therefore preserves the value exactly as it arrives from the API and asks the application to choose an arithmetic type intentionally—for example, math/big.Rat or a decimal package. It is a small API design decision with a useful message: precision should be an explicit responsibility, never an accidental by-product of JSON unmarshalling.

Transport behavior designed for production realities

A clean Go method signature is only half of an SDK. What happens when the server rejects a call, sends a business-level error, or asks the caller to slow down matters just as much.

kucoin-go uses a shared transport executor that decodes response envelopes and exposes useful metadata, including the HTTP status, KuCoin business code and message, request ID, rate-limit headers, and server timing headers. The SDK’s error hierarchy is designed to be inspected with Go’s native error helpers rather than parsed as text. 1

_, err := client.UTA.Market.GetTickers(ctx, market.TradeTypeSpot, "BTC-USDT" )
if errors.Is(err, transport.ErrRateLimited) {
    // Apply the application's backoff strategy.
}

var apiErr *transport.KucoinError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.HTTPStatus, apiErr.Code, apiErr.Message)
}

Its retry policy is conservative by design. It applies exponential backoff with jitter only to GET requests and bounds the total retry window. Write operations are not automatically retried. That distinction is important: reissuing a data lookup after a transient failure may be safe; reissuing a request that places, cancels, or amends an order can create a duplicate-action problem. The project makes the safer default explicit and leaves idempotency decisions with the application. 1

Authentication follows the same philosophy. The library includes an independently implemented HMAC-SHA256 signer for KuCoin authentication headers and validates it with known-answer fixture vectors. The README also recommends obtaining credentials from environment variables or a secret store, using the minimum permission required, and restricting keys by IP where the exchange supports it. 1

Documentation that is checked, not merely written

Many SDK repositories start with a good endpoint table and gradually lose the race between code changes and documentation. kucoin-go tries to remove that failure mode.

Its endpoint reference is generated from an internal manifest, internal/endpoints.yaml. Contributors update the manifest, regenerate docs/ENDPOINTS.md, and CI rejects a change if the generated file differs from the committed version. In addition, each exported method must link to the exact KuCoin documentation page that it implements. 2

The practical result is a highly useful question to ask before starting an integration: does the method exist here today? Rather than inferring coverage from a roadmap or package name, a developer can consult a concise list of supported methods, their account mode, HTTP method, permission requirement, test location, and a direct upstream documentation link. 2

Current scope: the honest version

This is an early, pre-1.0 Phase 1 checkpoint. Today, kucoin-go implements and tests UTA Market functionality only. It does not yet implement UTA account, order, position, leverage, or transfer operations; Classic Spot, Margin, and Futures coverage; or any WebSocket client. 1

The current coverage map contains ten UTA Market methods. Most are public read operations, while order-book retrieval is a notable exception: development smoke testing showed that GetOrderBook requires authentication and the General permission, despite appearing public alongside similar market-data endpoints. The SDK documents that requirement rather than letting users discover it at runtime. 2

Available now	Notes
`GetInstruments`, `GetTickers`, `GetKlines`, `GetTrades`	UTA market discovery and trading-data retrieval.
`GetCurrencies`, `GetCurrency`, `GetServiceStatus`, `GetAnnouncements`, `GetTradeStatistics`	UTA market and platform information.
`GetOrderBook`	Supported, but requires credentials with the `General` permission. 2
WebSockets, order placement, transfers, Classic APIs	Not implemented yet. 1

That candor is a feature, not a disclaimer hidden at the bottom of the page. A library that makes its limits obvious allows developers to select it appropriately: it is ready to support UTA market-data integration and not ready to run a production order-execution workflow.

Quick start: fetch a ticker without API credentials

Public market-data calls offer the fastest way to evaluate the SDK. The repository requires Go 1.22 or later and installs with the standard command below. 1

go get github.com/tigusigalpa/kucoin-go

The following example retrieves the latest price for the BTC-USDT spot symbol. Because this call is public, the client can be created without credentials. 1

package main

import (
    "context"
    "fmt"
    "log"

    kucoin "github.com/tigusigalpa/kucoin-go"
    "github.com/tigusigalpa/kucoin-go/uta/market"
)

func main() {
    client := kucoin.NewClient()

    tickers, err := client.UTA.Market.GetTickers(
        context.Background(),
        market.TradeTypeSpot,
        "BTC-USDT",
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(tickers.List[0].LastPrice)
}

The example captures the intended ergonomics: the account model and domain are visible in the call path, request lifetime is represented by a context, and LastPrice remains an exact string until the application decides how to process it.

An invitation to shape the roadmap

The roadmap is organized around a reliable core first, then broader trading domains, then specialty capabilities such as funding, subaccounts, and additional KuCoin products. Contributions are welcome, particularly for a single missing REST endpoint accompanied by fixtures, tests, a documentation link, and an updated generated coverage entry. 1

If your project needs full API coverage now, start with the official SDK. If you need a compact Go client for UTA market data and want a codebase that favors clear constraints, typed boundaries, testability, and documentation fidelity, try kucoin-go.

Explore the repository, inspect the coverage map before integrating, and open an issue if the next endpoint on the roadmap is the one your project needs: github.com/tigusigalpa/kucoin-go.

kucoin-go is an unofficial community-maintained client. It is provided as-is and is not financial advice. Review the project’s security notice and test new integrations with least-privilege credentials before using them with funded accounts. 1

References

Introducing bitget-php: a production-grade PHP and Laravel SDK for Bitget UTA v3

Igor — Sun, 09 Aug 2026 09:21:11 +0000

PHP is a strong fit for dashboards, back-office systems, trading utilities, and event-driven services. Yet exchange integrations can still become the most fragile part of the stack. Developers must sign authenticated requests correctly, retain decimal precision, surface actionable API errors, and keep real-time connections healthy when a network or remote service interrupts them.

bitget-php is an open-source SDK that aims to make that boundary more dependable. It is a production-oriented PHP 8.2+ client for the Bitget Unified Trading Account (UTA) v3 API, with optional Laravel 10–13 integration. The project’s initial release focuses deliberately on a practical core: market data, account operations, trading operations, and a reconnecting WebSocket client. 1

The library is built for demo-first trading safety. Its own documentation recommends validating new code against Bitget demo credentials before connecting an application to a live account. 1

This article introduces the library from a developer’s perspective: what it covers today, how its design avoids several common integration pitfalls, and how it can become a stable starting point for a PHP-based Bitget integration.

The exchange-integration problem is more than HTTP

Calling an exchange endpoint may look like a simple POST or GET, but a production integration has a much wider responsibility. A client must consistently apply request signing, make error states intelligible to the application, avoid leaking API credentials through logs, and preserve the exact meaning of a decimal value. It also needs an operational model for real-time transport: what happens after a disconnect, and how does an application recover its subscriptions?

bitget-php addresses these concerns at the SDK layer. It uses Guzzle for HTTP transport and allows a GuzzleHttp\Client to be injected, which is helpful when testing, routing requests through a proxy, or applying project-specific transport configuration. It supports PSR-3 logging while using a no-op logger by default, and its documentation states that credentials are never logged. 1

Design concern	How `bitget-php` addresses it
Decimal values	Prices, quantities, PnL, and fee values are represented as strings rather than floats. 1
API failures	A typed exception hierarchy exposes specific application-level failure paths and the raw Bitget error code. 1
HTTP testing and customization	The Guzzle client is injectable instead of being fixed internally. 1
Observability	The SDK accepts a PSR-3 logger and defaults to `NullLogger`; credentials are not written to logs. 1
Real-time reliability	The WebSocket client maintains heartbeat handling, reconnection, and prior subscription recovery. 1
Framework flexibility	Laravel support is supplied without making Laravel a requirement for non-Laravel projects. 1

The approach to decimals deserves special attention. Binary floating-point values cannot precisely represent many decimal fractions, so silently converting exchange quantities or prices into PHP floats can change a value in ways that matter to accounting and order logic. By keeping API-facing numeric values as strings, the SDK leaves exact arithmetic under the developer’s control, including the option to use BCMath or another appropriate decimal strategy.

A modern PHP foundation without framework lock-in

The package requires PHP 8.2 or newer and uses strict typing throughout its codebase. It also uses readonly constructor properties, a small but important design choice that makes an object’s initialized dependencies harder to mutate accidentally. 1

Although the project offers first-class Laravel 10–13 conveniences—an auto-discovered service provider, publishable configuration, and a Bitget facade—the core SDK does not have a hard illuminate/* dependency outside of Laravel applications. 1 That distinction matters. A Laravel team can adopt the package with familiar configuration conventions, while a CLI worker, Symfony project, or framework-free PHP application can use the same client directly.

Installation is a single Composer command:

composer require tigusigalpa/bitget-php

For a Laravel application, credentials can live in configuration backed by environment variables. For a standalone service, they can be loaded through the project’s own secure configuration mechanism. In either case, API credentials should not be committed to source control or embedded into a front-end application.

Phase 1 REST coverage: the useful essentials

The project is transparent about its scope. Rather than implying that every endpoint in the Bitget UTA v3 surface is wrapped, it documents precisely which operations are included in Phase 1 and which are not. 2 That is a meaningful advantage for planning: teams can decide early whether the current surface matches their workflow rather than discovering a missing endpoint late in implementation.

Area	Supported SDK methods in Phase 1	Typical role
Public market data	`Market::getInstruments()`, `Market::getTickers()`, `Market::getOrderBook()`	Discover instruments, display prices, and obtain order-book data. 2
Private account operations	`Account::getAssets()`, `Account::getSettings()`, `Account::setLeverage()`	Read available assets and settings, then adjust leverage where supported. 2
Private trade operations	`Trade::placeOrder()`, `Trade::modifyOrder()`, `Trade::cancelOrder()`, `Trade::getOpenOrders()`, `Trade::getOrderHistory()`, `Trade::getPositions()`	Manage an order lifecycle and reconcile positions. 2

This is enough to support a well-defined first version of several products: a market-monitoring page, a controlled order-entry service, a bot that watches positions, or an internal trading-operations console. The SDK’s endpoint map also links every listed method to its corresponding Bitget API documentation, helping engineers trace an integration requirement from application code back to the exchange specification. 2

Equally important, the repository documents the current boundaries. In Phase 1, it does not include areas such as transfers, Trading Bot, Copy Trading, RFQ, Fiat, Finance/earn, batch orders, plan/trigger orders, or the other UTA v3 REST endpoints. 2 A reliable promotion should say this plainly: the library is a focused foundation, not an unsupported promise of complete coverage.

Safer order code starts in the demo environment

The project provides a direct demo-trading mode. When demoTrading: true—or the BITGET_DEMO=true setting—is used with Demo API credentials, REST requests include Bitget’s required paptrading: 1 header. The SDK also exposes demo public and private WebSocket URLs. 1

The following example follows the repository’s safety pattern. An order is both configured for demo trading and guarded by an explicit environment-variable opt-in. The intentionally distant limit price helps prevent an accidental fill during a test.

use Tigusigalpa\Bitget\Client;

$client = new Client(
    apiKey: config('bitget.api_key'),
    secretKey: config('bitget.secret_key'),
    passphrase: config('bitget.passphrase'),
    demoTrading: true,
);

// Do not send an order unless the explicit gate is enabled.
if (getenv('BITGET_ENABLE_TRADING') === '1') {
    $client->trade()->placeOrder([
        'category' => 'SPOT',
        'symbol' => 'BTCUSDT',
        'side' => 'buy',
        'orderType' => 'limit',
        'price' => '10000',
        'qty' => '0.001',
    ]);
}

That pattern does not replace testing, permissions management, risk limits, or review. It does, however, make the safer path easier to follow. A team can wire up application behavior in a simulated environment, exercise success and failure paths, and remove the deliberate gate only after it has made a conscious production decision.

Typed errors make recovery logic explicit

Exchange error handling should not collapse every failure into one generic exception. An invalid API key, a rate-limit response, insufficient funds, and an order lookup failure lead to very different recovery actions.

bitget-php exposes typed exceptions including AuthenticationException, RateLimitException, InvalidParameterException, InsufficientFundsException, and OrderNotFoundException. Each inherits from the SDK’s exception model and retains Bitget’s raw error code; a general BitgetException also gives access to the raw response. 1

use Tigusigalpa\Bitget\Exceptions\AuthenticationException;
use Tigusigalpa\Bitget\Exceptions\InsufficientFundsException;
use Tigusigalpa\Bitget\Exceptions\RateLimitException;
use Tigusigalpa\Bitget\Exceptions\BitgetException;

try {
    $client->trade()->placeOrder([/* order payload */]);
} catch (AuthenticationException $e) {
    // Rotate or correct credentials; do not retry blindly.
} catch (InsufficientFundsException $e) {
    // Notify the workflow that the required balance or margin is unavailable.
} catch (RateLimitException $e) {
    // Back off before retrying according to your application policy.
} catch (BitgetException $e) {
    // Record $e->bitgetCode and $e->rawResponse for diagnostics.
}

The value here is architectural. Application code can decide which failures are retriable, which should create an alert, and which should immediately stop a workflow. That leads to clearer observability and safer automation than a single catch-all branch.

Real-time data with reconnection built in

A WebSocket is often the right channel for reacting to market updates or private fill notifications, but it needs operational safeguards. The SDK’s WebsocketClient uses a pluggable ConnectionInterface. It ships with a synchronous textalk/websocket adapter, while projects using ReactPHP, Amp, or Laravel Octane can implement their own adapter for a non-blocking event loop. 1

Here is the documented shape of a public ticker subscription:

use Tigusigalpa\Bitget\WebsocketClient;

$ws = new WebsocketClient(WebsocketClient::DEFAULT_PUBLIC_URL);
$ws->connect();

$ws->subscribe([
    'instType' => 'SPOT',
    'topic' => 'ticker',
    'symbol' => 'BTCUSDT',
]);

$ws->listen(function (array $push) {
    echo json_encode($push), PHP_EOL;
});

listen() is a blocking call in the default synchronous transport. It responds to Bitget’s text-frame ping/pong heartbeat and, after an unexpected disconnection, reconnects with exponential backoff from one second to a 60-second cap before resubscribing every channel that was active. 1 This turns a raw socket connection into a more usable building block for long-running workers.

For private streams, credentials can be passed to the client constructor and connect() performs authentication. The repository includes a fast-fill example for UTA order-fill events. The subscription and listener are otherwise channel-agnostic, meaning a developer can subscribe to other Bitget channels by supplying the appropriate payload and decoding the returned array. The documentation is careful to distinguish that flexibility from endpoint-level support: beyond fast-fill, additional channel payloads are not separately wrapped or decoded by Phase 1. 1

A focused starting point for PHP teams

bitget-php is compelling because it concentrates on the reliability details that are easy to overlook: strings for API decimal fields, strict PHP conventions, injectable transport, typed exceptions, carefully handled logs, and a WebSocket client that tries to restore its prior state after a disconnect. It also does not conceal its roadmap. The public endpoint map makes current coverage visible and invites contributions to extend it. 1

If you are building a PHP or Laravel service around Bitget UTA v3, the library is worth evaluating in a demo environment first. Install it, inspect the endpoint map against your requirements, and use the documented examples to validate your authentication, error handling, and real-time design before any production rollout.

Visit the project on GitHub: tigusigalpa/bitget-php. Feedback, bug reports, and endpoint-coverage contributions are welcome through the repository. 1

This article is for software-development information only. It does not constitute investment, trading, or financial advice.

References

Introducing bitget-go: An Idiomatic Go SDK for Bitget UTA v3

Igor — Sun, 09 Aug 2026 06:33:12 +0000

Building a trading service in Go should mean spending time on execution logic, risk controls, and observability—not reimplementing request signatures, decoding generic JSON maps, or rebuilding WebSocket recovery loops for every project.

That is the problem bitget-go aims to solve. It is an open-source, idiomatic Go SDK for the Bitget Unified Trading Account (UTA) API v3, providing typed REST access to essential market, account, and trading operations alongside a reconnecting WebSocket client.1

The short version: bitget-go gives Go developers typed API models, context-aware network calls, exact string representations for financial values, and automatic WebSocket reconnection—while keeping the runtime dependency footprint intentionally small.1

This post looks at why those design decisions matter and how you can make your first request or stream market data in just a few lines of Go.

The friction behind a “simple” exchange integration

A raw exchange API integration tends to accumulate infrastructure code quickly. Authentication must match the exchange’s HMAC signing rules; query parameters and request bodies must be encoded exactly; remote errors need useful application-level handling; and persistent streaming connections need recovery after the inevitable network interruption. None of those concerns is the business logic of a trading system, but all of them can affect its reliability.

There is also a deceptively important data-modeling concern: numeric precision. Exchange payloads contain prices, quantities, PnL, and fees. Converting decimal values directly into binary float64 can introduce representation artifacts. For a trading application, it is often safer to preserve the exact wire value and perform arithmetic with math/big.Rat or a decimal package selected by the application.

bitget-go treats those operational details as first-class SDK responsibilities. It returns monetary and quantity fields as strings, exposes typed models rather than interface{}, and takes context.Context as the first argument of every network call.1

Common integration concern	How `bitget-go` addresses it
Request authentication	Signs REST requests and sets the required headers internally.1
Precision-sensitive values	Keeps prices, quantities, PnL, and fees as strings instead of coercing them to `float64`.1
Cancellations and deadlines	Accepts `context.Context` on every network call.1
Response parsing	Uses typed models and a generic `models.BitgetResponse[T]` envelope.1
Connection interruptions	Reconnects WebSockets with exponential backoff and restores subscriptions.1
Testability	Allows a custom `*http.Client` to be injected through functional options.1

The result is not a wrapper that hides Go’s standard idioms. Instead, it makes them central to the API.

A deliberately Go-native client

The SDK’s public surface is designed around conventions Go developers already expect. A REST client is constructed once, services are grouped by responsibility, and methods return typed values plus an error. If a caller cancels a context or its deadline expires, the cancellation flows through the request instead of being concealed behind a custom concurrency abstraction.1

The package also favors a lightweight dependency profile. According to its README, gorilla/websocket is the only required runtime dependency; stretchr/testify is used for tests.1 This is a sensible default for services where transparent dependency trees, quick builds, and straightforward vendoring matter.

Installation requires Go 1.21 or later and follows the usual Go module workflow:1

go get github.com/tigusigalpa/bitget-go

Your first REST request

The following example asks for the spot BTC/USDT ticker. Notice what is absent from the application: no manually constructed signature, no hand-written JSON response struct, and no float64 conversion for the reported last price.

package main

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

    bitget "github.com/tigusigalpa/bitget-go"
    "github.com/tigusigalpa/bitget-go/models"
 )

func main() {
    client := bitget.NewRestClient(
        os.Getenv("BITGET_API_KEY"),
        os.Getenv("BITGET_SECRET_KEY"),
        os.Getenv("BITGET_PASSPHRASE"),
    )

    tickers, err := client.Market.GetTickers(
        context.Background(),
        models.CategorySpot,
        "BTCUSDT",
    )
    if err != nil {
        log.Fatal(err)
    }

    if len(tickers) > 0 {
        fmt.Printf("BTC/USDT last price: %s\n", tickers[0].LastPrice)
    }
}

The client signs the request, applies the relevant headers, parses the exchange response, and delivers typed ticker data to the caller.1 For a production service, replace context.Background() with a context that has an intentional deadline, so an obsolete request does not outlive the trading decision that initiated it.

REST coverage for the first phase

The project is candid about its current scope: Phase 1 focuses on core REST services plus WebSockets rather than claiming total endpoint coverage. That makes the package particularly useful for projects that need a strong foundation for market observation, account state, and order lifecycle management today.1

Area	Available methods in Phase 1	Typical application use
Market	`GetInstruments`, `GetTickers`, `GetOrderBook`	Discover instruments, display prices, evaluate liquidity.1
Account	`GetAssets`, `GetSettings`, `SetLeverage`	Read balances and configuration; update leverage where appropriate.1
Trade	`PlaceOrder`, `ModifyOrder`, `CancelOrder`, `GetOpenOrders`, `GetOrderHistory`, `GetPositions`	Implement an order workflow and monitor its outcome.1

The repository’s endpoint documentation is the authoritative place to check precise paths, request parameters, and the status of individual models before you depend on an endpoint in production.2

WebSockets that recover instead of merely connect

REST is ideal for commands and snapshots; it is not the preferred path for a real-time ticker or execution feed. A reliable streaming client needs to plan for unexpected disconnections. bitget-go provides both public and private WebSocket clients and exposes incoming pushes through Go channels.1

Here is a minimal public ticker subscription:

ws := bitget.NewPublicWSClient()

if err := ws.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer ws.Close()

pushes, err := ws.Subscribe(ctx, models.WSArg{
    InstType: "SPOT",
    Topic:    "ticker",
    Symbol:   "BTCUSDT",
})
if err != nil {
    log.Fatal(err)
}

for push := range pushes {
    fmt.Println(string(push.Data))
}

For authenticated streams, create the client with NewPrivateWSClient(apiKey, secretKey, passphrase); authentication occurs during Connect.1 On an unexpected disconnect, the implementation retries with an exponential backoff beginning at one second and capped at 60 seconds, then resubscribes to channels opened earlier.1 The Phase 1 private channel is fast-fill; the same subscription and raw-data shape can be used for other available channels as the project expands.1

That recovery behavior is especially valuable in long-running worker processes. It reduces the amount of state-reconciliation code each consumer has to write, while still letting the application decide how it should process, persist, or validate the messages it receives.

Errors that work with the standard library

A good Go SDK should not force a bespoke error framework on its users. bitget-go returns regular Go errors: callers can use errors.Is with the package’s sentinel errors and errors.As to access a typed *BitgetError containing an API error code and message.1

_, err := client.Account.GetAssets(ctx)
if err != nil {
    if errors.Is(err, bitget.ErrUnauthorized) {
        log.Println("authentication failed — check credentials")
        return
    }

    var apiErr *bitget.BitgetError
    if errors.As(err, &apiErr) {
        log.Printf("Bitget error %s: %s", apiErr.Code, apiErr.Message)
        return
    }

    log.Printf("request failed: %v", err)
}

This small distinction improves operational handling. Authentication failures can be surfaced to configuration management, exchange business errors can be logged with their code, and network or timeout errors can follow a retry policy appropriate to the application.

Start with demo trading, not real funds

Trading code deserves a careful rollout. The SDK supports Bitget demo trading through bitget.WithDemoTrading(), which sends the paptrading: 1 header with REST requests.1 The included REST example additionally gates a trading action behind both BITGET_DEMO=1 and BITGET_ENABLE_TRADING=1, helping prevent accidental execution while exploring the codebase.1

client := bitget.NewRestClient(
    os.Getenv("BITGET_API_KEY"),
    os.Getenv("BITGET_SECRET_KEY"),
    os.Getenv("BITGET_PASSPHRASE"),
    bitget.WithDemoTrading(),
)

Important: Use demo API credentials when demo mode is enabled. The project documentation warns that combining demo mode with production credentials will fail.1

The client is also configurable without turning its constructor into a long, brittle parameter list. Functional options support a custom HTTP client, REST base URL, timeout, logger, locale, and demo mode.1 Injecting an *http.Client is particularly useful for tracing, proxies, custom TLS transport, and httptest-based unit tests.

client := bitget.NewRestClient(
    os.Getenv("BITGET_API_KEY" ),
    os.Getenv("BITGET_SECRET_KEY"),
    os.Getenv("BITGET_PASSPHRASE"),
    bitget.WithHTTPClient(&http.Client{
        Timeout:   30 * time.Second,
        Transport: myProxyTransport,
    } ),
    bitget.WithDemoTrading(),
)

The repository provides offline unit tests with go test ./... and optional demo-environment integration tests with go test -tags=integration ./... once demo credentials are configured.1

A practical foundation for Go trading systems

bitget-go does not attempt to prescribe a strategy, a database, or a trading architecture. Its value is more focused: it handles the exchange-integration mechanics so your application can keep ownership of the decisions that truly belong to it—risk limits, position sizing, persistence, monitoring, and execution policy.

The project is released under the MIT License and welcomes contributions, bug reports, and endpoint additions.1 If your stack also includes PHP or Laravel services, the author maintains a corresponding bitget-php SDK.1

If you are building Bitget UTA v3 integrations in Go, clone the repository, start with the runnable REST and WebSocket examples, and validate your workflow against demo credentials before any production rollout.

Repository: github.com/tigusigalpa/bitget-go

This SDK is not affiliated with Bitget. Trading involves risk; test carefully, protect API credentials, and never commit secrets to source control.

References

Building Robust Crypto Data Pipelines in PHP: Introducing the Token Terminal SDK

Igor — Sun, 09 Aug 2026 06:05:28 +0000

The cryptocurrency and decentralized finance ecosystems generate an overwhelming amount of data every single day. For developers building financial dashboards, algorithmic trading tools, or market research platforms, accessing clean, standardized, and reliable data is absolutely critical. Token Terminal has established itself as a premier provider of fundamental financial data for the crypto space, offering institutional-grade metrics across various blockchains and decentralized applications 1. However, integrating complex third-party APIs into enterprise PHP applications often requires writing significant amounts of boilerplate code to handle edge cases, rate limits, and unexpected response structures.

To solve this problem and streamline the developer experience, the PHP community now has access to a dedicated solution: the tokenterminal-php SDK. This new open-source package provides a robust, fully-typed, and developer-friendly PHP 8.1+ client for the Token Terminal API v2 2. Designed with modern PHP standards and framework integration in mind, it abstracts away the complexities of the underlying HTTP transport, allowing developers to focus entirely on building their applications rather than wrestling with API mechanics.

The Challenge of Integrating Financial APIs

When working with comprehensive financial data APIs like Token Terminal, developers frequently encounter several architectural challenges. First, there is the issue of rate limiting. Token Terminal enforces a strict limit of 1,000 requests per minute 3. When building data pipelines that ingest historical metrics across hundreds of assets, hitting this limit is practically guaranteed. A naive implementation will simply crash or drop data, requiring manual intervention.

Second, the cryptocurrency space moves rapidly. Projects frequently rebrand, merge, or migrate to new smart contracts. The Token Terminal API handles this gracefully by issuing HTTP 308 Permanent Redirects when a requested project ID has been renamed 3. However, standard HTTP clients often require explicit configuration to follow these redirects correctly while preserving the original request context and authentication headers.

Finally, there is the challenge of partial success. When requesting data for multiple metrics simultaneously, some metric IDs might be valid while others are deprecated or misspelled. A rigid API client might throw an exception and discard the entire response, forcing the developer to parse raw JSON to salvage the valid data. Building a robust client that gracefully handles these scenarios requires careful architectural planning and extensive testing.

Introducing the Token Terminal PHP SDK

The tokenterminal-php SDK was created specifically to address these integration challenges while providing a fluent, modern PHP interface. It acts as a comprehensive bridge between your PHP application and the Token Terminal infrastructure, ensuring that your data pipelines remain resilient and maintainable 2.

Comprehensive Endpoint Coverage

One of the primary strengths of the SDK is its complete coverage of the Token Terminal API v2. It supports all 24 documented endpoints out of the box. Whether you need to fetch a list of supported market sectors, retrieve deep financial statements for a specific decentralized protocol, or access specialized datasets like the crypto screener and insider transactions, the SDK provides a dedicated, strongly-typed method for the job.

API Domain	Available Data	Example SDK Method
Assets	Individual token metrics and historical data	`$client->assets()->historicalMetrics($id, $req)`
Projects	Protocol financial statements and aggregations	`$client->projects()->financialStatement($id, $req)`
Market Sectors	Categorized industry segments	`$client->marketSectors()->all()`
Metrics	Specific data points across the ecosystem	`$client->metrics()->data($id, $req)`
Datasets	Pre-compiled research and screening data	`$client->datasets()->cryptoScreener($req)`

Built for Resilience and Reliability

Reliability is paramount when dealing with financial data. The SDK implements sophisticated retry logic to ensure that transient network issues or rate limits do not disrupt your application flow. When the client encounters an HTTP 429 Too Many Requests response, or a 5xx server error, it automatically initiates a retry sequence using exponential backoff and jitter 2. Furthermore, it natively respects the Retry-After header provided by the Token Terminal API, ensuring that your application waits exactly as long as required before attempting the request again.

This resilience extends to how the SDK handles the aforementioned 308 redirects. If a project undergoes a rebranding and its identifier changes, the SDK transparently follows the redirect, retrieves the data using the new identifier, and returns the result to your application without requiring any code changes on your end.

Graceful Handling of Partial Success

Perhaps one of the most developer-friendly features of the tokenterminal-php package is its approach to partial success responses. When querying multiple metrics, Token Terminal may return valid data alongside an array of errors for the invalid parameters. Instead of throwing a generic exception and discarding the payload, the SDK encapsulates the response in an immutable TokenTerminalResult object.

This object allows developers to easily access both the successful data payload and the specific error details. You can iterate through the valid data to populate your database while simultaneously logging the errors for the invalid metric IDs, ensuring zero data loss during complex batch operations.

Getting Started with the SDK

Integrating the SDK into your project is straightforward. Because it relies on the PSR-18 standard for HTTP clients, it is highly decoupled and framework-agnostic. While Guzzle is provided as the default transport, you can easily substitute it with any PSR-18 compatible client of your choosing.

Installation is handled via Composer:

composer require tigusigalpa/tokenterminal-php

Once installed, initializing the client requires nothing more than your API key. You can instantiate it directly from your environment variables or build a custom configuration object.

use Tigusigalpa\TokenTerminal\TokenTerminalClient;

// Initialize the client using your API key
$client = TokenTerminalClient::make('your-api-key');

// Fetch all supported projects and iterate through the results
$result = $client->projects()->all();

foreach ($result->data() as $project) {
    echo $project['name'] . ' (ID: ' . $project['project_id'] . ")\n";
}

The configuration architecture is entirely immutable. If you need to adjust timeout settings or modify the retry behavior for a specific task, you can use the fluent with*() methods to generate a new configuration instance without altering the global state of your application.

Exception Handling

The SDK provides a granular exception hierarchy, allowing developers to catch and handle specific HTTP errors cleanly. Instead of parsing status codes manually, you can catch UnauthorizedException for invalid keys, RateLimitException for quota issues, or a general ApiException as a fallback.

use Tigusigalpa\TokenTerminal\Exceptions\RateLimitException;
use Tigusigalpa\TokenTerminal\Exceptions\NotFoundException;

try {
    $result = $client->projects()->get('uniswap');
} catch (RateLimitException $e) {
    // The SDK handles retries automatically, but if max attempts are exceeded:
    echo "Rate limit exceeded. Try again after: " . $e->getRetryAfter();
} catch (NotFoundException $e) {
    echo "Project not found in the Token Terminal registry.";
}

First-Class Laravel Integration

While the SDK is perfectly suited for vanilla PHP applications, it truly shines when integrated into the Laravel ecosystem. The package includes auto-discovery, meaning the service provider and facade are registered automatically upon installation.

Laravel developers can publish the configuration file to their config directory and manage their API credentials directly through the standard .env file. Once configured, accessing the Token Terminal API becomes as simple as calling the facade from anywhere in your application:

use Tigusigalpa\TokenTerminal\Laravel\Facades\TokenTerminal;

// Fetch the revenue breakdown for Uniswap
$metrics = TokenTerminal::projects()->metricAggregations('uniswap');

This zero-configuration approach significantly reduces the time to market for Laravel-based financial applications and analytics dashboards.

Conclusion

Building reliable data pipelines in the cryptocurrency space requires tools that can handle the unique challenges of the ecosystem. The tokenterminal-php SDK provides PHP developers with a powerful, resilient, and elegant solution for integrating Token Terminal's comprehensive financial data into their applications. By abstracting away rate limits, redirects, and complex error handling, it allows you to focus on extracting insights and delivering value to your users.

If you are building data-driven applications in PHP, we highly encourage you to explore the package. You can view the source code, read the extensive documentation, and contribute to the project on GitHub.

Explore the repository: tigusigalpa/tokenterminal-php on GitHub

References

Build Resilient Web3 Data Pipelines in Go with tokenterminal-go

Igor — Wed, 05 Aug 2026 12:32:12 +0000

When a Go application needs on-chain and protocol-level data, the HTTP request itself is usually the easy part. The difficult work starts afterward: defining request models, decoding inconsistent payloads, respecting rate limits, recovering from transient failures, and deciding what to do when one part of a multi-metric query succeeds while another part does not. Those concerns can quietly turn a small integration into a maintenance burden.

tokenterminal-go is an open-source, production-oriented Go SDK for Token Terminal API v2 that aims to remove that plumbing. The project supports all 24 documented API routes across Assets, Projects, Market Sectors, Metrics, and Datasets; it requires Go 1.21 or newer and uses only the Go standard library. 1 It is a focused choice for engineers building internal analytics services, data jobs, dashboards, research tooling, or any application that needs Token Terminal data without hand-rolling an HTTP client.

The practical promise: keep the integration idiomatic and type-aware, while the client handles the failure modes that normally appear only after an application reaches real traffic.

Why an SDK matters here

Token Terminal’s API gives programmatic access to its data, but it requires an API key and an API-enabled plan. 2 That makes the client layer part of the application’s operational surface: it needs to handle credentials, request timeouts, rate limits, pagination or filtering parameters where relevant, and failures that should not crash a larger data pipeline.

The library addresses these needs with a small, deliberate design. Its client methods take a context.Context, its response envelopes use generic Result[T] types, and its errors can be inspected with standard Go mechanisms such as errors.Is and errors.As. 1 In other words, callers can keep control of cancellation and business policy instead of receiving opaque, string-only errors.

Capability	What it means in practice	Why it is useful
Zero external dependencies	The package uses the standard library rather than adding third-party runtime packages. 1	A smaller dependency surface makes the SDK easier to audit, vendor, and upgrade.
Type-safe API models	Typed request structures and generic `Result[T]` envelopes are used across the client. 1	Editors provide better completion, and more mistakes are caught before a request is sent.
Context-aware calls	Every client method accepts `context.Context`. 1	A service can enforce deadlines or stop in-flight work when a request is cancelled.
Retry with backoff	GET requests can be retried for rate limiting, server errors, and transient network failures. 1	Temporary failures are less likely to become application-visible outages.
Partial-success preservation	Valid `data` and API-supplied `errors` are both retained in the result. 1	A single invalid metric does not have to discard all usable data from the same response.
Concurrency-safe client	One `Client` may be shared safely across goroutines. 1	Parallel collection jobs do not need to create a separate client for each worker.

A fast path from API key to useful data

Installing the package follows the normal Go workflow:

go get github.com/tigusigalpa/tokenterminal-go

The client can be created with an API key, environment-driven configuration, or functional options. The repository documents options for the base URL, a custom HTTP client, timeout, retry count and delay, User-Agent, and opt-in POST retries. 1 The following example is adapted from the project’s historical-metrics example. It requests Uniswap fees and revenue on Ethereum for a specified time range, then prints any partial issues rather than throwing away the successful data. 3

package main

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

    tt "github.com/tigusigalpa/tokenterminal-go"
)

func main() {
    apiKey := os.Getenv("TOKEN_TERMINAL_API_KEY")
    if apiKey == "" {
        log.Fatal("TOKEN_TERMINAL_API_KEY is not set")
    }

    client, err := tt.NewClient(
        apiKey,
        tt.WithTimeout(15*time.Second),
        tt.WithRetry(3, time.Second),
    )
    if err != nil {
        log.Fatalf("create client: %v", err)
    }

    start, _ := tt.NewDate("2025-01-01")
    end, _ := tt.NewDate("2025-01-31")

    result, err := client.Projects.HistoricalMetrics(
        context.Background(),
        "uniswap",
        &tt.HistoricalMetricsParams{
            MetricIDs:      []string{"fees", "revenue"},
            ChainIDs:       []string{"ethereum"},
            Start:          &start,
            End:            &end,
            OrderDirection: tt.OrderAscending,
        },
    )
    if err != nil {
        log.Fatalf("load historical metrics: %v", err)
    }

    fmt.Printf("received %d data points\n", len(result.Data))
    for _, issue := range result.Errors {
        fmt.Printf("partial issue: %s %s=%s\n", issue.Code, issue.Field, issue.Value)
    }
}

This is the essential advantage of the SDK: the application code describes the question—which project, which chain, which metrics, which dates—rather than manually assembling URLs and decoding generic maps. The parameter structure makes filters explicit, while the Result object gives callers access to both the returned data and granular API feedback. 1

Coverage without a maze of wrappers

tokenterminal-go does not stop at a single “get metrics” helper. The repository’s endpoint coverage map groups the 24 routes into five service areas. 1 That makes the SDK suitable for broader workflows that need reference data, detailed time series, aggregates, and curated datasets in the same Go codebase.

Service area	Representative SDK methods	Typical use case
Assets	`client.Assets.List`, `Get`, `HistoricalMetrics`, `MetricsBreakdown`	Discover assets and examine an asset’s historical or aggregated metrics. 1
Projects	`client.Projects.List`, `Get`, `HistoricalMetrics`, `FinancialStatement`	Build protocol research pages, compare projects, or load financial statement data. 1
Market Sectors	`client.MarketSectors.List`, `Get`	Organize projects and assets by market sector. 1
Metrics	`client.Metrics.List`, `Data`, `Aggregations`, `Breakdown`	Query available metrics and retrieve detailed or summarized observations. 1
Datasets	`client.Datasets.CryptoScreener`, `CohortAnalysis`, `TrendingContracts`, and others	Start with curated screens and specialized analytical datasets. 1

This breadth matters because application needs evolve. A first version of a dashboard may list projects and draw one time series. A later version may need a screener, an aggregation view, or a financial-statement endpoint. With the same client abstraction across these areas, the transition does not require introducing a second API integration pattern.

Reliability is a feature, not an afterthought

A resilient client should have predictable behavior under pressure. By default, tokenterminal-go retries GET requests after HTTP 429 responses, 5xx responses, and transient network errors. It uses capped exponential backoff with jitter and honors a server-provided Retry-After header. POST retries are intentionally disabled unless the application explicitly enables them with WithRetryPOST(). Context cancellation stops retry waits immediately. 1

That policy is a strong default for data retrieval: reads are commonly safe to retry, while automatic retries of requests that may change server state deserve an explicit decision. It is also aligned with Token Terminal’s documentation, which calls out HTTP 429 as the rate-limit status that clients should handle. 4

The error model is equally practical. Instead of forcing consumers to compare error strings, the SDK exports sentinel values such as ErrUnauthorized, ErrNotFound, and ErrRateLimited, plus an *APIError that exposes structured details including status code, message, and retry information. 1 A caller can therefore implement a clear policy without coupling its business logic to the client’s internal wording.

if _, err := client.Projects.List(ctx); err != nil {
    switch {
    case errors.Is(err, tt.ErrUnauthorized):
        // Refresh configuration or surface a credential error.
        log.Println("check the Token Terminal API key")

    case errors.Is(err, tt.ErrRateLimited):
        var apiErr *tt.APIError
        if errors.As(err, &apiErr) {
            log.Printf("rate limited; retry after %s", apiErr.RetryAfter)
        }

    case errors.Is(err, tt.ErrNotFound):
        log.Println("project, asset, or metric was not found")

    default:
        log.Printf("Token Terminal request failed: %v", err)
    }
}

The SDK also follows HTTP 308 redirects, which the project documents as a way to handle project or asset renames transparently. 1 That is the kind of edge case developers rarely enjoy discovering after a production identifier changes.

Preserve partial results instead of losing a whole response

One of the more thoughtful details in tokenterminal-go is its treatment of partial success. Some Token Terminal responses can contain valid data alongside an errors array. The SDK keeps both. 1 This matters when a query asks for several metrics, chains, or entities: one unsupported input should not automatically erase the observations that were returned successfully.

A production workflow can turn this into a useful policy. Persist result.Data, emit structured logs or metrics for result.Errors, and alert only when the missing values break a required business rule. This approach is more robust than treating every non-empty error array as a total failure, and it gives downstream consumers a transparent view of data completeness.

Pair the SDK with Token Terminal’s API guidance

The SDK gives Go applications a sound transport and type layer; efficient data architecture is still the caller’s responsibility. Token Terminal recommends maintaining an up-to-date cache or index for /projects and /metrics, refreshing it daily or weekly according to the application’s needs. 4

“Maintain an up-to-date cache of projects and metrics.” — Token Terminal API best practices 4

That guidance fits naturally with tokenterminal-go. Fetch the project and metric catalogs on a schedule that matches your product, store them in your preferred cache or database, and use those local records to validate user-selected identifiers before issuing more focused API calls. The SDK intentionally does not impose an invisible persistent cache; the repository documents an optional integration point so an application can choose its own caching strategy. 1

For aggregate questions, Token Terminal also advises using the Breakdown API instead of first downloading a time series and aggregating it client-side. According to the official guidance, that can reduce transferred data and improve response time. 4 In the SDK, the relevant methods are exposed as client.Metrics.Breakdown and client.Assets.MetricsBreakdown, so the optimization is available without abandoning the same typed client model. 1

Built for normal Go engineering practices

The project includes dedicated examples for basics, historical project metrics, metric breakdowns, datasets, error handling, and concurrent calls. 1 It also documents conventional validation commands, including go test ./... -v, go test -race ./..., gofmt -l ., and go vet ./.... Its tests use httptest.Server rather than calling the live Token Terminal API. 1 That is a welcome design choice for teams that want deterministic tests and no hidden network dependency in their CI pipelines.

The package is published under the MIT license, so it is straightforward to evaluate and incorporate into an appropriate open-source or commercial Go project. 1

Give your Go code the API client it deserves

Reliable Web3 analytics infrastructure is not just about obtaining the right endpoint. It is about handling latency, retries, cancellation, redirects, structured errors, partial results, and concurrent workload patterns without distracting from the product you are actually building.

tokenterminal-go packages those operational details into a concise, zero-dependency SDK for Token Terminal API v2. If your Go service needs project metrics, asset data, sector information, or specialized datasets, it is worth exploring the repository, running the examples, and adapting the client to your own pipeline.

Start here: github.com/tigusigalpa/tokenterminal-go. If the SDK saves your team implementation time, consider starring the project, opening an issue with feedback, or contributing an improvement.

References

Stop Hand-Rolling HTTP Clients for Glassnode: Meet glassnode-go

Igor — Fri, 31 Jul 2026 11:50:23 +0000

Building with on-chain data is exciting right up until the integration work begins. A dashboard, research tool, alerting service, or backtesting pipeline may start with one metric, but it rarely stops there. Soon you are assembling request URLs by hand, decoding JSON into map[string]interface{}, checking every response for rate-limit headers, and adding retry logic that you hope will not become the next production incident.

That glue code is necessary, but it is not where a product becomes valuable. glassnode-go is designed to move that plumbing out of the way. It is an unofficial, community-built Go SDK for the Glassnode Basic API, aimed at developers who want a more idiomatic and production-oriented integration layer. It is not affiliated with or endorsed by Glassnode; it is a focused tool for teams that would rather build with on-chain data than continually maintain HTTP wrappers around it. 1

“A dependency-light, production-oriented Go module for the Glassnode Basic API, built with the kind of care you'd want from a library you depend on every day.” — the glassnode-go project README 1

The problem is not fetching a number—it's operating the integration

A raw API integration can fetch a price just fine. The difficult part begins when the application has to do it reliably: propagate cancellations through context.Context, protect the API key, distinguish bad input from an exhausted quota, tune timeouts, and retrieve multiple metrics concurrently without turning the client layer into a fragile tangle of helpers.

glassnode-go approaches that problem with a deliberately Go-native design. The module targets Go 1.21+ and declares no third-party module dependencies, keeping the integration limited to the standard library rather than adding transitive packages to the project. 1 Its client uses functional options for configuration, supports custom HTTP transports, and is documented as safe for concurrent use across goroutines. 1

What a data service needs	What `glassnode-go` provides	Why it matters
Familiar, discoverable access to standard metrics	25 typed category services such as `Market`, `Addresses`, `Indicators`, `Mining`, and `Transactions`	Code is easier to navigate, review, and autocomplete. 1
A way to reach newly introduced or unusual endpoints	A generic `MetricsService` for raw JSON, scalar time series, and object time series	You do not have to wait for a typed wrapper to start experimenting. 1
Clarity before making requests	Runtime metadata methods for assets, metric paths, and supported parameters	Fewer invalid requests and less guesswork around endpoint capabilities. 1
Resilience under load	Automatic handling of HTTP 429 responses and configurable retry behavior	Rate-limit logic stays centralized instead of leaking into every call site. 1
Safer operations	Header-based API-key authentication by default and redaction in URLs and error messages	Secrets are less likely to appear in logs and diagnostics. 1

Start with a useful result, not a pile of boilerplate

Installation is a familiar Go command:

go get github.com/tigusigalpa/glassnode-go

The quick-start experience is intentionally small. Put your Glassnode API key in GLASSNODE_API_KEY, create the client from the environment, and request the metric through a typed service. The following example retrieves BTC price data at daily resolution. 1

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    client, err := glassnode.NewClientFromEnv()
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    price, err := client.Market.Price(ctx, &glassnode.MetricQuery{
        Asset:      "BTC",
        Resolution: glassnode.Resolution24h,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, point := range price {
        fmt.Printf("BTC price at %d: $%.2f\n", point.T, point.V)
    }
}

The important detail is not merely that the example is short. It encodes a useful boundary: application code talks in terms of market data and queries, while the SDK takes responsibility for building the request, applying authentication, decoding the response, and returning a typed time series. That separation makes a dashboard handler, scheduled research job, or backtest easier to test and evolve.

Typed when you can; generic when you need to

The primary API surface is made of category services that mirror Glassnode's documented endpoint families. For example, a dashboard can request OHLC data from client.Market.PriceOHLC, activity data from client.Addresses.ActiveCount, and an indicator such as SOPR from client.Indicators.SOPR. The repository maintains an endpoint-coverage document that maps API paths to the corresponding SDK methods. 1

But strongly typed wrappers should never become a release-cycle bottleneck. APIs evolve, new metrics appear, and some response shapes are inherently specialized. For those moments, glassnode-go supplies the generic MetricsService. It can return raw JSON through Get, scalar time-series data through GetTimePoints, or object time-series data through GetObjectPoints. 1

// Use a valid metric path even when you do not need a dedicated convenience method.
data, err := client.Metrics.GetTimePoints(ctx, "/indicators/sopr", &glassnode.MetricQuery{
    Asset:      "BTC",
    Resolution: glassnode.Resolution24h,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Received %d SOPR observations\n", len(data))

That combination is especially useful in real products. Your stable, frequently used calls can remain concise and self-documenting; exploratory work, internal analytics, and recently introduced paths can still proceed without compromising the client architecture.

Discover capabilities before you spend requests

Metric paths alone do not tell the whole story. A query may support different resolutions, assets, bulk access, currencies, or time formats depending on the underlying endpoint. Guessing at those parameters often results in failed calls that are hard to diagnose in a busy service.

glassnode-go exposes a metadata layer for exactly this reason. The MetadataService can list supported assets, discover metric paths, and inspect a metric's available parameters at runtime. The SDK documentation recommends this metadata-first workflow before making data calls. 1

metric, err := client.Metadata.Metric(ctx, "/market/price_usd")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Metric: %s\n", metric.Description)
fmt.Printf("Supported resolutions: %v\n", metric.Resolutions)

For a product team, this is more than a convenience. It lets a configuration screen, query builder, or data pipeline validate its choices against the API instead of embedding assumptions that eventually become stale.

Rate limits deserve first-class engineering

A high-quality SDK should make the correct behavior the default behavior. In glassnode-go, HTTP 429 responses trigger automatic retries for idempotent GET requests. The client uses the x-rate-limit-reset header when the server supplies it and falls back to exponential backoff when it does not. It avoids retrying 400, 401, and 404 responses because those represent problems a retry is unlikely to fix. Retry behavior can be configured with WithRetry. 1

This decision is quietly powerful. Every endpoint call retains the same clean shape, while the behavior that protects the service is standardized in one place. When the retry budget is exhausted, the caller still gets actionable context through the exported APIError type and the ErrRateLimited sentinel. 1

_, err := client.Indicators.SOPR(ctx, &glassnode.MetricQuery{Asset: "BTC"})
if err != nil && errors.Is(err, glassnode.ErrRateLimited) {
    var apiErr *glassnode.APIError
    if errors.As(err, &apiErr) {
        log.Printf("Rate limit exhausted; reset in %ds", apiErr.RateLimitReset)
    }
}

The same philosophy applies to the rest of the error model. The package exposes sentinel errors for conditions such as bad requests, unauthorized access, missing metric paths, rate limits, and internal server errors. That gives callers the familiar errors.Is and errors.As workflow rather than forcing production code to branch on error-message strings. 1

Security should not be an afterthought

An API key is an operational secret, not a configuration string that belongs in source code or a query URL. The library defaults to the X-Api-Key header mode and supports query-string authentication only as an explicit opt-in for exceptional environments. It also documents API-key redaction in URLs, response metadata, and error messages. 1

The recommended developer experience is therefore straightforward: keep the key in GLASSNODE_API_KEY, construct the client with NewClientFromEnv(), and let the client carry the secret in headers. It is a small convention with a meaningful payoff in log hygiene and incident response.

Built for dashboards today—and historical research tomorrow

The SDK is not limited to a single-metric dashboard. Its BulkQuery support can request data for explicitly specified multiple assets in one call, reducing round trips where the underlying metric supports bulk access. The project documentation also notes that the cost model remains per asset, so bulk requests optimize throughput rather than magically reducing credit consumption. 1

For researchers, the Point-in-Time API is another standout capability. PIT response models preserve a computed_at timestamp alongside the observation timestamp. This matters when historical metric values may later be revised: a backtest can distinguish what the current dataset says from what was known at a particular historical moment. The SDK offers typed PIT response models and generic point-in-time methods for that workflow. 1

Use case	A practical `glassnode-go` path
Market dashboard	Typed `Market`, `Indicators`, and `Addresses` services for the metrics displayed most often. 1
Multi-asset research job	`Metrics.GetBulk` with explicit asset lists, plus metadata checks before the request. 1
API explorer or no-code query builder	`Metadata.Assets`, `Metadata.Metrics`, and `Metadata.Metric` to populate valid options dynamically. 1
Strategy backtesting	Point-in-Time response models that retain `computed_at` for historically aware analysis. 1
Custom or newly added endpoint	`Metrics.Get`, `GetTimePoints`, or `GetObjectPoints` with a valid metric path. 1

The developer experience is the feature

glassnode-go does not try to hide Glassnode behind a proprietary abstraction. Instead, it gives Go developers a reliable, conventional way to work with the Basic API: typed services for everyday endpoints, generic access when flexibility is needed, metadata for discovery, and production-minded defaults for context propagation, concurrency, security, and retries. The project's initial v1.0.0 release documents these capabilities along with typed response models, configurable transport options, and a mocked-transport test suite. 2

If your next Go project needs on-chain metrics, take the SDK for a spin, browse the examples, and consider contributing an issue, documentation improvement, or pull request. The repository is MIT licensed and welcomes contributions. 1

Repository: github.com/tigusigalpa/glassnode-go

Note: This post discusses developer tooling for accessing data. It is not investment, trading, or financial advice.