Developer API

Provision and manage proxy lines with the API

Look up available inventory, place bulk orders, pay and query orders through the REST API, and wire it into your own systems.

On this page
  1. 01Headers and base URL
  2. 02Check available regions and bandwidth
  3. 03Place a bulk order
  4. 04Pay the order
  5. 05Query orders and purchased IPs

The API and the console share the same inventory. Once an order placed through the API is paid, the lines appear immediately under "My IPs" in the console.

01Headers and base URL

Every merchant endpoint requires two headers: x-merchant-token (your merchant access token) and x-merchant-code (your merchant code). Both are mandatory; a request missing either one is rejected.

base-url
https://api.ipfast.net/api/ipft

All paths below are relative to that base URL. For example, GET /client/order/orderList resolves to https://api.ipfast.net/api/ipft/client/order/orderList.

02Check available regions and bandwidth

Look up purchasable inventory first. bandwidth is a required spec (Mbps, commonly 5 or 10). When you omit it, the same region comes back as several rows, one per bandwidth tier.

regional-available.sh
curl -X GET "https://api.ipfast.net/api/ipft/client/ip/pool/regionalAvailableIps?type=1&ipCategory=HOST" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

In the response, price is the monthly unit price for that bandwidth tier and ipTotals is the quantity still available. The bandwidth you send when ordering must match a tier returned here, otherwise the order fails because no price or stock is configured for it.

03Place a bulk order

countryNums is an array, and each entry describes the requirement for one country or region — so a single request provisions multiple regions at once. Every entry must carry an explicit bandwidth.

create-order.sh
curl -X POST "https://api.ipfast.net/api/ipft/client/order/addStatic" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "countryNums": [
      {"countryCode":"US","location":"New York","num":2,"ipType":1,"ipCategory":"HOST","bandwidth":10},
      {"countryCode":"HK","location":"hongkong","num":5,"ipType":1,"ipCategory":"HOST","bandwidth":5}
    ],
    "monthCount": 1
  }'

Field reference: countryCode country code; location state or region; num how many IPs you need in that region; ipType 0 broadcast, 1 native; ipCategory HOST residential, IDC datacenter; monthCount subscription length in months. A successful call returns the order number:

response
{"msg":"操作成功","code":200,"data":"N2025032701271232584"}

04Pay the order

An order only takes effect after payment. Balance is currently the only supported method, and the path parameter orderId is the order number returned above.

pay-order.sh
curl -X POST "https://api.ipfast.net/api/ipft/client/payment/order/pay/N2025032701271232584" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE" \
  -H "Content-Type: application/json" \
  -d '{"payment":"BALANCE"}'

data.status is 1 when the payment succeeded and 0 when it failed. Common errors: 500 order expired, 500 merchant wallet not found, 500 insufficient balance.

05Query orders and purchased IPs

The order list returns order status plus an orderItems breakdown. status: 0 not yet active, 10 active, 20 expired. paidStatus: 0 cancelled, 10 unpaid, 20 paid.

query.sh
curl -X GET "https://api.ipfast.net/api/ipft/client/order/orderList?productType=2" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

# Purchased IPs, filterable by order number, status and IP
curl -X GET "https://api.ipfast.net/api/ipft/client/ip/pool/item/merchantIpList?orderNo=N2025032701271232584&status=1&pageNum=1&pageSize=50" \
  -H "x-merchant-token: $TOKEN" \
  -H "x-merchant-code: $CODE"

For merchantIpList, status: 1 active, 2 expired, 3 unsubscribed. Returned fields include ip, account, password, port, countryCode, location, bandwidth, effectiveDatetime and expireDatetime; pagination uses pageNum and pageSize.

TipOne request can provision several regions at once, but stock and bandwidth are validated per region: if any single row lacks the requested tier, the entire order is rejected. Check ipTotals from regionalAvailableIps before submitting.

FAQFrequently asked

How soon can I use an IP after purchase?

Lines are generated in about 1–3 minutes. Check "My IPs" in the console for the assigned address.

Which protocols are supported? Which one should I use?

Both HTTP and SOCKS5 are supported. For anti-detect browsers and desktop clients, SOCKS5 has better compatibility.

What happens when a line expires?

Forwarding stops immediately. Enable expiry reminders and renew in advance — the IP stays the same after renewal.

Can I use the same line for several accounts?

Technically yes, but it is not recommended. Sharing one IP increases the risk of linking accounts. Use a dedicated static IP per account or profile.

Do you support IP whitelisting?

Yes. You can authenticate by username and password or by whitelisting your egress IP. Whitelisting suits servers with a fixed IP.

Was this article helpful?
I

IPFAST Tech Team

We build and operate IPFAST residential proxy infrastructure. Every guide here is tested in-house and kept in sync with the product.

More guides

Related articles

Help Center
Newsletter

Subscribe to IPFAST updates

New tutorials, product updates, and industry insights — about once a month. Unsubscribe anytime.

By submitting you agree to the Privacy Policy
Start free trial See pricing