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

# Go SDK

> Install the Go SDK and send your first proxy request with the net/http standard library.

Install the Go SDK and send your first proxy request with the standard library.

The `nodemaven-go` module builds proxy settings for Go's `net/http` client and other clients that accept a proxy URL. It also provides separate browser proxy fields and an account API client.

## Before you start

You need Go 1.22 or newer, an active Residential/Mobile plan with available traffic, and your proxy credentials. This quickstart uses SDK version **v0.1.1**.

## 1. Create a module

In a new project directory, run:

```bash theme={null}
go mod init example.com/nodemaven-quickstart
go get github.com/nodemaven/nodemaven-go@v0.1.1
```

If you are adding the SDK to an existing Go module, run only the `go get` command.

## 2. Set your proxy credentials

Open the [NodeMaven dashboard](https://dashboard.nodemaven.com), go to **Rotating Residential Proxy → Authenticated**, and find your credentials under **Proxy generator**.

![Proxy Setup 2](https://mintcdn.com/node-maven/l_oWfdd8xhVH5Vk9/images/proxy-setup-2.png?fit=max\&auto=format\&n=l_oWfdd8xhVH5Vk9\&q=85\&s=fd8b67bedb3bde4fb1e32461dd8b03ba)

Use your base proxy username, without generated targeting or session suffixes. The SDK builds those from your options. These credentials are different from your dashboard sign-in email and password.

On macOS or Linux:

```bash theme={null}
export NODEMAVEN_LOGIN='YOUR_PROXY_USERNAME'
export NODEMAVEN_PASSWORD='YOUR_PROXY_PASSWORD'
```

On Windows PowerShell:

```powershell theme={null}
$env:NODEMAVEN_LOGIN = 'YOUR_PROXY_USERNAME'
$env:NODEMAVEN_PASSWORD = 'YOUR_PROXY_PASSWORD'
```

Run the program from this terminal. The SDK reads environment variables but does not load `.env` files automatically.

## 3. Send your first request

Create `main.go`:

```go theme={null}
package main

import (
    "fmt"
    "io"
    "log"
    "net"
    "net/http"
    "strings"
    "time"

    "github.com/nodemaven/nodemaven-go"
)

func main() {
    if err := run(); err != nil {
        log.Fatal(err)
    }
}

func run() error {
    proxy, err := nodemaven.New(
        nodemaven.WithParam("country", "us"),
        nodemaven.WithParam("filter", "medium"),
    )
    if err != nil {
        return err
    }

    transport := http.DefaultTransport.(*http.Transport).Clone()
    transport.Proxy = proxy.HTTPProxy()
    defer transport.CloseIdleConnections()

    client := &http.Client{
        Transport: transport,
        Timeout:   30 * time.Second,
    }
    response, err := client.Get("https://api.ipify.org")
    if err != nil {
        return err
    }
    defer response.Body.Close()

    if response.StatusCode != http.StatusOK {
        return fmt.Errorf("IP request returned %s", response.Status)
    }
    body, err := io.ReadAll(response.Body)
    if err != nil {
        return err
    }
    exitIP := net.ParseIP(strings.TrimSpace(string(body)))
    if exitIP == nil {
        return fmt.Errorf("IP service returned an invalid address")
    }
    fmt.Printf("Proxy exit IP: %s\n", exitIP)
    return nil
}
```

Run it:

```bash theme={null}
go run .
```

The output contains the proxy's public exit IP. For example:

```text theme={null}
Proxy exit IP: 203.0.113.42
```

This is illustrative output. Your IP will be different, and the request uses proxy traffic.

The SDK reads your credentials from the environment. `filter="medium"` corresponds to the dashboard's **Quality** mode. `nodemaven.New` builds a configuration locally; the HTTP client makes the request.

## Choose the right output

| SDK method | What it returns |
| - | - |
| `proxy.HTTPProxy()` | A function for `http.Transport.Proxy` |
| `proxy.ProxyURL()` | A parsed `*url.URL` |
| `proxy.URL()` | An authenticated HTTP proxy URL |
| `proxy.Browser()` | Separate `Server`, `Username`, and `Password` fields |
| `proxy.Username()` | The generated username, including parameters |
| `proxy.Server()` | `host:port` without credentials |

For a browser driver, map `proxy.Browser()` fields to that driver's own proxy and authentication options. The SDK does not start the browser. Although printing a `Proxy` masks its password, `URL()` and the fields returned for clients contain real credentials; keep them out of shared logs.

## Reuse the client

Create a client and transport once for each proxy identity you intend to reuse. Reusing them preserves connection pooling. When you create a different SDK proxy object, configure a transport for that object as well: changing your Go variable does not update an existing HTTP client's proxy settings.

## Next steps

* [Configure location, pool, and filters](https://docs.nodemaven.com/developer-sdks/configuration.md)
* [Manage sticky sessions and worker identities](https://docs.nodemaven.com/developer-sdks/sessions.md)
* [Check a connection and handle errors](https://docs.nodemaven.com/developer-sdks/connection-checks.md)
* [Call the account API](https://docs.nodemaven.com/developer-sdks/account-api.md)

Full method reference: [pkg.go.dev](https://pkg.go.dev/github.com/nodemaven/nodemaven-go@v0.1.1). Source and issues: [nodemaven-go](https://github.com/nodemaven/nodemaven-go).


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