# ProxyMarket Vendor Integration: Sell Your Own Proxies

> For AI tools: this is the Markdown copy of https://xproxy.io/document/proxymarket-vendor-integration. Every XProxy guide has one at its URL + `.md`; the index of all guides is https://xproxy.io/llms.txt.

Connect your own proxy or VPN platform to ProxyMarket: build the health check, create your API key, sync plans, deliver orders by webhook and get paid.

Sell your own proxies or VPN on ProxyMarket ([market.xproxy.io](https://market.xproxy.io)). You keep running your servers. ProxyMarket runs the shop, takes the payments and answers customers. A small connector on your side links the two: it makes a few calls to ProxyMarket and answers four webhooks.

**You need:** an approved vendor account on market.xproxy.io, a server that ProxyMarket can reach over HTTPS with a valid certificate, and someone who can write a small web service. Every endpoint, field and answer is also in the [ProxyMarket API reference](https://xproxy.io/docs/api/market/sync-plans).

**No time to write the server?** The [ProxyMarket connector](https://xproxy.io/document/proxymarket-connector) is a ready-made one. Install it on your server, give it one small script that adds and deletes a customer's login in your system (ready ones in Python, Node.js and shell), and it delivers every order. No code, no open port, no domain.

In short

**You call ProxyMarket**

Send your plans, keep stock and proxy health up to date, and deliver a login late if you need to. Every call carries your `X-API-Key`.

**ProxyMarket calls you**

A health check every 10 minutes, then a webhook when a customer pays, when an order ends and when a customer changes a setting.

**You keep 70%**

Your share of each sale is credited as soon as the payment clears. ProxyMarket keeps 30% for the shop, payments, support and refunds.

## How does it work?

**Your server** modems, proxies, VPN

You send: plans, stock, health We send: each paid order

**ProxyMarket** shop, payments, support

We show: the login or config Customer: browses and pays

**Customer** connects to your proxy

ProxyMarket sells. You deliver the proxy login or the VPN config file, and the customer then connects straight to your server.

## What are the steps to go live?

Do them in this order. Steps 1 to 3 set up your account; steps 4 to 7 are the integration.

1. Create a normal account on [market.xproxy.io](https://market.xproxy.io) You
2. Apply to become a vendor (**Become Vendor** in the top menu)You
3. Approval, usually within 24 hours. The top menu shows **Vendor Pending…** until then; message [@xproxyio](https://t.me/xproxyio) with your account email to speed it upProxyMarket
4. Meanwhile, [build your health check](#health) and put your webhook server onlineYou
5. [Create your API key](#api-key) in the vendor dashboardYou
6. [List your plans](#plans), [handle orders](#orders) and [check webhook signatures](#signature) You
7. [Place one real test order](#test-order) and check the customer gets a working proxyYou + ProxyMarket

## Why build the health check first?

ProxyMarket checks your server with `HEAD {webhook_url}/health`. It is the one endpoint that decides whether your plans stay on sale:

- **When you create your key**, ProxyMarket calls it once. A 5xx, a refused connection or more than 5 seconds: no key (HTTP 422 with the reason).
- **Every 10 minutes after that**, while the key has plans on sale, it calls it again. After **2 failures in a row, every plan served by that key is hidden** from the shop and cannot be bought. One good answer brings them all back by itself.

| Counts as up | Counts as down |
| --- | --- |
| Any status below 500, within 5 seconds. No login and no body needed. | A timeout, a refused connection, or any 5xx status. |

**Python (Flask)**

```python
@app.route("/health", methods=["HEAD", "GET"])
def health():
    return "", 200   # no login, no database, no outside call
```

Put it under your webhook URL: with `https://your-vendor-host.com/marketplace` it answers at `/marketplace/health`.

**Node.js (Express)**

```javascript
// Express answers HEAD with the GET route automatically
app.get("/health", (req, res) => res.sendStatus(200));
```

Check it from outside: `curl -I https://your-vendor-host.com/marketplace/health` must show a status below 500 in under 5 seconds.

**This is the most common way a working shop quietly stops selling.** A deploy, a restart, or a firewall that blocks `HEAD` can empty your whole catalogue in about 20 minutes. Make `/health` the simplest route you have: no login, no database, no outside call, and answer `GET` too.

Do not mix it up with [Report the health of your proxies](https://xproxy.io/docs/api/market/report-health) (`POST /api/integration/health`). That one is a call *you* make about single proxies; it does not keep your plans listed.

## How do I get my API key?

You create it yourself once your vendor application is approved; nobody sends it to you. In the vendor dashboard, give the key a name and your **webhook URL**, for example `https://your-vendor-host.com/marketplace`. You can also do it with one call ([reference](https://xproxy.io/docs/api/market/create-integration-key)):

```bash
curl -X POST "https://market.xproxy.io/api/vendor/integrations" \
  -H "Authorization: Bearer $PROXYMARKET_LOGIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "primary-instance", "webhook_url": "https://your-vendor-host.com/marketplace"}'

# {"api_key": "pm_..."}   <- shown only this once, save it now
```

**The key is shown only once.** ProxyMarket keeps only a hash and cannot give it back. Save it straight away. If you lose it, create a new one.

From that one key you get two values. Keep them apart:

| Value | What it is | Used for |
| --- | --- | --- |
| `api_key` | The key itself, starting with `pm_` | The `X-API-Key` header on every call you make |
| `signing_key` | `SHA256(api_key)` as 64-character hex | Checking the `X-Signature` of every webhook ([how](#signature)) |

The key never expires, and its webhook URL cannot be changed later: to move servers, create a new key. If you run several independent servers, give each its own key. Orders go to the key set in each plan's **API Key / Server** in the vendor dashboard. A plan created by a sync gets the key that synced it; an older plan without that setting sends its orders to your **oldest** active key.

**Adding a second key?** Plans made before that keep going to the older key. Set their **API Key / Server** to the new key, or switch the old key off. `pm-connector test` warns when a plan goes elsewhere.

Errors: a call without the `X-API-Key` header gets 422, a wrong key 401, and a key whose vendor application is still pending 403. The **Integration Status** tab of the vendor dashboard shows, per key, when it was last seen, the connector version, and the last 20 deliveries with their result.

## How do I list my plans?

Send all your products with [Publish or update your plans](https://xproxy.io/docs/api/market/sync-plans) when your connector starts, and again whenever something changes. Synced plans are approved at once (plans you add by hand in the dashboard wait for an admin). Your `external_id` is your own ID for the product (a port, a modem, a VPN pool), and every later call and webhook uses it.

```bash
curl -X POST "https://market.xproxy.io/api/integration/plans/sync" \
  -H "X-API-Key: $PROXYMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "external_id": "port-1",
    "name": "US Mobile 4G - Port 1",
    "proxy_type": "mobile",
    "protocol": "HTTP",
    "country": "United States",
    "duration_days": 30,
    "price_usd": 25.00,
    "stock": 1,
    "is_active": true
  }]'

# {"created": 1, "updated": 0, "plans": [{"plan_id": "...", "external_id": "port-1", "status": "created"}]}
```

| Good to know | Why |
| --- | --- |
| Sending the same `external_id` again updates the plan | Sync is safe to repeat; it never makes duplicates. |
| A plan you leave out stays on sale | To stop selling it, call [Take a plan off sale](https://xproxy.io/docs/api/market/deactivate-plan). |
| Use only `mobile`, `residential`, `datacenter`, `isp`, `ipv6` or `vpn` as `proxy_type` | The API takes any text, but another value breaks the order: the customer never gets a login. See [VPN and VLESS](#vpn-vless). |
| `country` is the full English name, for example `United States` | Customers filter by the exact text, so spell it the same way on every plan ([more](#countries)). ProxyMarket does not check it. |
| A plan is shown only when it is active, in stock, listed and not hidden by the health check | `stock` is usually `1` per modem port: one customer per port. |
| `protocol` left out means `HTTP` | Send it anyway for VPN and SOCKS5 plans. |
| A plan created by a sync is pinned to the key that synced it | Its orders go to that key. A sync never changes the key of a plan that already exists ([more](#api-key)). |

## What happens when someone buys?

1. **The customer pays.** Your 70% is credited to your balance right away, before your server is even called.
2. **ProxyMarket calls `POST {webhook_url}/provision`** with the `order_id` and your `external_plan_id` ([payload](https://xproxy.io/docs/api/market/provision-webhook)). Check the signature, then create the customer's access.
3. **You answer** with the login or config (best), with `pending`, or with `error`. See the table below.
4. **The customer sees the login** on ProxyMarket and connects to your server. ProxyMarket lowers the plan's stock by one by itself.
5. **When the time runs out**, ProxyMarket ends the order by itself (it checks every 5 minutes) and calls `POST {webhook_url}/deprovision`. You remove the access and put the unit back on sale. See [When an order ends](#order-ends).

| `status` you answer | When to use it | What happens |
| --- | --- | --- |
| `provisioned` (best) | You can create the access at once | The customer gets it immediately. Add all four of `proxy_ip`, `proxy_port`, `proxy_username`, `proxy_password`, or `vpn_config_file` for VPN. |
| `pending` | Setting it up takes a while | Send it with [Deliver the proxy login or VPN config](https://xproxy.io/docs/api/market/push-credentials). ProxyMarket waits **120 seconds in total**, counted from the start; after that the order is refunded and a late delivery gets `409`. |
| `error` | You cannot deliver (port offline, no free profile) | Nothing is delivered. After the 120 seconds the customer is refunded to their wallet and your earning is removed. |

**Always answer HTTP 200, even for an error.** If `/provision` answers with another status, times out (after 30 seconds), returns invalid JSON, or says `provisioned` with an incomplete login, ProxyMarket hands the customer the login you synced on the plan instead, if there is one. A delivered login is never copied onto the plan, and a plan login that already belongs to another order is not reused: that order is refunded. The call is not retried.

Your answer's `expires_at` is ignored: ProxyMarket counts the time from activation and tells you in `/deprovision`.

### Can I encrypt the answer on a plain http:// URL?

Yes, optionally. Answer `200` with the headers `X-PM-Encrypted: v1` and `X-PM-Signature: sha256=` + the hex HMAC-SHA256 of the raw body keyed with your signing key, and the body `{"enc": "v1", "nonce": "…", "ct": "…"}`: a random 12-byte nonce and the AES-256-GCM ciphertext of your normal answer (tag appended), both in standard base64. The key is HKDF-SHA256 over the UTF-8 bytes of your signing key (empty salt, info `pm-provision-v1`, 32 bytes), and the AAD is the `order_id`. ProxyMarket checks the signature, decrypts and reads the answer as usual; a bad envelope counts like a timeout. The full format and a test vector are in the [API reference](https://xproxy.io/docs/api/market/provision-webhook) and section 5.1 of the guide. pm-connector does this by itself on an `http://` URL. HTTPS is still recommended, because webhook requests are not encrypted.

Save the `order_id`: you need it to deliver late, to end the order yourself, and to match the other webhooks.

## How do I check that a webhook really comes from ProxyMarket?

Every webhook POST carries `X-Signature: sha256=…`, an HMAC-SHA256 of the raw body. The secret is your **signing key**, `SHA256(api_key)` as hex, not the API key itself. Check it on `/provision`, `/deprovision` and `/update-settings` before you do anything else.

**Python**

```python
import hashlib, hmac, os

API_KEY = os.environ["PROXYMARKET_API_KEY"]
# The HMAC secret is SHA256(api_key) as hex, NOT the raw key. Compute it once.
SIGNING_KEY = hashlib.sha256(API_KEY.encode()).hexdigest()

def verify_signature(raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(SIGNING_KEY.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

# Flask: sign the raw bytes, before you parse the JSON
@app.route("/provision", methods=["POST"])
def provision():
    if not verify_signature(request.get_data(), request.headers.get("X-Signature", "")):
        return jsonify({"status": "error", "message": "Invalid signature"}), 401
    data = request.get_json()
    ...
```

Use the raw request body. Parsing the JSON and dumping it again changes the bytes, and the signature no longer matches.

**Node.js**

```javascript
const crypto = require("crypto");

// The HMAC secret is SHA256(api_key) as hex, NOT the raw key. Compute it once.
const SIGNING_KEY = crypto.createHash("sha256").update(process.env.PROXYMARKET_API_KEY).digest("hex");

function verifySignature(rawBody, header) {
  const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", SIGNING_KEY).update(rawBody).digest("hex"));
  const given = Buffer.from(header || "");
  // timingSafeEqual throws on different lengths, so check that first
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express: keep the raw body for the check
app.post("/provision", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("X-Signature"))) {
    return res.status(401).json({ status: "error", message: "Invalid signature" });
  }
  const data = JSON.parse(req.body);
  // ...
});
```

Answer `401` when the signature is wrong. Without this check, anyone who finds your URL can get free proxies or cut off a paying customer.

## How do I test before customers buy?

1. From outside your network, run `curl -I https://your-vendor-host.com/marketplace/health` and check you get a status below 500 within 5 seconds.
2. Sync one plan and find it in Browse on market.xproxy.io.
3. Place one real order for it. Your server should get `/provision` with a valid signature, and the login should appear in the customer's order.
4. Connect with that login, then wait for the order to end (or ask over Telegram to end it) and check `/deprovision` removes the access and the stock comes back.

Tell ProxyMarket on [Telegram @xproxyio](https://t.me/xproxyio) when you place the test order, so it can be checked from their side too.

## How do I keep stock and health up to date?

| When this happens on your side | Call |
| --- | --- |
| A modem or server goes offline | [`PATCH /plans/stock`](https://xproxy.io/docs/api/market/update-stock) with `stock: 0, is_active: false` |
| It comes back online, or a sold port is free again | [`PATCH /plans/stock`](https://xproxy.io/docs/api/market/update-stock) with `stock: 1, is_active: true` |
| A price, name or config changes | [`POST /plans/sync`](https://xproxy.io/docs/api/market/sync-plans) with just that plan |
| You stop selling a product | [`DELETE /plans/{external_id}`](https://xproxy.io/docs/api/market/deactivate-plan) |
| Optional, every few minutes | [`POST /health`](https://xproxy.io/docs/api/market/report-health) with the state and current IP of each proxy. Always include `current_ip`: leaving it out clears the stored IP. It does not keep your plans listed; the health check of your server does. |

All paths start with `https://market.xproxy.io/api/integration`.

## What happens when an order ends?

ProxyMarket calls [`POST {webhook_url}/deprovision`](https://xproxy.io/docs/api/market/deprovision-webhook) with a `reason`:

| Reason | Meaning |
| --- | --- |
| `expired` | The rental time is over. Sent automatically, up to 5 minutes late. |
| `renewed` | The customer paid to renew a running order. The old order ends now and a new `/provision` with a new `order_id` follows. |
| `cancelled` | An admin cancelled the order. |
| `admin_refund` | An admin refunded the customer. Your earning for it is taken back. |

Remove the customer's login (or turn their VPN profile off). Then send your real number of free units with `PATCH /plans/stock`: ProxyMarket puts stock back by itself after a refund, but not after an expiry. Answer `{"status": "deprovisioned"}`; the answer is only logged.

**This call is sent once and never retried.** If your server is down at that moment, the customer keeps access. Also end each order on your own timer when its time is up (you know the length from `/provision`). An order that failed provisioning and was auto-refunded gets no `/deprovision` at all.

[Mark an order expired](https://xproxy.io/docs/api/market/expire-order) only changes its status on ProxyMarket, in any state, even a cancelled one. It does not refund the customer, change stock or call your webhook.

## What if a customer changes their IP whitelist or TCP fingerprint?

When a customer saves **Proxy Settings** on an active order, ProxyMarket calls [`POST {webhook_url}/update-settings`](https://xproxy.io/docs/api/market/update-settings-webhook). It is sent once, for any order type. Apply what your system supports and answer `{"status": "ok"}`; you can ignore a field you do not support. The body has no `external_plan_id`, so find the plan from the `order_id` you saved at provision.

- `ip_whitelist`: only these IPs may use the proxy. Always a list of single addresses; `[]` means no IP limit.
- `tcp_fingerprint`: which OS the connection should look like (`win1` Windows 11, `mac1` macOS, `ios1` iPhone 15, `android1` Galaxy S24, and more). `null` turns it off.

## How do I sell VPN and VLESS?

The order flow is the same; only what you deliver changes. Send the **complete client file**, exactly as the customer should import it.

| Product | Plan fields | You deliver |
| --- | --- | --- |
| OpenVPN | `proxy_type: "vpn"`, `protocol: "OpenVPN"`, `vpn_protocol: "openvpn"` | The full `.ovpn` text, certificates and keys inside |
| WireGuard | `proxy_type: "vpn"`, `protocol: "WireGuard"`, `vpn_protocol: "wireguard"` | The full `.conf` with `[Interface]` and `[Peer]` |
| VLESS (Xray) | `proxy_type: "vpn"`, `protocol: "VLESS"`, `vpn_protocol: "vless"` | A one-line `vless://` link, or full Xray client JSON |

**Never send `proxy_type: "xray"`.** The shop shows VLESS plans as “Xray”, but that label comes from `vpn_protocol`. `xray` is accepted by the API and then breaks the plan: the customer pays and the config never arrives.

Three ways to deliver the file:

- **Same file for everyone on the plan:** put it in `vpn_config_template` when you sync.
- **A new file per order:** make it in `/provision` and answer with `vpn_config_file`.
- **A new file that takes time:** answer `pending`, then send `vpn_config_file` with [Deliver the proxy login or VPN config](https://xproxy.io/docs/api/market/push-credentials).

For VLESS, give each order its **own UUID** (sharing one means revoking one customer revokes all), name the transport in the plan description (for example XTLS-Reality or WS+TLS), and remove the UUID from your inbound when the order ends.

An OpenVPN file must contain `remote`, `dev tun` or `dev tap`, or both `client` and a `&lt;ca>` block; a `&lt;ca>` block alone is rejected. Every config needs at least 50 characters.

## How does IP rotation work?

The `rotation_link` you deliver is a URL that **ProxyMarket itself calls**, with a plain `GET` (redirects followed, certificate not checked, 15-second timeout). It does so when the customer presses **Rotate** and on the auto-rotation timer the customer picks (every 5 to 60 minutes), and stops when the order ends. The customer also sees the link and can open it.

If the plan's own `rotation_link` is handed out as a fallback (see [above](#orders)), it is never one that already belongs to another order.

## Is there a ready-made webhook server?

Yes: the [ProxyMarket connector](https://xproxy.io/document/proxymarket-connector) (`pm-connector`) runs on your Linux or Windows server and does everything on this page for you. You only give it one small script that adds and deletes a customer's login in your system; ready scripts in Python, Node.js and shell are on its page.

- It answers the webhooks with signature checks and creates the customer's username and password in your system and deletes them when the rental ends.
- It reaches ProxyMarket through the **ProxyMarket hook** (key type *ProxyMarket hook*): one outgoing connection to `market-hook-service.xproxy.io`, so the server needs no open port and no domain. Customers always connect to your proxy port directly.
- It catches up after downtime: orders that ended while it was offline lose their user as soon as it is back.

You make the plans in the Vendor Dashboard. If you want ProxyMarket to call your own HTTPS address instead of the hook, see [using your own address](https://xproxy.io/document/proxymarket-connector#public-url).

## How do I get paid?

|  |  |
| --- | --- |
| Your share | **70%** of each sale (the standard rate; it can be agreed per vendor) |
| ProxyMarket share | 30%, for the shop, payments, support and refunds |
| When it is credited | As soon as the customer's payment clears and the order goes active, before your `/provision` is called |
| Where to see it | **Earnings** in your vendor dashboard: each sale with its amount, your amount and the rate used |
| Payouts | Paid by the ProxyMarket admin from your balance. Ask on Telegram when you want to withdraw. |
| Refunds | An automatic refund (nothing delivered within 120 seconds) or an admin refund removes the earning from your balance. A promo code lowers the sale amount, and your share with it. |
| Withdrawing | A payout can be up to your balance and marks your oldest unpaid earnings as paid. |

The rate is saved with each sale, so a later rate change never touches money you already earned.

## Where do my plans show up in the shop?

Browse lists plans cheapest first, with one rule to know before you set prices: **plans from vendors running XProxy software come first**, under *Powered by xProxy*, with an `xProxy` badge. Plans from your own connector come next, under *Other vendors*, also cheapest first.

| Where | What decides the order |
| --- | --- |
| Browse, default | The XProxy group first, then yours, each cheapest first |
| Browse, when the customer sorts | The sort applies inside each group, so a cheaper plan of yours still stays below the XProxy group |
| Homepage “from $X” cards | The cheapest XProxy plan of each category; yours only when XProxy has no stock there |
| Country, protocol and search filters, your store page | Exactly the same for every vendor |

When everything listed belongs to one group, Browse shows one flat list without headings. Most customers arrive by filtering for a country or protocol, and there your plans sit next to everyone's.

## What do the error codes mean?

| Code | Meaning | What to do |
| --- | --- | --- |
| `401` | `Invalid API key` (wrong or switched-off key), `Missing API key` (empty header) or `Vendor inactive` | Check the `X-API-Key` header and that the key is on in the dashboard |
| `403` | Your vendor application is still pending (on any call), or the account is not an approved vendor (key creation) | Wait for approval |
| `404` | Unknown `external_id` or `order_id` | Check the ID; sync the plan first |
| `409` | Delivering credentials to an order that is no longer paid or active | Usually the 120 seconds passed and the order was refunded. Do not retry |
| `422` | A value is not valid, or the `X-API-Key` header is missing altogether | `detail` in the answer names the field |
| `500` | ProxyMarket error | Retry with a growing delay |

Errors come back as `{"detail": "…"}`. There are no published rate limits; sync on change rather than in a tight loop.

## Is there a full example?

Yes. This Python connector syncs one proxy plan, reports health every 5 minutes and answers all four webhooks. Replace the two functions at the top with calls to your own system, and add a timer that ends each order when its time is up.

```python
"""Minimal ProxyMarket connector: sync plans, report health, answer the four webhooks."""
import hashlib
import hmac
import os
import secrets
import threading
import time

import requests
from flask import Flask, jsonify, request

API_KEY = os.environ["PROXYMARKET_API_KEY"]          # pm_... from "Create your API key"
MARKET = "https://market.xproxy.io/api/integration"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
SIGNING_KEY = hashlib.sha256(API_KEY.encode()).hexdigest()

# ── Your system (replace with your own code) ─────────────────────────
PORTS = {
    "port-1": {"name": "US Mobile 4G - Port 1", "country": "United States", "protocol": "HTTP",
               "price": 25.00, "days": 30, "online": True, "ip": "203.0.113.1", "port": 8080},
}

def add_proxy_login(port_id, username, password): ...   # create the customer's login
def remove_proxy_login(port_id, order_id): ...          # delete it again

# ── Calls you make ───────────────────────────────────────────────────
def sync_plans():
    plans = [{
        "external_id": pid, "name": p["name"], "proxy_type": "mobile", "protocol": p["protocol"],
        "country": p["country"], "duration_days": p["days"], "price_usd": p["price"],
        "stock": 1 if p["online"] else 0, "is_active": p["online"],
    } for pid, p in PORTS.items()]
    r = requests.post(f"{MARKET}/plans/sync", json=plans, headers=HEADERS, timeout=15)
    print("[sync]", r.status_code, r.json())

def set_stock(port_id, free):
    requests.patch(f"{MARKET}/plans/stock", headers=HEADERS, timeout=15,
                   json=[{"external_id": port_id, "stock": 1 if free else 0, "is_active": free}])

def health_reporter():
    while True:
        try:
            reports = [{"external_id": pid, "status": "online" if p["online"] else "offline",
                        "current_ip": p["ip"]} for pid, p in PORTS.items()]
            requests.post(f"{MARKET}/health", json=reports, headers=HEADERS, timeout=15)
        except requests.RequestException as e:
            print("[health]", e)
        time.sleep(300)  # every 5 minutes

# ── Webhooks ProxyMarket calls ───────────────────────────────────────
app = Flask(__name__)

def signed():
    expected = "sha256=" + hmac.new(SIGNING_KEY.encode(), request.get_data(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, request.headers.get("X-Signature", ""))

@app.route("/health", methods=["HEAD", "GET"])
def health():
    return "", 200

@app.route("/provision", methods=["POST"])
def provision():
    if not signed():
        return jsonify({"status": "error", "message": "Invalid signature"}), 401
    data = request.get_json()
    port = PORTS.get(data["external_plan_id"])
    if not port or not port["online"]:
        return jsonify({"status": "error", "message": "Port offline"})  # ProxyMarket refunds the customer
    username = f"cust_{data['order_id'][:8]}"
    password = secrets.token_urlsafe(16)
    add_proxy_login(data["external_plan_id"], username, password)
    set_stock(data["external_plan_id"], free=False)
    return jsonify({
        "status": "provisioned",
        "proxy_ip": port["ip"], "proxy_port": port["port"],
        "proxy_username": username, "proxy_password": password,
    })

@app.route("/deprovision", methods=["POST"])
def deprovision():
    if not signed():
        return jsonify({"status": "error", "message": "Invalid signature"}), 401
    data = request.get_json()
    remove_proxy_login(data["external_plan_id"], data["order_id"])  # must be safe to run twice
    set_stock(data["external_plan_id"], free=True)
    return jsonify({"status": "deprovisioned"})

@app.route("/update-settings", methods=["POST"])
def update_settings():
    if not signed():
        return jsonify({"status": "error", "message": "Invalid signature"}), 401
    data = request.get_json()
    # data["ip_whitelist"]: [] = allow everyone, None = leave as it is
    # data["tcp_fingerprint"]: "win1", "ios1", ... or None = no spoofing
    return jsonify({"status": "ok"})  # apply what you support, ignore the rest

if __name__ == "__main__":
    sync_plans()
    threading.Thread(target=health_reporter, daemon=True).start()
    # Serve this behind HTTPS at your webhook_url, for example https://your-vendor-host.com/marketplace
    app.run(host="0.0.0.0", port=9090)
```

## Where is the full API reference?

Every call and webhook, with all fields, example answers and code in curl, Python, Node.js and PHP, is in the [ProxyMarket API reference](https://xproxy.io/docs/api/market/sync-plans). The OpenAPI 3.1 file is at [market.openapi.yaml](https://xproxy.io/docs/api/market.openapi.yaml).

| Direction | Endpoint | What it does |
| --- | --- | --- |
| You call | [`POST /api/vendor/integrations`](https://xproxy.io/docs/api/market/create-integration-key) | Create your API key |
| You call | [`POST /plans/sync`](https://xproxy.io/docs/api/market/sync-plans) | Publish or update plans |
| You call | [`PATCH /plans/stock`](https://xproxy.io/docs/api/market/update-stock) | Change stock and visibility |
| You call | [`DELETE /plans/{external_id}`](https://xproxy.io/docs/api/market/deactivate-plan) | Take a plan off sale |
| You call | [`POST /health`](https://xproxy.io/docs/api/market/report-health) | Report the state of your proxies |
| You call | [`POST /orders/{order_id}/credentials`](https://xproxy.io/docs/api/market/push-credentials) | Deliver a login or config late |
| You call | [`POST /orders/{order_id}/expire`](https://xproxy.io/docs/api/market/expire-order) | Mark an order expired (no refund) |
| We call you | [`HEAD /health`](https://xproxy.io/docs/api/market/webhook-health) | Health check that keeps your plans listed |
| We call you | [`POST /provision`](https://xproxy.io/docs/api/market/provision-webhook) | A customer paid: deliver |
| We call you | [`POST /deprovision`](https://xproxy.io/docs/api/market/deprovision-webhook) | An order ended: remove access |
| We call you | [`POST /update-settings`](https://xproxy.io/docs/api/market/update-settings-webhook) | Apply a new IP whitelist or TCP fingerprint |
| You call | [`GET /orders/active`](https://xproxy.io/docs/api/market/list-active-orders) | The paid and active orders routed to your key |

## Which countries can I list?

Any. Send the full English country name, for example `United States`, `Germany` or `Vietnam`, and spell it the same way on every plan: customers filter by the exact text. ProxyMarket does not check the name; the list in the guide and in the vendor dashboard is the spelling to use. `pm-connector test` rejects a name that is not on that list.

## What changed in version 1.13?

- **New call:** [List the orders routed to your key](https://xproxy.io/docs/api/market/list-active-orders) (`GET /orders/active`, with `routed_plans` and ETag), for catching up after downtime.
- **Safer fallback:** a delivered login is no longer copied onto the plan, and a plan login or rotation link that belongs to another order is never handed out.
- **Provision timing:** `/provision` is sent only once the payment is committed, so an immediate credential push is accepted. `/update-settings` always carries the values the customer just saved.
- **ProxyMarket connector:** a ready-made webhook server, including how to reach it behind NAT. See [the connector](#connector).
- **Encrypted provision answer** (optional): on a plain `http://` webhook URL, seal your `/provision` answer with `X-PM-Encrypted: v1`. See [above](#encrypted-answer).
- **Plan pinning:** a plan created by a sync goes to the key that synced it.
- **Rotation:** ProxyMarket calls your `rotation_link` with `GET`. See [IP rotation](#rotation).
- **Integration Status tab** in the vendor dashboard, and the optional `X-PM-Connector` header.
- **Written down to match the code:** 422 without an `X-API-Key` header, 403 while your application is pending, 30-second provision timeout, unvalidated country and sync port, `protocol` defaults to HTTP, a `/health` report without `current_ip` clears it, the OpenVPN `&lt;ca>` rule, and no `external_plan_id` in `/update-settings`.

## FAQ

### I run XProxy. Do I need to build this?

No. Turn on ProxyMarket in the panel (Selling Platform → ProxyMarket) and it does all of this for you, including the webhooks. See [Sell on ProxyMarket](https://xproxy.io/document/proxymarket). Your plans then also get the `xProxy` badge.

### Why did all my plans disappear from the shop?

Almost always the health check: `HEAD {webhook_url}/health` failed twice in a row (down, slower than 5 seconds, a 5xx, or `HEAD` blocked). Fix it and the plans come back after the next good check, within 10 minutes.

### I lost my API key. Can ProxyMarket send it again?

No. Only a hash is stored. Create a new key, and remember that the signing key changes with it.

### My signature check always fails. Why?

Usually one of two things: you used the raw API key as the HMAC secret instead of `SHA256(api_key)` in hex, or you signed parsed and re-encoded JSON instead of the raw request body.

### Do I get paid if my server fails to deliver?

No. If nothing usable arrives within 120 seconds, the customer is refunded and the earning is removed from your balance.

### Why did a customer get an old login?

Your `/provision` answered with a status other than 200, timed out or sent invalid JSON, so ProxyMarket gave the login you synced on the plan. A delivered login is never saved on the plan, and the plan login is not reused when it already belongs to another order (that order is refunded instead). Always answer 200, with `error` if you cannot deliver.

### Can I connect several servers?

Yes. Create one key per server, each with its own webhook URL. A plan created by a sync goes to the key that synced it; for older plans, set **API Key / Server** in the dashboard, or their orders go to your oldest key.

### What happens when a customer renews?

Renewing an expired order is a normal new order. Renewing a running one first sends `/deprovision` with `reason: renewed` for the old order, then `/provision` for the new one, with a new `order_id`.

## What next?

Open the full reference, or ask ProxyMarket on Telegram.

[API reference →](https://xproxy.io/docs/api/market/sync-plans) [Telegram @xproxyio →](https://t.me/xproxyio) [Sell on ProxyMarket with XProxy →](https://xproxy.io/document/proxymarket)

---

Source: https://xproxy.io/document/proxymarket-vendor-integration
