⚡ Enterprise Reseller Infrastructure • v1.2.0

High-Speed Reseller API
Built for Next-Gen Telegram Bots

Power your reseller panels and Telegram shops with sub-second digital fulfillment, atomic single-commit transactions, real-time HMAC webhooks, and locked 1$ = 100₹ predictability.

Launch Interactive Console

BASE URL: https://reseller.aivaulthub.store/api/v1

⚡

<50ms Response

Edge-optimized JSON routing with automated background voucher delivery.

🛡️

Atomic Settlement

Single-commit wallet deduction & order insert. Zero funds lost on failure.

🔄

Zero-Debit Idempotency

Pass external_order_id to safely retry failed network connections.

💵

Fixed 1$ = 100₹

Completely immune to crypto volatility. Predictable margins across every order.

HTTP HEADERS

Authentication

Every request requires your confidential API secret passed in the X-API-Key header. Treat your API key as a password.

Header	Type	Description
X-API-Key Required	string	Your secret reseller API key (e.g. `sk_live_...`).

Header Example

curl -H "X-API-Key: sk_live_your_secret_key" \
  https://reseller.aivaulthub.store/api/v1/me

QUOTA HEADERS

Rate Limits & Live Quota

Requests are limited to 60 requests per minute per API key. Live budget headers are returned on every HTTP response.

Header	Description
X-RateLimit-Limit	Allowed requests per 60-second window (`60`).
X-RateLimit-Remaining	Remaining requests available in current window.
X-RateLimit-Reset	Unix epoch timestamp when your quota refills.

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1788944424

GUARANTEES

Atomic Settlement & Zero-Debit Idempotency

Automated reseller integrations require absolute financial reliability. Our platform is built on two core guarantees:

🛡️

1. Single-Commit Atomic Settlement

Wallet deductions and order creation execute inside a single atomic SQLite transaction (BEGIN IMMEDIATE ... COMMIT). If fulfillment fails, funds automatically roll back. You are never debited without an order.

🔄

2. Idempotent Replays (external_order_id)

Pass your internal order reference in external_order_id when placing orders. If a network connection drops and your bot retries, the API returns the original order with "idempotent_replay": true — zero duplicate debits or duplicate orders.

SIMULATOR

Interactive Volume Price & Bulk Slab Calculator

Visualize exact volume pricing, tier boundaries, bulk percentage discounts, and fixed USD/INR totals in real time before placing orders:

Select Service

Quantity: 500 units

Base Unit Price:$0.45 USD

Base Total:$225.00 USD

Bulk Discount:5% (-$11.25)

Final Order Cost:$213.75 USD

Fixed INR Conversion (1$=100₹):₹21,375.00 INR

GET /api/v1/products

List Available Products

Returns real-time digital catalog services, live available stock, quantity pricing slabs, and bulk discount rules.

curl -X GET "https://reseller.aivaulthub.store/api/v1/products" \
  -H "X-API-Key: YOUR_API_KEY"

import requests
headers = {"X-API-Key": "YOUR_API_KEY"}
res = requests.get("https://reseller.aivaulthub.store/api/v1/products", headers=headers)
print(res.json())

const res = await fetch("https://reseller.aivaulthub.store/api/v1/products", {
  headers: { "X-API-Key": "YOUR_API_KEY" }
});
console.log(await res.json());

Response (200 OK)

{
  "currency": "USD",
  "rate": "1 USD = 100 INR (fixed)",
  "products": [
    {
      "service_id": "service_1",
      "name": "Gemini Pro 1 Month",
      "stock": 482,
      "custom_pricing": true,
      "custom_pricing_note": "Active. Applied because stock (482) is above the 150 buffer stock reserve.",
      "pricing_tiers": [
        { "min": 1, "max": 99, "price": 0.50 },
        { "min": 100, "max": 1000, "price": 0.45 }
      ],
      "bulk_discounts": [
        { "min_qty": 500, "discount_pct": 5 }
      ]
    }
  ]
}

