Go SDK

Installation

go get github.com/DishantSinghDev2/buyproxy-go

Go 1.21+. Standard library only.

Authentication

Create an API key under Dashboard → API keys — personal keys start bp_key_, reseller keys bp_live_. The SDK reads BUYPROXY_API_KEY from the environment automatically; you can also pass the key explicitly. A missing key fails immediately with an authentication error, without a network call.

// 1. Environment variable (recommended)
client := buyproxy.New()

// 2. Explicit key, e.g. from a secrets manager
client = buyproxy.New(buyproxy.WithAPIKey(secret))

// 3. Which kind of key is it?
fmt.Println(client.KeyKind()) // "personal" | "reseller" | ""

Quick start

package main

import (
	"context"
	"fmt"
	"io"
	"log"

	buyproxy "github.com/DishantSinghDev2/buyproxy-go"
)

func main() {
	ctx := context.Background()
	client := buyproxy.New() // reads BUYPROXY_API_KEY — or buyproxy.WithAPIKey("bp_key_…")

	plans, err := client.Plans.List(ctx)
	if err != nil || len(plans) == 0 {
		log.Fatal("no plans yet — top up first: ", err)
	}

	res, err := client.Plans.Generate(ctx, plans[0].ID, &buyproxy.GenerateParams{Country: "US", City: "Austin", Count: 5})
	if err != nil {
		log.Fatal(err)
	}

	resp, err := res.Proxies[0].HTTPClient().Get("https://api.ipify.org")
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	ip, _ := io.ReadAll(resp.Body)
	fmt.Println("exit IP:", string(ip))
}

Set StickyMinutes: 10 to keep the same IP for ten minutes, or Protocol: buyproxy.SOCKS5 for SOCKS5.

Generating proxies

Generation is free and instant — bandwidth is only consumed when traffic flows through a proxy. Every parameter is optional; omit one and the API's default applies. (Names follow each language's conventions, e.g. stickyMinutes / sticky_minutes / StickyMinutes.)

Each returned line is username:password@host:port with your targeting encoded in the username. Lines are on-demand and not persistent — generate fresh ones when you need them instead of storing them, because credentials can rotate when the pool moves.

// Country, state and city — what a plan supports is in plan.Generate.Targeting
client.Plans.Generate(ctx, plan.ID, &buyproxy.GenerateParams{Country: "US", State: "California", City: "Los Angeles"})

// Sticky session: keep one IP for 30 minutes (max is plan.Generate.MaxStickyMinutes)
client.Plans.Generate(ctx, plan.ID, &buyproxy.GenerateParams{Country: "DE", StickyMinutes: 30})

// SOCKS5 instead of HTTP
client.Plans.Generate(ctx, plan.ID, &buyproxy.GenerateParams{Protocol: buyproxy.SOCKS5, Count: 10})

// Bulk: up to 1000 lines per call
res, _ := client.Plans.Generate(ctx, plan.ID, &buyproxy.GenerateParams{Count: 1000})
os.WriteFile("proxies.txt", []byte(strings.Join(res.Lines, "\n")), 0o600)

Every top-up and allocation call takes a product key. Live prices come from the catalog call, so you never hard-code a rate.

Pay-as-you-go top-ups of 100 GB or more include a 10% volume bonus, and a single order is capped at 10,000 GB.

Using the proxies with your stack

Each generated proxy is a small object (host, port, username, password, protocol) with helpers that return exactly what common clients expect, so you never hand-build a proxy URL or worry about percent-encoding special characters in a password.

proxy := res.Proxies[0]

client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(proxy.URL())}}
// or simply: client := proxy.HTTPClient()

c := colly.NewCollector()
c.SetProxyFunc(http.ProxyURL(res.Proxies[0].URL()))

opts := append(chromedp.DefaultExecAllocatorOptions[:],
	chromedp.ProxyServer(res.Proxies[0].URL().Host)) // add auth via a fetch.AuthRequired handler

