> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go client

> Call the 0xinsider API from Go with typed responses, request deadlines, and a keyless sandbox.

Use `github.com/0xinsider/0xinsider-go` to call the API from a Go program. Each operation has a typed `...WithResponse` method. The [source repository](https://github.com/0xinsider/0xinsider-go) contains the generated types and request helpers.

## Install

```bash theme={null}
go get github.com/0xinsider/0xinsider-go
```

You need Go 1.26.5 or newer. The client uses `github.com/oapi-codegen/runtime`.

<span id="run-it-without-a-key" />

## Make a request without a key

Start with example data from the [sandbox](/sandbox). You do not need an account or a credential.

```go theme={null}
package main

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

	oxinsider "github.com/0xinsider/0xinsider-go"
)

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

	client, err := oxinsider.New(oxinsider.WithBaseURL("https://0xinsider.com/sandbox"))
	if err != nil {
		log.Fatal(err)
	}

	limit := 5
	resp, err := client.ListLeaderboardWithResponse(ctx, &oxinsider.ListLeaderboardParams{Limit: &limit})
	if err != nil {
		log.Fatal(err)
	}
	if resp.JSON200 == nil {
		log.Fatalf("HTTP %d: %s", resp.StatusCode(), resp.Body)
	}

	for _, entry := range resp.JSON200.Data {
		grade := "ungraded"
		if entry.Grade != nil {
			grade = *entry.Grade
		}
		fmt.Println(entry.Address, grade)
	}
}
```

`WithBaseURL("https://0xinsider.com/sandbox")` sends requests to the sandbox. Supported operations return their documented examples. See the sandbox page for exceptions and the `sandbox_status` query parameter for error examples.

<span id="then-live-data" />

## Switch to live data

Import `os` and replace the sandbox client with:

```go theme={null}
client, err := oxinsider.New(oxinsider.WithBearerToken(os.Getenv("OXINSIDER_API_KEY")))
```

Set `OXINSIDER_API_KEY` in your environment first. The client does not read that variable itself; the example passes its value to `WithBearerToken`.

`WithBearerToken` accepts an API key (`oxi_sk_live_...`) or an OAuth access token (`oxi_at_...`). The default API origin is `https://api.0xinsider.com`. Live data requires an active Pro or Max subscription; the [public routes](/authentication#what-needs-a-key) work without a token.

<span id="reading-a-response" />

## Read the response

The HTTP status selects the response field: `JSON200` contains a decoded `200` body, `JSON201` contains a decoded `201` body, and other fields work the same way. Those fields are `nil` for a different status. Always check before you use one.

```go theme={null}
if resp.JSON200 == nil {
	log.Fatalf("HTTP %d: %s", resp.StatusCode(), resp.Body)
}
```

`Body` contains the raw response bytes, and `StatusCode()` returns the HTTP status. Read the API's `error.code` and `error.reason` when the response is an error; [Errors](/errors) explains the possible values.

Optional fields are pointers. A `nil` `Grade` means that no grade was returned. It does not mean the wallet has an F grade or a zero value.

<span id="keep-financial-values-exact" />

## Keep money values exact

Trader and position responses can include an `exact` block with decimal values stored as strings. Use these values for arithmetic when they are available. Parse them directly into `math/big.Rat` or another decimal type, without converting through `float64`.

```go theme={null}
import (
	"fmt"
	"math/big"
)

func exactRat(value string) (*big.Rat, error) {
	rat, ok := new(big.Rat).SetString(value)
	if !ok {
		return nil, fmt.Errorf("invalid exact decimal %q", value)
	}
	return rat, nil
}

// After a successful typed get-trader or list-positions call:
// rat, err := exactRat(atom.Value)
// total := new(big.Rat).Add(rat, new(big.Rat).SetInt64(1))
// fmt.Println(total.FloatString(6))
```

Each exact value also records its `Unit`, `Scale`, and `Basis`. The block or one of its fields can be absent when the source value is unavailable. Report that absence instead of substituting zero.

<span id="deadlines" />

## Set a deadline

Ordinary requests have a 30-second default deadline. Export downloads have a 5-minute default deadline. The default transport also limits connection, TLS handshake, and response-header waits.

```go theme={null}
client, err := oxinsider.New(
	oxinsider.WithBearerToken(os.Getenv("OXINSIDER_API_KEY")),
	oxinsider.WithRequestTimeout(5*time.Second),
)
```

A context with a deadline keeps the deadline you supplied. Use a shorter one for a request that must finish sooner. `WithRequestTimeout(0)` removes the client's total request deadline but keeps the transport's connection limits.

A deadline added by the client returns `*oxinsider.RequestTimeoutError`. It includes `Deadline`, `Method`, and `URL`, unwraps to `context.DeadlineExceeded`, and implements `Timeout() bool`. A deadline you supplied returns the context's own error.

The [event stream](/api-reference/endpoint/get-stream) has no total request deadline. Read it with `OpenStream`, which uses separate start and idle timeouts. Do not use the generated `GetStreamWithResponse`: it would try to read the entire stream before returning. For a finite stream task, pass a context deadline to `OpenStream` and call `reader.Close()` when finished.

<span id="credential-safety" />

## Protect the credential

Credentialed requests require HTTPS. HTTP is allowed only for a loopback development host.

An insecure destination or a redirect that downgrades the request returns `*oxinsider.InsecureTransportError` before the credential is sent. The error identifies the destination without including the token.

<span id="which-document-a-release-implements" />

## Check which API version you have

The package records the OpenAPI document used to generate it:

```go theme={null}
oxinsider.Version        // the client release
oxinsider.OperationCount // operations in that release's document
oxinsider.OpenAPISHA256  // SHA-256 of that document
oxinsider.AppCommit      // app commit that last changed the document
```

Compare `OpenAPISHA256` with the SHA-256 of the [published OpenAPI document](https://0xinsider.com/api/v1/openapi.json). A difference means the documents differ; check the [changelog](/changelog) for the changes and upgrade when you need them.

<span id="what-this-client-does-not-do" />

<span id="go-next" />

## Limits

* The client does not retry failed requests. Handle `429`, `503`, and other failures in your application.
* It does not place Polymarket orders or hold a wallet key.
* Webhook and export operations can change resources on your 0xinsider account.
* Round values only when displaying them. Missing values remain missing.

Read [Authentication](/authentication) to create a live key, or [Quickstart](/quickstart) for common API calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.