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

# Go SDK

> Install the Go client for the Rails API and make your first request.

The Go SDK is the client for the Perpetuals and Options APIs. Orders go over the WebSocket; reads go over HTTP. It takes care of the connection, session and token plumbing listed below, so your code deals with orders and streams.

<Note>
  This page covers the SDK itself. What an endpoint or stream does, and what its fields mean, is documented in each product's guides and API reference, which apply to the SDK unchanged.
</Note>

## What the SDK Handles

* **Access tokens.** The client exchanges your API key for an [Access Token](/latest/authorization#access-token) when it first needs one, caches it, and refreshes it before it expires.
* **Connections.** It opens the WebSocket, keeps it alive with pings, and reconnects with backoff that stays within the exchange's connection limits, including a soft ban.
* **Sessions.** Each connection keeps its [session](/latest/websocket-session) across reconnects, so order events missed while it was down are replayed.
* **Orders.** Every order command over the WebSocket waits for the exchange's answer and reports how long the acknowledgment and the answer took. Each carries a `clientRequestId`; the SDK generates one for a request that doesn't set its own.
* **Rate limits.** The rate limits the exchange reports reach you as errors, with how long to wait. An optional [pacer](/latest/go-sdk/configuration#pacing) keeps calls under your account's budget before they are sent.

## Install

```bash theme={null}
go get github.com/rails-xyz/exchange-go-sdk
```

The SDK requires Go 1.25 or later and follows [semantic versioning](https://semver.org/); every release is listed in the [changelog](https://github.com/rails-xyz/exchange-go-sdk/blob/main/CHANGELOG.md). It has three packages:

| Package | Contains |
| - | - |
| `rails` | What both products share: credentials, environments, configuration options, errors, and hooks. |
| `perps` | The Perpetuals client. |
| `options` | The Options client. |

## Credentials and Environments

A client takes an [API key](/latest/api-keys) and its secret. Everything else is an option:

```go theme={null}
client, err := perps.NewClient(rails.Credentials{
	APIKey:    os.Getenv("RAILS_API_KEY"),
	APISecret: os.Getenv("RAILS_API_SECRET"),
})
if err != nil {
	return err
}
defer client.Close()
```

The client connects to Production. To use the [Sandbox](/latest/environments), pass its environment, with `creds` the credentials above:

```go theme={null}
client, err := perps.NewClient(creds, rails.WithEnvironment(rails.Sandbox()))
```

The examples in these docs leave the environment out.

## Next Steps

<CardGroup cols={2}>
  <Card title="Perpetuals quickstart" icon="chart-line" href="/latest/perps/go-sdk/quickstart">
    Place and cancel a perpetuals order in one short program.
  </Card>

  <Card title="Options quickstart" icon="layer-group" href="/latest/options/go-sdk/quickstart">
    Find a contract, then place and cancel an order on it.
  </Card>
</CardGroup>

* [Configuration](/latest/go-sdk/configuration) and [Errors and Retries](/latest/go-sdk/errors)
* [Source on GitHub](https://github.com/rails-xyz/exchange-go-sdk)
* [Package reference on pkg.go.dev](https://pkg.go.dev/github.com/rails-xyz/exchange-go-sdk)


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