BuyProxy API: introduction

The base URL for every endpoint below is:

https://www.buyproxy.org/v1

This is the same self-service API that powers your dashboard, exposed for programmatic use. Sign up, verify your email, create a key, and you can add money to your wallet, buy bandwidth and generate proxies without ever opening a browser again.

Authentication

Every request except GET /v1/products needs an X-API-Key header. Create a key from Personal API keys once you have an account — see Authentication for the full signup-to-key flow, including the two calls needed to create an account by API alone.

curl https://www.buyproxy.org/v1/account \
  -H "X-API-Key: bp_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# {"email":"you@example.com","name":"you","plan":"free","planExpiresAt":null,"balanceGb":4.2,"createdAt":"..."}

Prefer a typed client? The official Go SDK wraps the calls below (the wallet calls need v1.1.0 or later).

Endpoints

A typical flow

# 1. Pick a product and see its price
curl https://www.buyproxy.org/v1/products

# 2. Add $20 to your wallet, then open payUrl to pay (use "method":"crypto" for a crypto invoice)
curl -X POST https://www.buyproxy.org/v1/wallet/topup \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"method":"card","amountCents":2000}'
# {"payUrl":"https://...","transactionId":"st_..."}

# 3. Wait for the payment to settle: the money is in your wallet once it's succeeded
curl https://www.buyproxy.org/v1/transactions/st_... -H "X-API-Key: $KEY"
# {"id":"st_...","kind":"wallet","status":"succeeded",...}

# 4. Buy 10 GB of Core Residential from the wallet. It is yours straight away.
#    Reuse the same Idempotency-Key if you retry, and you are charged once.
curl -X POST https://www.buyproxy.org/v1/wallet/purchase \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"kind":"gb","productKey":"residential","gb":10}'
# {"ok":true,"summary":"10 GB Core Residential","amountCents":990,"balanceCents":1010}

# 5. Find the plan and generate a US proxy
curl https://www.buyproxy.org/v1/balances -H "X-API-Key: $KEY"
curl -X POST https://www.buyproxy.org/v1/plans/PLAN_ID/generate \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"country":"US","count":5}'
# {"lines":["user-country-us:pass@gw.buyproxy.org:6969", ...]}

# 6. Send a request through one of the lines
curl -x "http://user-country-us:pass@gw.buyproxy.org:6969" https://api.ipify.org

A generate response can also carry notes, a list of plain-language remarks about the lines, for example that stickyMinutes turned sticky on without setting a length on Core Residential. It's left out when there is nothing to say.

The full machine-readable spec is at /openapi.yaml.

Reselling to your own customers instead of using proxies yourself? See the Reseller API — a separate key type for managing sub-customers.

Errors

Every error response is {"error": "message"} with one of these status codes: