> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.
# Go SDK
> Official Go SDK for the Limitless Exchange API
## Overview
The Limitless Exchange Go SDK (`limitless-exchange-go-sdk`) is a fully typed Go client for interacting with both **CLOB** and **NegRisk** prediction markets. It provides:
* Strongly typed structs for all API requests and responses
* Automatic venue caching for EIP-712 order signing
* Built-in retry logic with exponential backoff (using Go generics)
* WebSocket streaming with auto-reconnect
* Functional options pattern for flexible configuration
The SDK requires **Go 1.22+**. All I/O methods accept a `context.Context` as the first parameter and return `error` as the last return value, following standard Go conventions.
## Installation
```bash theme={null}
go get github.com/limitless-labs-group/limitless-exchange-go-sdk@latest
```
## Quick Start
```go theme={null}
package main
import (
"context"
"fmt"
"os"
limitless "github.com/limitless-labs-group/limitless-exchange-go-sdk/limitless"
)
func main() {
client := limitless.NewHttpClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
)
}
```
```go theme={null}
func main() {
client := limitless.NewHttpClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
)
marketFetcher := limitless.NewMarketFetcher(client)
ctx := context.Background()
result, err := marketFetcher.GetActiveMarkets(ctx, &limitless.ActiveMarketsParams{
Limit: 10,
Page: 1,
})
if err != nil {
panic(err)
}
for _, m := range result.Data {
fmt.Println(m.Title, m.Slug)
}
}
```
```go theme={null}
func main() {
client := limitless.NewHttpClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
)
portfolio := limitless.NewPortfolioFetcher(client)
ctx := context.Background()
positions, err := portfolio.GetPositions(ctx)
if err != nil {
panic(err)
}
for _, pos := range positions.CLOB {
fmt.Println(pos.Market.Title)
}
}
```
## Authentication
Authentication uses scoped API tokens with HMAC-SHA256 request signing. A scoped API token is a **token ID** plus a one-time **secret**, generated at [limitless.exchange](https://limitless.exchange) → profile menu → Api keys.
* HMAC headers `lmts-api-key`, `lmts-timestamp`, `lmts-signature` — the SDK builds and signs them for you when you pass HMAC credentials
Store the token ID and secret in your environment, then pass them as HMAC credentials:
```bash theme={null}
export LMTS_TOKEN_ID="your-token-id"
export LMTS_TOKEN_SECRET="your-base64-secret"
```
```go theme={null}
client := limitless.NewHttpClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
)
```
Set the `LIMITLESS_API_KEY` environment variable and the `HttpClient` loads it automatically, or pass it explicitly with `WithAPIKey`:
```bash theme={null}
export LIMITLESS_API_KEY="lmts_your_key_here"
```
```go theme={null}
client := limitless.NewHttpClient() // auto-loads LIMITLESS_API_KEY
// Or pass it explicitly:
client = limitless.NewHttpClient(
limitless.WithAPIKey("lmts_your_key_here"),
)
```
With `WithHMACCredentials(...)` set, the SDK automatically generates and sends `lmts-api-key`, `lmts-timestamp`, and `lmts-signature`. Do not manually build HMAC headers when using the SDK client.
**Legacy:** an older API key (`LIMITLESS_API_KEY`, sent as the `X-API-Key` header) still works but is not recommended for new integrations. Prefer a scoped API token.
Never hardcode API keys in source code or commit them to version control. Use environment variables or a secrets manager.
## Root Client
The recommended entrypoint is the root `Client`, which composes all domain services (markets, portfolio, orders, API tokens, partner accounts, delegated orders). Authenticate it with scoped-token HMAC credentials:
```go theme={null}
client := limitless.NewClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
)
// client.Markets, client.Portfolio, client.Pages,
// client.ApiTokens, client.PartnerAccounts, client.DelegatedOrders
```
The legacy `WithAPIKey` option still works but is not recommended for new integrations:
```go theme={null}
client := limitless.NewClient(
limitless.WithAPIKey("lmts_your_key_here"),
)
```
## HttpClient Options
The `HttpClient` uses the functional options pattern. Pass any combination of options to `NewHttpClient()` or `NewClient()`:
| Option | Type | Default | Description |
| ---------------------------- | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------- |
| `WithBaseURL(url)` | `string` | `https://api.limitless.exchange` | API base URL |
| `WithAPIKey(key)` | `string` | Reads `LIMITLESS_API_KEY` env | Legacy `X-API-Key` auth (still works; prefer a scoped API token) |
| `WithHMACCredentials(creds)` | `HMACCredentials` | -- | HMAC credentials for scoped API token auth (see [Programmatic API](/developers/programmatic-api)) |
| `WithTimeout(d)` | `time.Duration` | `30s` | HTTP request timeout |
| `WithMaxIdleConns(n)` | `int` | `50` | Maximum idle connections in the pool |
| `WithIdleConnTimeout(d)` | `time.Duration` | `60s` | How long idle connections remain in the pool |
| `WithTransport(t)` | `http.RoundTripper` | Default transport | Custom HTTP transport |
| `WithAdditionalHeaders(h)` | `map[string]string` | `nil` | Extra headers merged into every request |
| `WithLogger(l)` | `Logger` | `NoOpLogger` | Logger for request/response tracing |
```go theme={null}
client := limitless.NewHttpClient(
limitless.WithHMACCredentials(limitless.HMACCredentials{
TokenID: os.Getenv("LMTS_TOKEN_ID"),
Secret: os.Getenv("LMTS_TOKEN_SECRET"),
}),
limitless.WithTimeout(15 * time.Second),
limitless.WithLogger(limitless.NewConsoleLogger(limitless.LogLevelDebug)),
)
```
## Logging
The SDK provides a pluggable `Logger` interface with a built-in `ConsoleLogger`:
```go theme={null}
logger := limitless.NewConsoleLogger(limitless.LogLevelDebug)
client := limitless.NewHttpClient(limitless.WithLogger(logger))
```
| Level | Description |
| --------------- | -------------------------------------------------------------------------- |
| `LogLevelDebug` | Verbose output including headers, venue cache operations, and raw payloads |
| `LogLevelInfo` | General operational messages |
| `LogLevelWarn` | Warnings about potential issues |
| `LogLevelError` | Errors only |
Set `LogLevelDebug` during development to see request headers, venue cache hits/misses, and full API responses. Switch to `LogLevelInfo` or `LogLevelWarn` in production.
## Source Code
The SDK is open source. Contributions and issue reports are welcome.
Browse the source, report issues, and contribute at github.com/limitless-labs-group/limitless-exchange-go-sdk
## Disclaimer
**USE AT YOUR OWN RISK.** This SDK is provided as-is with no guarantees. You are solely responsible for any trading activity conducted through this software. Limitless Exchange is not available to users in the United States or other restricted jurisdictions. By using this SDK, you confirm compliance with all applicable local laws and regulations.
## Next Steps
Discover markets, fetch orderbooks, and understand venue caching.
Browse markets by category with navigation, filters, and pagination.
Place GTC and FOK orders, cancel orders, and manage token approvals.
Track your open positions and trading history.
Derive, list, and revoke scoped HMAC tokens for partner integrations.
Create sub-accounts with server wallets or EOA verification.
Place orders on behalf of sub-accounts with server-side signing.
Subscribe to real-time orderbook and price updates.
Retry logic, error types, and debugging strategies.
## Server Wallet Redemption and Withdrawal
For partner server-wallet sub-accounts, the SDK provides helper methods for payout settlement and treasury movement:
* [`POST /portfolio/redeem`](/api-reference/portfolio/redeem) — claim resolved positions
* [`POST /portfolio/withdraw`](/api-reference/portfolio/withdraw) — transfer ERC20 funds from managed sub-accounts
* [`POST /portfolio/withdrawal-addresses`](/api-reference/portfolio/add-withdrawal-address) — allowlist an explicit treasury destination with Privy identity auth
* [`DELETE /portfolio/withdrawal-addresses/:address`](/api-reference/portfolio/delete-withdrawal-address) — remove an allowlisted destination with Privy identity auth
Required scopes for `apiToken` auth: `trading` for redeem and `withdrawal` for withdraw. Allowlist add/delete calls use a Privy identity token instead of API-token/HMAC auth.
```go theme={null}
identityToken := os.Getenv("PRIVY_IDENTITY_TOKEN")
treasuryAddress := "0x0F3262730c909408042F9Da345a916dc0e1F9787"
_, err := client.PartnerAccounts.AddWithdrawalAddress(ctx, identityToken, limitless.PartnerWithdrawalAddressInput{
Address: treasuryAddress,
Label: "treasury",
})
if err != nil {
log.Fatal(err)
}
withdraw, err := client.ServerWallets.Withdraw(ctx, limitless.WithdrawServerWalletParams{
Amount: "1000000",
OnBehalfOf: childProfileID,
Destination: treasuryAddress,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(withdraw.Destination)
```
Set `OnBehalfOf` when withdrawing from a child server-wallet profile. `Destination` is optional for child withdrawals; when omitted, the API defaults to the authenticated partner smart wallet when present, otherwise the authenticated partner account. Leave `OnBehalfOf` as zero only when withdrawing the authenticated caller's own server wallet to an explicit `Destination`.
See the full flow and scope guidance in [Programmatic API](/developers/programmatic-api).