# PROXY KING API

Base URL: https://proxyking.com.ng/api/public/v1
JSON in and out. Amounts are whole Naira (NGN). Products use PKP-#### numbers, orders use PKO-XXXX-XXXX IDs.

## Authentication
Every request must send your API key in the Authorization header as a Bearer token. Create or rotate your key from API Documentation in the menu on proxyking.com.ng (up to 5 keys). Keep it secret: anyone holding it can spend your wallet balance. Never put it in browser code; call the API from your own server.
Header: Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx

## GET /balance — Get wallet balance
Returns the Naira balance available for purchases.
Request:
curl https://proxyking.com.ng/api/public/v1/balance \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx"
Response:
{
  "ok": true,
  "data": { "balance": 15250, "currency": "NGN" }
}

## GET /products — List products
Returns every product currently on sale, with price and live stock.
Parameters:
- category (string): Category slug to filter by, e.g. 711proxy.
- in_stock (boolean): true returns only products with stock > 0.
Request:
curl "https://proxyking.com.ng/api/public/v1/products?in_stock=true" \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx"
Response:
{
  "ok": true,
  "data": [
    {
      "product_no": "PKP-0001",
      "name": "9PROXY 50 IPs",
      "category": "9proxy",
      "price": 4500,
      "currency": "NGN",
      "stock": 120,
      "description": "Residential proxy redeem key ..."
    }
  ]
}

## GET /products/{product_no} — Get one product
Returns a single product by its PKP number.
Parameters:
- product_no (string, required): Product number, e.g. PKP-0001.
Request:
curl https://proxyking.com.ng/api/public/v1/products/PKP-0001 \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx"
Response:
{
  "ok": true,
  "data": {
    "product_no": "PKP-0001",
    "name": "9PROXY 50 IPs",
    "category": "9proxy",
    "price": 4500,
    "currency": "NGN",
    "stock": 120,
    "description": "Residential proxy redeem key ..."
  }
}

## POST /orders — Buy a product
Charges your wallet and returns the redeem keys. The order fails with insufficient_balance if your wallet cannot cover price × quantity. Send an Idempotency-Key header so a retried request never buys twice.
JSON body:
- product_no (string, required): Product number, e.g. PKP-0001.
- quantity (integer, required): 1 to 1000 in one order (bulk), up to the current stock.
Request:
curl -X POST https://proxyking.com.ng/api/public/v1/orders \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b9e-order-001" \
  -d '{ "product_no": "PKP-0001", "quantity": 2 }'
Response:
{
  "ok": true,
  "data": {
    "order_id": "PKO-7KQ2-M9XD",
    "status": "delivered",
    "product_no": "PKP-0001",
    "quantity": 2,
    "total": 9000,
    "currency": "NGN",
    "keys": ["XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY"],
    "created_at": "2026-10-27T15:40:00Z"
  }
}

## GET /orders — List your orders
Returns your orders, newest first. Keys are not included in the list; fetch one order to read them.
Parameters:
- limit (integer): 1–100, default 20.
- cursor (string): Value of next_cursor from the previous page.
Request:
curl "https://proxyking.com.ng/api/public/v1/orders?limit=20" \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx"
Response:
{
  "ok": true,
  "data": [
    {
      "order_id": "PKO-7KQ2-M9XD",
      "status": "delivered",
      "product_no": "PKP-0001",
      "quantity": 2,
      "total": 9000,
      "created_at": "2026-10-27T15:40:00Z"
    }
  ],
  "next_cursor": null
}

## GET /orders/{order_id} — Get one order
Returns a single order with its delivered keys.
Parameters:
- order_id (string, required): Order ID, e.g. PKO-7KQ2-M9XD.
Request:
curl https://proxyking.com.ng/api/public/v1/orders/PKO-7KQ2-M9XD \
  -H "Authorization: Bearer ProxyKing-xxxxxxxxxxxxxxxxxxxxxxxx"
Response:
{
  "ok": true,
  "data": {
    "order_id": "PKO-7KQ2-M9XD",
    "status": "delivered",
    "product_no": "PKP-0001",
    "quantity": 2,
    "total": 9000,
    "keys": ["XXXX-XXXX-XXXX", "YYYY-YYYY-YYYY"],
    "created_at": "2026-10-27T15:40:00Z"
  }
}

## Order statuses
- delivered: Keys are ready in the keys array.
- processing: Payment taken, keys on the way. Check again in a few seconds with GET /orders/{order_id}.
- refunded: The order could not be filled and the money went back to your wallet.
- failed: Nothing was charged.

## Errors
{
  "ok": false,
  "error": { "code": "insufficient_balance", "message": "Wallet balance is too low for this order." }
}
- unauthorized (HTTP 401): Missing, wrong or revoked API key.
- insufficient_balance (HTTP 402): Your wallet cannot cover price × quantity. Fund your wallet and retry.
- not_found (HTTP 404): No product or order with that number.
- out_of_stock (HTTP 409): Requested quantity is more than the current stock.
- price_changed (HTTP 409): The price changed while ordering. Fetch the product again and retry.
- invalid_request (HTTP 422): A field is missing or has the wrong type.
- rate_limited (HTTP 429): Too many requests. Wait and retry; limit is 60 requests per minute per key.
- server_error (HTTP 500): Something went wrong on our side. Safe to retry with the same Idempotency-Key.