GET /api/v1/me

Account Profile & Balance

Returns your verified Telegram owner chat ID and active wallet balance in USD.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://reseller.aivaulthub.store/api/v1/me

import requests
r = requests.get("https://reseller.aivaulthub.store/api/v1/me", headers={"X-API-Key": "YOUR_API_KEY"})
print(r.json())

Response (200 OK)

{
  "chat_id": 123456789,
  "balance": 145.50,
  "currency": "USD"
}

GET /api/v1/quote

Price Quote Preview

Validates exact order financial calculations before submission. Computes active tier, bulk discount savings, and wallet balance sufficiency without committing an order.

Query Param	Type	Description
service_id Required	string	Product identifier.
quantity Required	integer	Desired order units.

cURL Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://reseller.aivaulthub.store/api/v1/quote?service_id=service_1&quantity=500"

Response (200 OK)

{
  "service_id": "service_1",
  "service_name": "Gemini Pro 1 Month",
  "quantity": 500,
  "stock": 482,
  "stock_warning": null,
  "custom_pricing": true,
  "custom_pricing_note": "Active. Applied because stock remaining after order (332) is above the 150 buffer reserve.",
  "currency": "USD",
  "pricing": {
    "unit_price": 0.45,
    "slab_range": "100-1000",
    "base_total": 225.00,
    "bulk_discount_pct": 5,
    "bulk_discount_amount": 11.25,
    "final_total": 213.75,
    "price_source": "normal+bulk_discount"
  },
  "your_balance": 350.00,
  "sufficient_balance": true
}

POST /api/v1/order

Place Automated Order

Executes an atomic balance deduction and immediate digital product delivery. Always pass external_order_id for safe zero-duplicate retries.

Body Field	Type	Description
service_id Required	string	Target product ID.
quantity Required	integer	Number of units to purchase.
external_order_id Optional	string	Your internal idempotency key to prevent double debiting.
accept_normal_price Optional	boolean	Set true to override low-stock custom pricing protection.

POST Request Payload

curl -X POST "https://reseller.aivaulthub.store/api/v1/order" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "service_1",
    "quantity": 2,
    "external_order_id": "bot_order_99812"
  }'

Response (201 Created)

{
  "success": true,
  "order_id": "API89XKZ42",
  "external_order_id": "bot_order_99812",
  "service_id": "service_1",
  "quantity": 2,
  "total_cost": 1.00,
  "new_balance": 144.50,
  "currency": "USD",
  "price_breakdown": {
    "unit_price": 0.50,
    "base_total": 1.00,
    "bulk_discount_pct": 0,
    "bulk_discount_amount": 0.00,
    "final_total": 1.00,
    "price_source": "normal"
  },
  "products": [
    "KEY-GEMINI-A1904-8842",
    "KEY-GEMINI-B8912-7719"
  ]
}

GET /api/v1/stats

Reseller Account Analytics

Real-time financial analytics: order counts, total USD spend (today, 7d, 30d, all-time), and per-product order breakdowns. Filter by start and end timestamps.

Response (200 OK)

{
  "orders": { "today": 4, "7d": 28, "30d": 142, "all_time": 680 },
  "spending": { "today": 2.80, "7d": 18.20, "30d": 84.50, "all_time": 395.00 },
  "products_breakdown": [
    { "service_id": "service_1", "name": "Gemini Pro 1 Month", "orders": 120, "quantity_ordered": 540, "total_spent": 243.00 }
  ],
  "currency": "USD"
}

GET /api/v1/order/{order_id}

Single Order Status & Product Codes

Fetches delivery status, timestamps, and delivered digital codes/coupons for any previous order using its unique order_id.

Path Parameter	Type	Description
order_id Required	string	The unique order ID returned upon purchase (e.g. `API89XKZ42`).

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://reseller.aivaulthub.store/api/v1/order/API89XKZ42

Response (200 OK)

