API v1 — YTMarket

1. Getting an API key

Keys are issued by admin only — no self-signup. Message Telegram support with subject "API key" + your email/project. Limit: 60 requests/minute per key (HTTP 429 on exceed). Key + HMAC secret are issued together and shown only once — save immediately. support.

2. Authentication

X-API-Key: YOUR_KEY_HERE

Every request requires the header. Missing or invalid → HTTP 401 Unauthorized.

3. Catalog (READ-ONLY)

GET /v1/health

Key validation + uptime probe.

curl -H "X-API-Key: $KEY" https://ytmarket.pro/api/v1/health
# {"status":"ok","timestamp":1779497200}

GET /v1/products

Catalog with filters. Query params:

• category, sku
• min_price, max_price (float, USDT)
• min_qty (default 1), page (default 1), page_size (default 50, max 200)

curl -H "X-API-Key: $KEY" \
  "https://ytmarket.pro/api/v1/products?min_price=1&page=1&page_size=50"

GET /v1/products/{id}

Single-product details by ID.

GET /v1/categories

Category list with product counts + min prices.

4. Balance & top-up

GET /v1/balance

Current key balance + total spent/topped-up/refunded.

curl -H "X-API-Key: $KEY" https://ytmarket.pro/api/v1/balance
# {"balance_usdt": 50.0, "total_spent_usdt": 12.5,
#  "total_topup_usdt": 62.5, "total_refunded_usdt": 1.2,
#  "currency": "USDT"}

POST /v1/balance/topup

Create a top-up intent → get USDT address. Client picks amount + network. Body:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"amount_usdt": 100, "network": "usdt_trc_20"}' \
  https://ytmarket.pro/api/v1/balance/topup

# {"topup_id": "abc123...", "payment_address": "TYz...",
#  "payment_network": "usdt_trc_20", "amount_usdt": 100.0,
#  "expires_at": 1779500800}

After USDT arrives at the address — balance is automatically credited (cron scans incoming TX every 5 sec). Addresses are shared with website purchases (one master wallet per network); intents are distinguished by amount.

⏱ Full top-up lifecycle

1. T+0:00 — client: POST /v1/balance/topup {amount_usdt: 100, network: "usdt_trc_20"}
2. T+0:00 — API creates `topup_id`, returns `payment_address` (your master) + `amount_usdt: 100` + `expires_at: now+1h`
3. T+0:30 — client sends 100 USDT (TRC-20) from their wallet to that address
4. T+0:55 — TRC-20 confirms (~20 sec / 3-5 blocks)
5. T+1:00 — backend (every 5s) sees incoming TX, searches pending intents by exact amount
6. T+1:05 — backend matches the deposit by amount ±$0.01 with your intent → BAL +100, status=credited_auto
7. T+1:05 — client: GET /v1/balance → balance_usdt: 100.0 ✓

📋 Response fields — what each means

⚠️ Edge cases — what if something is off

5. Orders (balance-debit)

POST /v1/orders

Create order + auto-debit balance + system fulfilment. On failed/expired/cancelled — balance is auto-refunded (`refunded` field in response and webhook).

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"product_id": 12345, "quantity": 10,
       "payment_method": "balance",
       "webhook_url": "https://your.app/api-cb"}' \
  https://ytmarket.pro/api/v1/orders

# {"order_id": 789, "status": "processing",
#  "price_usdt": 12.34, "quantity": 10, "refunded": false,
#  "created_at": 1779497200, "updated_at": 1779497200}

If balance < price → HTTP 402 Payment Required with top-up instruction.

⚠️ Minimum batch per product is in `min_quantity` field. If requested `quantity` is below this minimum → HTTP 400 with the exact required amount.

GET /v1/orders/{id}

Order status + items[] with credentials when completed. Key-scoped (404 if not yours).

curl -H "X-API-Key: $KEY" https://ytmarket.pro/api/v1/orders/789

