# Go SDK

The official Go SDK wraps the CoinMarketCap Pro API with typed request and response structs, automatic retries, and endpoints grouped by category.

- **Module:** [`github.com/OpenCMC/coinmarketcap-api-go/v5`](https://pkg.go.dev/github.com/OpenCMC/coinmarketcap-api-go/v5)
- **GitHub:** [OpenCMC/coinmarketcap-api-go](https://github.com/OpenCMC/coinmarketcap-api-go)
- **Package name:** `coinmarketcap`
- **Requires:** Go 1.24+

## Get started

1. **Install the module**

   ```bash
   go get github.com/OpenCMC/coinmarketcap-api-go/v5
   ```

1. **Create a client**

   Set your API key from the [Developer Portal](https://pro.coinmarketcap.com/account). For keyless endpoints, use `WithEnvironment(coinmarketcap.EnvironmentPublic)`.

   ```go
   import (
   	"log"
   	"os"

   	"github.com/OpenCMC/coinmarketcap-api-go/v5"
   )

   cmc, err := coinmarketcap.New(coinmarketcap.WithAPIKey(os.Getenv("CMC_PRO_API_KEY")))
   if err != nil {
   	log.Fatal(err)
   }
   ```

1. **Call an endpoint**

   Endpoints are grouped by category on the client. Optional parameters are pointers; `coinmarketcap.String`, `Int`, `Float64`, `Bool` and `Ptr` create them:

   ```go
   quotes, err := cmc.Cryptocurrency.QuotesLatest(ctx, &coinmarketcap.CryptocurrencyQuotesLatestParams{
   	ID: coinmarketcap.String("1,1027"),
   })
   if err != nil {
   	log.Fatal(err)
   }
   for _, coin := range quotes.Data {
   	if coin.Name != nil {
   		fmt.Println(*coin.Name)
   	}
   }
   ```

1. **Handle errors**

   HTTP errors come back as typed errors. Use `errors.As` to inspect them:

   ```go
   var rateLimited *coinmarketcap.RateLimitError
   var apiErr *coinmarketcap.CMCError
   switch {
   case errors.As(err, &rateLimited):
   	// 429 - check the Retry-After header
   	fmt.Println(rateLimited.Header.Get("Retry-After"))
   case errors.As(err, &apiErr):
   	// Any HTTP error, with the API's error code and message
   	fmt.Println(apiErr.StatusCode, apiErr.ErrorCode, apiErr.Message)
   }
   ```

## Public (keyless) mode

```go
cmc, err := coinmarketcap.New(coinmarketcap.WithEnvironment(coinmarketcap.EnvironmentPublic))
if err != nil {
	log.Fatal(err)
}

listings, err := cmc.Cryptocurrency.ListingsLatest(ctx, &coinmarketcap.CryptocurrencyListingsLatestParams{
	Limit: coinmarketcap.String("10"),
})
```

See the [Keyless Public API](https://coinmarketcap.com/api/documentation/pro-api-reference/keyless-public-api) for available endpoints without a key.

## Configuration

```go
cmc, err := coinmarketcap.New(
	coinmarketcap.WithAPIKey(os.Getenv("CMC_PRO_API_KEY")),
	coinmarketcap.WithTimeout(10*time.Second), // per attempt, default 30s
	coinmarketcap.WithMaxRetries(3),           // default 2, 0 disables retries
)
```

Requests are retried on `408`, `409`, `429` and `5xx` responses, network errors and timeouts, with exponential backoff that honors `Retry-After`. The client is safe for concurrent use; create one and reuse it.

## Next steps

- [Get Started with an API Key](https://coinmarketcap.com/api/documentation/guides/quick-start) if you have not set up authentication yet
- [Choose an endpoint](https://coinmarketcap.com/api/documentation/pro-api-reference/endpoint-overview) to find the right API family
- Every endpoint page in the API reference has a Go SDK sample
- Full README and examples on [GitHub](https://github.com/OpenCMC/coinmarketcap-api-go)