{
  "order_id": "API89XKZ42",
  "status": "delivered",
  "service_id": "service_1",
  "quantity": 2,
  "total_cost": 1.00,
  "currency": "USD",
  "created_at": "2026-09-09T14:00:00",
  "products": [
    "KEY-GEMINI-A1904-8842",
    "KEY-GEMINI-B8912-7719"
  ]
}

GET /api/v1/orders

Paginated Order History

Returns your historical purchases in reverse chronological order. Supports page-based navigation.

Query Param	Type	Default	Description
page Optional	integer	`1`	Page number.
limit Optional	integer	`20`	Max orders per page (up to 50).

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://reseller.aivaulthub.store/api/v1/orders?page=1&limit=20"

Response (200 OK)

{
  "page": 1,
  "limit": 20,
  "currency": "USD",
  "orders": [
    {
      "order_id": "API89XKZ42",
      "service_id": "service_1",
      "quantity": 2,
      "total_cost": 1.00,
      "status": "delivered",
      "created_at": "2026-09-09T14:00:00"
    }
  ]
}

GET /api/v1/orders/export

Bulk Order History Export (CSV / JSON)

Download your complete transaction ledger for accounting, revenue reconciliation, and audits. Pass format=csv for an instant spreadsheet file.

Query Param	Type	Description
format Optional	string	`csv` or `json` (default: json).
start Optional	string	ISO 8601 start timestamp.
end Optional	string	ISO 8601 end timestamp.

Download CSV

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://reseller.aivaulthub.store/api/v1/orders/export?format=csv" \
  -o orders_export.csv

POST /api/v1/keys/rotate

Self-Service API Key Rotation

Instantly revokes your existing API key and issues a brand-new secret key. The previous key ceases functioning immediately.

Request

curl -X POST "https://reseller.aivaulthub.store/api/v1/keys/rotate" \
  -H "X-API-Key: YOUR_OLD_API_KEY"

Response (200 OK)

{
  "success": true,
  "new_api_key": "sk_live_9f83a04b12c8e9f...",
  "message": "Your old key has been revoked. Store this new key securely."
}

REAL-TIME WEBHOOKS

Webhooks Architecture & Cryptographic Verification

Webhooks eliminate the need for your bot to constantly poll the server asking "Is the order ready yet?". Whenever an order is delivered or queued, our engine immediately pushes a signed HTTPS POST notification directly to your server.

🔔

order.delivered

Fired when digital keys / coupons are assigned and ready for your customer.

⏳

order.queued

Fired when stock is pending restock. Your order will fulfill automatically once restocked.

⚠️

order.failed

Fired if delivery encounters an unrecoverable exception or error.

HMAC-SHA256 Signature Verification

Every webhook delivery includes header X-Webhook-Signature: sha256=<hex>. Use your webhook secret to cryptographically verify authenticity:

Python Signature Verifier

import hmac, hashlib

def verify_webhook(raw_payload_bytes, signature_header, webhook_secret):
    expected = "sha256=" + hmac.new(webhook_secret.encode(), raw_payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

POST /api/v1/webhooks

Register Webhook Endpoint

Registers an HTTPS endpoint on your server to receive real-time order events. Returns a secret token to verify HMAC signatures.

Field	Type	Description
url Required	string	Your HTTPS listener URL (e.g. `https://mybot.com/webhook`).
events Required	array	Events to subscribe: `["order.delivered", "order.queued"]`.

curl -X POST "https://reseller.aivaulthub.store/api/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mybot.com/webhooks/orders",
    "events": ["order.delivered", "order.queued"]
  }'

Response (201 Created)

{
  "id": 1,
  "url": "https://mybot.com/webhooks/orders",
  "events": ["order.delivered", "order.queued"],
  "secret": "9a38f7b2c01824d67e89ab32c10f8231e57c6...",
  "active": true,
  "note": "Store this secret securely — use it to verify webhook signatures."
}

GET /api/v1/webhooks

List Registered Webhooks

