Market API

REST Architecture

A strictly typed, highly atomic engine. Securely drain wallet balances and synchronously map dynamic admin-altered constraints into your SaaS.

-H "X-API-Key: sk_live_a1b2c3d4..."

Type & Error Constraints

• 401
  Unauthorized HeaderX-API-Key is invalid, blank, missing, or compromised.
• 402
  Insufficient Funds (NSF)Volatile balance calculation failed the lock. Refuse service.
• 403
  Forbidden / SuspendedAccount permanently banned. API globally suspended for token.
• 404
  Not FoundProduct deleted by admin, or order doesn't belong to you.
• 409
  Stock ConflictRace condition: stock was purchased by another buyer between your catalog read and checkout.
• 429
  Rate LimitedToo many requests. GET endpoints: 60/min. POST endpoints: 20/min. Per API key. Retry after the Retry-After header value.
• 503
  Service UnavailableMarketplace Maintenance Mode active or API globally disabled by admin.

curl -X GET "https://api.bunaistore.shop/v1/me" \
  -H "X-API-Key: YOUR_KEY"

{
  "user_id": 12345678,
  "display_name": "Premium Dev",
  "balance": 1500.50,
  "api_orders": 45,
  "api_spent": 142.00
}

Data Dictionary

curl -X GET \
  "https://api.bunaistore.shop/v1/products?view=variants&type=auto&limit=10" \
  -H "X-API-Key: YOUR_KEY"

[
  {
    "product_id": "ab360422",
    "group_id": "d8b627d5",
    "group_name": "Amazon Prime",
    "variant_name": "1 month",
    "display_name": "Amazon Prime > 1 month",
    "price": 1.00,
    "stock_type": "manual",
    "stock_count": 11,
    "infinite_stock": false,
    "warranty_hours": 1,
    "has_promo": false,
    "group_share_path": "/group_d8b627d5",
    "plan_share_path": "/plan_ab360422_d8b627d5"
  }
]

Query Parameters

Response Fields

curl -X GET \
  "https://api.bunaistore.shop/v1/products/PRD_ajS8x" \
  -H "X-API-Key: YOUR_KEY"

{
  "product_id": "PRD_ajS8x",
  "name": "Netflix Premium",
  "note": "Read TOS before buying.",
  "price": 3.50,
  "stock_type": "auto",
  "stock_count": 12,
  "infinite_stock": false,
  "warranty_hours": 720,
  "promo_active": true,
  "promo_cb": 5.0,
  "promo_tiers": {"5": 5.0, "10": 12.0}
}

Extra Properties (vs List)

curl -X POST "https://api.bunaistore.shop/v1/orders" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "PRD_XYZ",
    "qty": 1
  }'

{
  "status": "success",
  "order": {
    "order_id": "ORDx8kLm2Qp",
    "product_id": "PRD_ajS8x",
    "product_name": "Netflix Premium",
    "qty": 3,
    "timestamp": "2024-06-19T14:32:07",
    "base_price": 10.50,
    "total_paid": 9.98,
    "discount_applied": 0.52,
    "stock_type": "auto",
    "items": [
      "Full account details...\nRegion: US\nPlan: Premium...",
      "Full account details...\nRegion: CA\nPlan: Premium...",
      "Full account details...\nRegion: UK\nPlan: Premium..."
    ],
    "warranty_expires": "2024-07-19T14:32:07",
    "refunded": false,
    "after_note": "Use CA VPN for login."
  }
}

Payload Architecture

curl -X GET \
  "https://api.bunaistore.shop/v1/orders/ORD_1A..." \
  -H "X-API-Key: YOUR_KEY"

{
  "order": {
    "order_id": "ORD_1A...",
    "product_id": "PRD_ajS8x",
    "product_name": "Netflix Premium",
    "qty": 1,
    "timestamp": "2024-06-19T...",
    "total_paid": 3.50,
    "stock_type": "auto",
    "items": ["email:pass"],
    "warranty_expires": "2024-07-19T...",
    "refunded": false,
    "after_note": "Use Canada VPN."
  }
}

Key Differences vs POST

Returns all deposit addresses for every payment method. The enabled field reflects the admin toggle in real-time — never hardcode addresses or assume a method is always active.

curl -X GET "https://api.bunaistore.shop/v1/topup/addresses" \
  -H "X-API-Key: YOUR_KEY"

{
  "bep20":   { "enabled": true,  "address": "0xAbC1...", "network": "BSC (BEP-20)",   "token": "USDT",       "submit_txid": true  },
  "ton":     { "enabled": true,  "address": "UQAbc...", "network": "TON",           "token": "USDT/TON",   "submit_txid": true  },
  "trx":     { "enabled": true,  "address": "TXyz...",  "network": "TRON (TRC-20)", "token": "USDT/TRX",   "submit_txid": true  },
  "binance": { "enabled": true,  "pay_id": "123456789", "name": "BunaiStore", "submit_order_id": true, "order_id_format": "numeric string" }
}

Submit a payment for background verification. Accepted for all 4 methods. Returns immediately with 202 — verification runs async. On success, topup_completed + balance_updated webhooks fire automatically.

// Blockchain (BEP20 / TON / TRX)
{
  "method": "bep20",   // bep20 | ton | trx
  "txid":   "0x1a2b3c..."
}

// Binance Pay (Order ID, not TXID)
{
  "method": "binance",
  "txid":   "40123456789"  // numeric string
}

{
  "status":  "success",
  "message": "Payment verification started in background"
}

// Fires automatically when confirmed:
// webhook → topup_completed
// webhook → balance_updated

Error Responses

Async Verification Outcomes

After a 202, verification runs in the background. The following outcomes are not HTTP errors — they fire through your registered webhook or are silently logged:

Global Verification Limits

40123456789   ✓ digits only
4.012e10      ✗ not numeric
BNBP_12345   ✗ not numeric

Signature Verification

Every webhook includes an X-Webhook-Signature header — an HMAC-SHA256 hex digest of the raw POST body signed with your API Key. Always verify before processing.

import hmac, hashlib

def verify(api_key, body, sig):
    expected = hmac.new(
        api_key.encode(),
        body,  # raw bytes
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        expected, sig
    )

const crypto = require('crypto');

function verify(apiKey, body, sig) {
  const expected = crypto
    .createHmac('sha256', apiKey)
    .update(body) // Buffer
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig)
  );
}

<?php
function verify($apiKey, $body, $sig) {
  $expected = hash_hmac(
    'sha256',
    $body,
    $apiKey
  );
  return hash_equals(
    $expected, $sig
  );
}
?>

Event Payloads

{
  "event":   "topup_completed",
  "method":  "bep20",      // bep20 | ton | trx | binance
  "txid":    "0x1a2b...", // tx hash; null for binance (order_id used)
  "amount":  25.50,        // credited USDT
  "bonus":   0.50,         // promo bonus if any, else 0
  "user_id": 12345678
}

{
  "event":       "balance_updated",
  "user_id":     12345678,
  "new_balance": 167.50,  // live wallet balance after change
  "delta":       25.50,   // +credited / -deducted
  "reason":      "topup_bep20"  // topup_bep20 | topup_ton | topup_trx | topup_binance | order_purchase
}

{
  "event":        "order_placed",
  "order_id":     "ORDx8kLm2Qp",
  "product_id":   "PRD_ajS8x",
  "product_name": "Netflix Premium",
  "qty":          2,
  "total_paid":   7.00,
  "stock_type":   "auto",    // auto | manual
  "items":        ["email:pass", "email2:pass2"],  // [] for manual stock
  "source":       "api",     // api | bot
  "user_id":      12345678
}

Delivery & Retry