# {"order_id": 789, "status": "completed", "refunded": false,
#  "price_usdt": 12.34, "quantity": 10,
#  "items": [{"login": "...", "password": "...", ...}],
#  "created_at": 1779497200, "updated_at": 1779497500}

6. Webhook notifications

Pass `webhook_url` in POST /v1/orders — we POST JSON there on status change (completed/partial/failed/expired/cancelled/refunded).

POST $YOUR_WEBHOOK_URL
Content-Type: application/json

{
  "order_id": 789,
  "status": "completed",
  "price_usdt": 12.34,
  "quantity": 10,
  "product_id": 12345,
  "items": [{"login": "...", "password": "...", ...}],
  "error_message": null,
  "refunded": false,
  "fired_at": 1779497200
}

Expects HTTP 2xx response. On 5xx/timeout — up to 5 retries with exp-backoff. After 5 fails webhook is marked fired.

7. Usage metrics

GET /v1/usage

Per-key statistics: request count, last activity, total spent, refunded.

curl -H "X-API-Key: $KEY" https://ytmarket.pro/api/v1/usage
# {"request_count": 1234, "last_used_at": 1779497200,
#  "first_used_at": 1779480000, "last_endpoint": "/api/v1/products",
#  "total_spent_usdt": 125.50}

8. Account delivery

Delivery time: 30 seconds — 10 minutes after `status=processing`. Processed async — poll GET /v1/orders/{id} or register webhook.

1. POST /v1/orders → status=processing
2. Async processing (30s-10min)
3. On success → status=completed
4. GET /v1/orders/{id} → items[]
5. Webhook fired (if registered)

9. USDT networks & fees

10. Limits & pricing

• Rate-limit: 60 requests/min/key (HTTP 429 + Retry-After header)
• API price = website price (no markup)
• page_size: 1-200 (default 50)
• order quantity: 1-10000 units
• Top-up: 1-100000 USDT
• Webhook timeout 10s, up to 5 retries
• Auto-refund: balance returned on failed/expired/cancelled (cron every 30s)

11. Error codes

• 401 — invalid X-API-Key
• 402 — insufficient balance
• 404 — product/order not found
• 409 — insufficient stock
• 422 — invalid request body
• 429 — rate-limit (60/min)
• 501 — invoice mode not implemented
• 503 — Redis down

11.5 Security (HMAC + IP whitelist)

Additional defenses for production keys. Opt-in via admin request.

HMAC body signing (POST /orders + /topup)

On key mint, admin may issue an HMAC secret (shown once). If a key has a secret, POST requests must include 2 extra headers. Formula:

X-Timestamp = unix epoch seconds (≤5 min drift from server)
X-Signature = hmac_sha256(secret, f"{timestamp}\n{request_body}").hex()

# Python example
import hmac, hashlib, time, json, requests
KEY = "..."; SECRET = "..."
BASE = "https://ytmarket.pro/api/v1"
body = json.dumps({"product_id": 12345, "quantity": 1, "payment_method": "balance"})
ts = str(int(time.time()))
sig = hmac.new(SECRET.encode(), f"{ts}\n{body}".encode(), hashlib.sha256).hexdigest()
r = requests.post(f"{BASE}/orders", data=body, headers={
    "X-API-Key": KEY,
    "Content-Type": "application/json",
    "X-Timestamp": ts,
    "X-Signature": sig,
})
print(r.status_code, r.json())

Protects against: replay attack, MITM tampering, accidental key leak (signature is invalid without secret). If no secret was issued — backward-compat, signature not required.

IP whitelist

Admin can add allowed IPs for a key. If whitelist is empty — no IP check (default). If at least one IP is present — all others get HTTP 403.

Audit log

All admin actions (mint/revoke/credit/topup credited/rotate secret/whitelist) are written to the DB table `api_audit_log`. Admin can list last 50 via bot command `/api_audit` or endpoint `GET /api/admin/api-audit`.

🧪 Try it now — interactive playground

Paste your X-API-Key below and click any button — the request fires directly from this page to our API. For POST endpoints, HMAC signature is computed in the browser automatically (if your key has a secret).

12. SDK examples

