Repository navigation
Home
nansen-go is an idiomatic Go client for the Nansen AI API. It is designed to feel like the rest of your Go code: no third-party dependencies, full context support, and a clean, functional options API. The entire library is built on the Go standard library — go get it and you are done, with no dependency tree to audit.
The library was written with a few explicit goals in mind. Every API call accepts a context.Context as its first argument, so timeouts and cancellation work exactly the way you would expect in any Go program. The client is configured via functional options (WithBaseURL, WithHTTPClient, WithTimeout, WithRetry) rather than a configuration struct, which makes partial configuration natural and avoids zero-value ambiguity. The client itself is safe to share across goroutines with no additional locking required.
Type safety is a first-class concern. Blockchain identifiers, sort fields, trader types, and Smart Money labels are all defined as typed constants rather than raw strings, so the compiler catches mistakes before they reach the API. Optional request fields are represented as pointers, which means a stray false or 0 is never silently serialised into your JSON payload.
Error handling is designed to be actionable. Every API failure is returned as an *APIError that carries the HTTP status code, the decoded error message, the raw response body, and the full set of response headers — including rate-limit information. Sentinel errors (ErrRateLimited, ErrUnauthorized, ErrNotFound, etc.) allow you to branch on the kind of failure using the standard errors.Is pattern.
Retries are opt-in. When you call WithRetry, the client automatically backs off on 429 Too Many Requests responses, honouring Retry-After, RateLimit-Reset, and X-RateLimit-Reset headers. It also retries transient 5xx errors and flaky network failures, provided the context has not been cancelled. The timeout budget you set covers all retry attempts together, not each one individually.
| Section | Description |
|---|---|
| Quick Start | Install the package and make your first API call. |
| Configuration | All available client options and their defaults. |
| Smart Money | Netflows, holdings, and DEX trades for smart money wallets. |
| Token God Mode | Token screener, flow intelligence, and who-bought-sold data. |
| Profiler | Current balances and DEX trade history for a wallet address. |
| Portfolio | DeFi holdings for a wallet address. |
| Historical | Backtesting endpoints for historical token flow and smart money balances. |
| Error Handling & Retries | How to inspect errors, use sentinels, and configure retries. |
| Models & Pointers | Typed constants, pointer helpers, and common request/response types. |
The source code is available at github.com/tigusigalpa/nansen-go. The package is licensed under the MIT License.