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.
Top comments (0)