Returns all active webhook endpoints currently receiving events for your reseller account.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  https://reseller.aivaulthub.store/api/v1/webhooks

Response (200 OK)

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://mybot.com/webhooks/orders",
      "events": ["order.delivered", "order.queued"],
      "created_at": "2026-09-09T14:00:00",
      "active": true
    }
  ]
}

DEL /api/v1/webhooks/{id}

Delete Webhook Endpoint

Deactivates and removes a webhook subscription by its ID.

Request

curl -X DELETE "https://reseller.aivaulthub.store/api/v1/webhooks/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "deleted": true,
  "id": 1
}

POST /api/v1/webhooks/test

Test Webhook Delivery Ping

Dispatches an instant signed test event to all your registered webhooks and returns the HTTP status code received from your server, verifying connectivity.

Send Test Ping

curl -X POST "https://reseller.aivaulthub.store/api/v1/webhooks/test" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.delivered"}'

Response (200 OK)

{
  "test_results": [
    {
      "webhook_id": 1,
      "url": "https://mybot.com/webhooks/orders",
      "status": 200,
      "success": true
    }
  ]
}

Interactive Developer Console

Execute real and simulated requests directly inside your browser. Test orders with a live sandbox wallet or connect your live API key.

API Console Terminal

Select Action / Endpoint

Response Output 200 Ready

0ms

{
  "status": "Ready",
  "message": "Click Execute Request to test this endpoint."
}

STATUS CODES

Error Reference Catalog

Comprehensive list of HTTP status codes, structured error keys, and remediation instructions:

Code	Error Key	Cause & Remediation
`400`	invalid_json	Malformed request body. Ensure valid JSON payload.
`400`	missing_parameter	Missing mandatory fields such as `service_id` or `quantity`.
`401`	missing_api_key	The `X-API-Key` header was omitted from request.
`401`	invalid_api_key	The API key was revoked, expired, or does not exist.
`402`	Insufficient balance	Your wallet balance is below the order total. Top up funds to proceed.
`404`	unknown_service	Requested `service_id` was not found in catalog.
`409`	Buffer Stock Conflict	Quantity crosses low-stock buffer. Resend with `"accept_normal_price": true`.
`429`	rate_limited	60 requests/min threshold exceeded. Back off until `X-RateLimit-Reset`.
`500`	internal_error	Atomic rollback executed safely. Zero balance was lost. Retry request.

RELEASES

API Changelog & Updates

Version History

v1.2.0 — Production Release (September 2026)
- Added Webhooks Engine (register, list, delete, test ping with HMAC-SHA256).
- Added GET /api/v1/stats analytics endpoint.
- Added GET /api/v1/orders/export for CSV and JSON order downloads.
- Added POST /api/v1/keys/rotate for instant key revocation and replacement.
- Added real-time X-RateLimit-* response headers.

v1.1.0 — Parity & Safety Update
- Locked exchange rate at 1 USD = 100 INR.
- Added automatic bulk discount calculations matching Telegram bot logic.
- Added GET /api/v1/quote pre-order price preview.
- Added external_order_id idempotency guarantee.
- Added single-commit atomic wallet deduction & order creation.

High-Speed Reseller API Built for Next-Gen Telegram Bots

Authentication

Rate Limits & Live Quota

Atomic Settlement & Zero-Debit Idempotency

Interactive Volume Price & Bulk Slab Calculator

List Available Products

Account Profile & Balance

Price Quote Preview

Place Automated Order

Reseller Account Analytics

Single Order Status & Product Codes

Paginated Order History

Bulk Order History Export (CSV / JSON)

Self-Service API Key Rotation

Webhooks Architecture & Cryptographic Verification

HMAC-SHA256 Signature Verification

Register Webhook Endpoint

List Registered Webhooks

Delete Webhook Endpoint

Test Webhook Delivery Ping

Interactive Developer Console

Error Reference Catalog

API Changelog & Updates

High-Speed Reseller API
Built for Next-Gen Telegram Bots