fmt.Println(res.Proxies[0].Curl())  // ready-to-run curl command
fmt.Println(res.Proxies[0].Env())   // HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, …

Account, balances & history

Read-only calls for building dashboards, alerts and pre-flight checks. balances is the one to watch: it shows spendable GB per product, including GB from a payment that's still being added (pending).

catalog, _ := client.Products.List(ctx)       // product keys & live prices — no API key needed
account, _ := client.Account.Get(ctx)         // email, plan, lifetime GB
balances, _ := client.Balances.List(ctx)      // spendable GB per product (+ GB still arriving)
plans, _ := client.Plans.List(ctx)            // plan ids and what each can generate
history, _ := client.Transactions.List(ctx, 20)

Buying bandwidth

1. Call the top-up method — it returns a hosted payment URL and a transaction id. Card payments are processed by Stripe Checkout; crypto by an invoice page.
2. Send your user (or yourself) to that URL to pay.
3. Poll the transaction (or use the SDK's wait helper) until status is succeeded or failed. Crypto payments are checked live on every poll, so they settle even if a webhook is delayed.
4. The GB shows up under balances within seconds — pendingGb while it's arriving, activeGb once it's live.

Plans are subscriptions billed monthly or yearly by card (crypto only covers pay-as-you-go top-ups). If the account already has a subscription, the call returns the subscription settings page as the URL and a null transaction id — switching plans is prorated there, and you can't accidentally subscribe twice.

// Buy 10 GB of Core Residential by card — open PayURL in a browser
checkout, _ := client.Topup.Card(ctx, buyproxy.TopupCardParams(buyproxy.ProductResidential, 10))
fmt.Println(checkout.PayURL)

// Or subscribe to a plan (monthly or yearly)
client.Topup.Card(ctx, buyproxy.PlanCardParams(buyproxy.PlanPro, buyproxy.Yearly))

// Crypto (pay-as-you-go top-ups only)
client.Topup.Crypto(ctx, buyproxy.ProductResidential, 50)

// Wait for the payment to settle — GB appears on client.Balances.List right after
tx, _ := client.Transactions.Wait(ctx, *checkout.TransactionID, 3*time.Second)
fmt.Println(tx.Status) // "succeeded"

Card payments are processed by Stripe; crypto top-ups are pay-as-you-go only. Subscriptions can be managed or cancelled from Dashboard → Billing.

Reseller API

The reseller API lets you build a proxy product on top of BuyProxy. The flow is always the same:

1. Fund your pool — buy GB per product into your reseller pool by card or crypto. Pool GB is priced like a normal top-up (including the volume bonus), fixed at purchase time.
2. Create a customer — an isolated sub-account with its own credentials and no bandwidth. Store the returned username.
3. Allocate — move whole GB of one product from your pool onto that customer, with an idempotency key. The first allocation of a product creates the plan; later ones add to it.
4. Generate — produce proxy lines for the customer from their plan id (found on the customer record), with all the usual targeting options.
5. Monitor — read the customer's usage (remaining, used, total per plan, plus any GB still arriving) to bill or alert.
6. Suspend / reactivate — a suspended customer can't generate new lines (403). Lines already handed out may keep working until they rotate, so stop distributing them at the same time. You can also rename a customer.

Allocated GB can't be moved back to the pool, so allocate what a customer has paid for.

reseller := buyproxy.New(buyproxy.WithAPIKey("bp_live_…"))

reseller.Reseller.Pool.TopupCard(ctx, buyproxy.PoolTopupParams{ProductKey: buyproxy.ProductResidential, GB: 500})
customer, _ := reseller.Reseller.Customers.Create(ctx, "Acme Inc") // isolated sub-account

reseller.Reseller.Customers.Allocate(ctx, customer.Username, buyproxy.AllocateParams{
	ProductKey: buyproxy.ProductResidential, GB: 20, IdempotencyKey: "order-1042", // safe to retry
})

detail, _ := reseller.Reseller.Customers.Get(ctx, customer.Username)
res, _ := reseller.Reseller.Customers.Generate(ctx, customer.Username, buyproxy.CustomerGenerateParams{
	PlanID: detail.Plans[0].ID, GenerateParams: buyproxy.GenerateParams{Country: "DE"},
})

reseller.Reseller.Customers.Update(ctx, customer.Username, buyproxy.CustomerUpdate{Status: buyproxy.CustomerSuspended})

Allocating bandwidth to a customer moves real GB, so it accepts an idempotency key. Send the same key twice and the second call moves nothing and returns alreadyApplied: true with the same result — safe to retry after a timeout or crash.

Use a value you can derive again from your own data (an order id, an invoice number), not a random value created per attempt. Keys are scoped to your account and may be up to 200 characters.

Errors & retries

Every non-success response becomes a typed error carrying the HTTP status and the API's own message, so you can branch on the failure instead of parsing strings.

_, err := client.Plans.Generate(ctx, planID, nil)

switch {
case errors.Is(err, buyproxy.ErrInsufficientBandwidth):
	log.Println("Out of GB — top up first")
case errors.Is(err, buyproxy.ErrRateLimited):
	var apiErr *buyproxy.APIError
	errors.As(err, &apiErr)
	log.Printf("Slow down; retry in %s", apiErr.RetryAfter)
case errors.Is(err, buyproxy.ErrAuthentication):
	log.Println("Check your API key")
}

Non-2xx responses are *buyproxy.APIError (with Status, Message, Body); network failures are *buyproxy.ConnectionError.

Every SDK retries for you, with the same rules:

• Rate limits (`429`) are always retried, waiting for the Retry-After the API sends (capped at 30 s) or an exponential back-off with jitter.
• Reads (GET) are also retried on 502/503/504 and on network failures.
• Writes are not retried on server errors — a repeated checkout or allocation must never double-charge — unless you attach an idempotency key (see below), which makes the retry provably safe.
• The default is 2 retries; set it to 0 to turn retries off. After the last attempt you get the typed error.

The API allows 60 requests per minute per key. Batch with count (up to 1000 lines per call) rather than looping over single-proxy calls.

Configuration

client := buyproxy.New(
	buyproxy.WithAPIKey("bp_key_…"),            // default: $BUYPROXY_API_KEY
	buyproxy.WithBaseURL("https://www.buyproxy.org"),
	buyproxy.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
	buyproxy.WithMaxRetries(2),                  // 429s always; 5xx only for safe requests
)

Concurrency

// The client is safe for concurrent use (mind the 60 requests/minute limit)
g, ctx := errgroup.WithContext(ctx)
for _, p := range plans {
	p := p
	g.Go(func() error {
		_, err := client.Plans.Generate(ctx, p.ID, &buyproxy.GenerateParams{Count: 10})
		return err
	})
}
err := g.Wait()

Testing your code

You don't need a real account or network to unit-test code that uses the SDK — inject a fake transport. This is how the SDK's own test suite works.

srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	fmt.Fprint(w, `{"lines":["u:p@gw.buyproxy.org:6969"]}`)
}))
defer srv.Close()

client := buyproxy.New(buyproxy.WithAPIKey("bp_key_test"), buyproxy.WithBaseURL(srv.URL))
res, _ := client.Plans.Generate(ctx, "plan_1", nil)
// res.Proxies[0].Host == "gw.buyproxy.org"

API reference

Every method maps one-to-one onto a documented REST endpoint.

Notes

• Non-2xx responses are *buyproxy.APIError with Status, Message and Body; use errors.As to read them.

• Proxy.HTTPClient() returns an *http.Client already routed through the proxy — HTTP and SOCKS5.

• Zero third-party dependencies, so there is nothing to audit but this module.

Developing the SDK

go vet ./... && go test -race ./...