Python (requests)

import requests
KEY = "YOUR_API_KEY"
BASE = "https://ytmarket.pro/api/v1"
headers = {"X-API-Key": KEY}

# 1. List products
products = requests.get(f"{BASE}/products", headers=headers,
                         params={"min_price": 1, "page_size": 50}).json()

# 2. Check balance
bal = requests.get(f"{BASE}/balance", headers=headers).json()
print(f"Balance: {bal['balance_usdt']} USDT")

# 3. Create order (balance-debit)
order = requests.post(f"{BASE}/orders", headers=headers, json={
    "product_id": products["items"][0]["id"],
    "quantity": 1,
    "payment_method": "balance",
    "webhook_url": "https://your.app/cb",
}).json()
print(f"Order #{order['order_id']} {order['status']}")

# 4. Poll until final
import time
while True:
    o = requests.get(f"{BASE}/orders/{order['order_id']}", headers=headers).json()
    if o["status"] in ("completed", "failed", "expired", "cancelled"):
        break
    time.sleep(5)
print(f"Final: {o['status']}, items={o.get('items')}, refunded={o.get('refunded')}")

Node.js (axios)

import axios from "axios";

const KEY = process.env.API_KEY;
const api = axios.create({
  baseURL: "https://ytmarket.pro/api/v1",
  headers: { "X-API-Key": KEY },
});

// 1. List products
const { data: products } = await api.get("/products", { params: { min_price: 1 } });

// 2. Create order
const { data: order } = await api.post("/orders", {
  product_id: products.items[0].id,
  quantity: 1,
  payment_method: "balance",
  webhook_url: "https://your.app/cb",
});

// 3. Poll
let o;
while (true) {
  o = (await api.get(`/orders/${order.order_id}`)).data;
  if (["completed", "failed", "expired", "cancelled"].includes(o.status)) break;
  await new Promise(r => setTimeout(r, 5000));
}
console.log("Final:", o.status, "items:", o.items, "refunded:", o.refunded);

Go (net/http)

package main

import (
  "bytes"; "encoding/json"; "fmt"; "io"; "net/http"
)

func main() {
  body, _ := json.Marshal(map[string]any{
    "product_id": 12345, "quantity": 1, "payment_method": "balance",
  })
  req, _ := http.NewRequest("POST", "https://ytmarket.pro/api/v1/orders", bytes.NewReader(body))
  req.Header.Set("X-API-Key", "YOUR_KEY")
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  b, _ := io.ReadAll(resp.Body); fmt.Println(string(b))
}

curl

# Full flow in 4 curls
KEY=YOUR_API_KEY
BASE=https://ytmarket.pro/api/v1

curl -H "X-API-Key: $KEY" "$BASE/products?min_price=1&page_size=5"
curl -H "X-API-Key: $KEY" "$BASE/balance"
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"product_id":12345,"quantity":1,"payment_method":"balance"}' \
  "$BASE/orders"
curl -H "X-API-Key: $KEY" "$BASE/orders/789"

🙋 FAQ — frequently asked questions

13. Postman / Changelog / Support

Postman collection

Download a ready Postman collection for all endpoints: Download .postman_collection.json

Changelog

• v1.4 (2026-05-23) — Min-purchase enforcement (per-product min_quantity + 600₽ floor); auto-credit cron 120s→5s; cross-platform dynamic pricing +1%/15min also applies via API; webhook HMAC signing (X-Webhook-Signature header); Try-it playground in /api/docs.
• v1.3 (2026-05-23) — Auto-refund on failed/expired/cancelled, `refunded` field, status maps paid→processing, `created_at`/`updated_at` in response.
• v1.2 (2026-05-23) — Balance system, POST /orders with balance-debit, webhook cron.
• v1.1 (2026-05-23) — Rate-limit 60/min/key, per-key metrics.
• v1.0 (2026-05-23) — Read-only catalog endpoints (products/categories/health).

Support

API questions: Telegram support. SLA: 30 min during work hours (08:00-22:00 MSK). Telegram.