API v1 — YTMarket

1. 获取 API 密钥

密钥仅由管理员签发 — 无自助注册。请联系 Telegram 客服，主题 "API key"，附上您的邮箱/项目。限流：每密钥每分钟 60 次请求（超出 HTTP 429）。密钥 + HMAC secret 会一起签发并只显示一次 — 请立即保存。 客服.

2. 鉴权

X-API-Key: YOUR_KEY_HERE

每个请求都需要该 header。缺失或无效 → HTTP 401 Unauthorized。

3. 目录（只读）

GET /v1/health

密钥校验 + 可用性探针。

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

GET /v1/products

带筛选的目录。Query 参数：

• 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}

单个商品详情（按 ID）。

GET /v1/categories

类目列表，含商品数量 + 最低价。

4. 余额与充值

GET /v1/balance

当前密钥余额 + 已花费/已充值/已退款总额。

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

创建充值意向 → 获取 USDT 地址。客户选择金额和网络。请求体：

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}

USDT 到账后 — 余额自动入账（cron 每 5 秒扫描入账 TX）。地址与网站购买共用（每个网络一个主钱包），意向通过金额区分。

⏱ 完整充值生命周期

1. T+0:00 — 客户：POST /v1/balance/topup {amount_usdt: 100, network: "usdt_trc_20"}
2. T+0:00 — API 创建 `topup_id`，返回 `payment_address`（你的主钱包）+ `amount_usdt: 100` + `expires_at: now+1h`
3. T+0:30 — 客户从自己的钱包发送 100 USDT（TRC-20）到该地址
4. T+0:55 — TRC-20 确认（~20 秒 / 3-5 块）
5. T+1:00 — backend（每 5 秒）发现入账 TX，按精确金额查找待匹配充值意向
6. T+1:05 — backend 按 amount ±$0.01 匹配存款与你的意向 → BAL +100，status=credited_auto
7. T+1:05 — 客户：GET /v1/balance → balance_usdt: 100.0 ✓

📋 响应字段 — 每个的含义

⚠️ Edge cases — 不一致时的处理

5. 订单（余额扣款）

POST /v1/orders

创建订单 + 自动扣款 + 系统履约。失败/过期/取消时 — 余额自动退还（响应和 webhook 中的 `refunded` 字段）。

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}

若余额 < 价格 → HTTP 402 Payment Required + 充值指引。

⚠️ 每个商品的最低批量由 `min_quantity` 字段指定。若请求的 `quantity` 低于该值 → HTTP 400，提示所需最低数量。

GET /v1/orders/{id}

订单状态 + 完成时返回 items[] 凭据。仅限创建该订单的密钥访问（404 表示非本人）。

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 通知

POST /v1/orders 中传入 `webhook_url` — 状态变更时（completed/partial/failed/expired/cancelled/refunded）我们 POST JSON 到该地址。

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
}

期望 HTTP 2xx 响应。5xx/超时 — 最多 5 次指数退避重试。5 次失败后标记为 fired。

7. 使用统计

GET /v1/usage

按密钥统计：请求数、最近活跃、累计花费、累计退款。

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. 账号交付

交付时长：`status=processing` 之后 30 秒 — 10 分钟。异步处理 — 轮询 GET /v1/orders/{id} 或注册 webhook。

1. POST /v1/orders → status=processing
2. 异步处理（30s-10min）
3. 成功 → status=completed
4. GET /v1/orders/{id} → items[]
5. Webhook 触发（如已注册）

9. USDT 网络与手续费

10. 限制与计费

• 限流：每密钥每分钟 60 次（HTTP 429 + Retry-After）
• API 价格 = 网站价格（无加价）
• page_size：1-200（默认 50）
• 订单 quantity：1-10000
• 充值：1-100000 USDT
• Webhook 超时 10s，最多 5 次重试
• 自动退款：failed/expired/cancelled 时余额自动返还（cron 每 30s）

11. 错误码

• 401 — 无效的 X-API-Key
• 402 — 余额不足
• 404 — 商品/订单未找到
• 409 — 库存不足
• 422 — 请求体非法
• 429 — 触发限流（60/min）
• 501 — 发票模式未实现
• 503 — Redis 不可用

11.5 安全（HMAC + IP 白名单）

生产密钥的可选额外防护。通过联系管理员开启。

HMAC 请求体签名（POST /orders + /topup）

签发密钥时管理员可附带 HMAC secret（仅显示一次）。密钥有 secret 时，POST 请求需要两个额外 header。公式：

X-Timestamp = Unix 时间戳秒（与服务器漂移 ≤5 分钟）
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())

防护对象：重放攻击、MITM 篡改、密钥意外泄露（没有 secret 无法生成签名）。若未签发 secret — 向后兼容，不要求签名。

IP 白名单

可为密钥配置 允许的 IP。白名单为空时不校验 IP（默认）。若有至少一个 IP，其他来源返回 HTTP 403。

审计日志

所有 admin 操作（mint/revoke/credit/topup credited/rotate secret/whitelist）写入数据库表 `api_audit_log`。管理员可通过 bot 命令 `/api_audit` 或接口 `GET /api/admin/api-audit` 查看最近 50 条。

🧪 立即试用 — 交互式 Playground

在下方粘贴你的 X-API-Key，点击任意按钮 — 请求将直接从本页发送到 API。POST 端点的 HMAC 签名会在浏览器自动计算（如果你的密钥有 secret）。

12. SDK 示例

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 — 常见问题

13. Postman / Changelog / 支持

Postman 集合

下载所有 endpoints 的现成 Postman 集合： 下载 .postman_collection.json

变更日志

• v1.4 (2026-05-23) — 最低批量限制（600₽ 或供应商 min_quantity）；自动入账 cron 120s→5s；跨平台动态定价 +1%/15分钟 同样适用于 API；Webhook HMAC 签名（X-Webhook-Signature header）；/api/docs 中加入 Try-it playground。
• v1.3 (2026-05-23) — failed/expired/cancelled 自动退款，新增 `refunded` 字段，paid→processing 映射，响应含 `created_at`/`updated_at`。
• v1.2 (2026-05-23) — 余额系统，POST /orders 余额扣款，webhook cron。
• v1.1 (2026-05-23) — 限流 60/min/key，按密钥统计。
• v1.0 (2026-05-23) — 只读目录接口（products/categories/health）。

支持

API 问题：Telegram 客服。SLA：工作时段 30 分钟（08:00-22:00 MSK）。 Telegram.