Black Shop API

One REST API for Hosting, Telegram Stars & Premium, Game top-ups & gift cards, NFT market — same balance and same prices as your Black Shop account.

Base URL

https://api.blaack.shop

Health check (no key): GET /health

Getting started

1. Sign in at blaack.shop → Account → Developer API keys → New key.
2. Give it a name, choose its sections and (optionally) spending limits and allowed IPs. You can have several keys, e.g. one per bot or website, each with its own settings.
3. Top up your balance on the website. Every paid call is charged from that balance.

Authentication

Send your key in the X-API-Key header (recommended), or Authorization: Bearer <key>, or the key query parameter. Keep it secret: anyone with the key can spend your balance.

curl https://api.blaack.shop/balance -H "X-API-Key: bsk_your_key"

Balance

GET/balance — /v3/balance · /v4/balance · /v5/balance · /v6/balance

Returns your account balance in USD (balance) plus the same amount in the display currency you chose on the website (balance_display). It is the same balance used by the website and every API version.

curl https://api.blaack.shop/balance -H "X-API-Key: bsk_your_key"

{"ok": true, "data": {"balance": 12.5, "currency": "USD", "display_currency": "EGP", "balance_display": "620 EGP"}}

Responses

Every response is JSON. Success: {"ok": true, "data": …}. Failure: {"ok": false, "error": {"code", "message", "details?"}} with a matching HTTP status. Money values are in USD. POST bodies may be JSON or form-encoded. Messages follow ?lang= or Accept-Language (default English).

{"ok": true, "data": {"balance": 12.5, "currency": "USD"}}

{"ok": false, "error": {"code": "missing_params", "message": "Missing parameter(s): country", "details": {"params": ["country"]}}}

Billing rules: Purchases are charged the moment the request is accepted, and delivered items are final (no cancel). Orders that fail at the provider are refunded automatically to the same balance.

Errors

HTTP	code
`400`	`bad_request / missing_params`	Invalid or missing parameters, not enough balance, or the request was refused (see message)
`401`	`invalid_key`	Missing or wrong API key
`403`	`key_disabled / key_blocked / key_expired`	Key turned off by you, suspended by the admin, or expired
`403`	`scope_denied / read_only_key`	Section not allowed for this key, or purchase with a read-only key
`403`	`ip_not_allowed`	Request from an IP that is not on the key allow-list
`403`	`spend_limit`	The order would exceed a spending limit of this key — nothing was charged
`403`	`disabled`	This section is turned off right now
`404`	`not_found`	Unknown endpoint or object
`429`	`rate_limited`	Too many requests
`500`	`internal_error`	Unexpected error — safe to retry GETs
`502`	`upstream_error`	Provider temporarily unavailable
`503`	`api_disabled / version_disabled`	API or version paused by the admin

Rate limits

120 requests per minute per key (HTTP 429 when exceeded). Some purchase endpoints have their own tighter limits, same as the website.

Key permissions & limits

Sections — a key only reaches the versions you allow (v1…v6); other versions return 403 scope_denied. /balance works for every key.
Read-only — GET requests only; purchases return 403 read_only_key.
Spending limits (USD) — per order, per day (UTC) and lifetime total. The limit is enforced at the moment of charging, so an order that would exceed it is rejected with 403 spend_limit before anything is charged; details.limit tells which one (per_order, daily, total).
Allowed IPs — up to 20 addresses or CIDR networks; other sources get 403 ip_not_allowed.
Expiry — after the expiry date the key returns 403 key_expired.
Every key has its own request log (last 30 days) on the website. Rolling a key changes its secret and keeps its settings.

{"ok": false, "error": {"code": "spend_limit", "message": "Spending limit reached for this key", "details": {"limit": "daily", "remaining": 1.25}}}

v3 — Hosting https://api.blaack.shop/v3

GET/v3/balance

Your balance

curl "https://api.blaack.shop/v3/balance" \
  -H "X-API-Key: bsk_your_key"

GET/v3/categories

Hosting categories

curl "https://api.blaack.shop/v3/categories" \
  -H "X-API-Key: bsk_your_key"

GET/v3/plans

Plans (optionally by category)

Parameters
`category`	optional	Category id/slug

curl "https://api.blaack.shop/v3/plans" \
  -H "X-API-Key: bsk_your_key"

POST/v3/orders

Order a hosting plan

Parameters
`plan_id`	required	Plan id from /v3/plans
`password`	optional	Control panel password (8+ chars, letters and digits)

curl -X POST "https://api.blaack.shop/v3/orders" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": 12, "password": "StrongPass123"}'

GET/v3/orders

Hosting order history

curl "https://api.blaack.shop/v3/orders" \
  -H "X-API-Key: bsk_your_key"

GET/v3/services

Your active hosting services

curl "https://api.blaack.shop/v3/services" \
  -H "X-API-Key: bsk_your_key"

GET/v3/services/{id}

Service details

Parameters
`id`	required	Id from the list endpoint

curl "https://api.blaack.shop/v3/services/123" \
  -H "X-API-Key: bsk_your_key"

GET/v3/services/{id}/renew

Renewal price/info

Parameters
`id`	required	Id from the list endpoint

curl "https://api.blaack.shop/v3/services/123/renew" \
  -H "X-API-Key: bsk_your_key"

POST/v3/services/{id}/renew

Renew a service

Parameters
`id`	required	Id from the list endpoint

curl -X POST "https://api.blaack.shop/v3/services/123/renew" \
  -H "X-API-Key: bsk_your_key"

POST/v3/services/{id}/password

Change the control panel password

Parameters
`id`	required	Id from the list endpoint
`password`	required	Control panel password (8+ chars, letters and digits)

curl -X POST "https://api.blaack.shop/v3/services/123/password" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"password": "NewPass12345"}'

POST/v3/services/{id}/auto-renew

Turn auto-renew on/off

Parameters
`id`	required	Id from the list endpoint
`enabled`	required	true \| false

curl -X POST "https://api.blaack.shop/v3/services/123/auto-renew" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

v4 — Telegram Stars & Premium https://api.blaack.shop/v4

GET/v4/balance

Your balance

curl "https://api.blaack.shop/v4/balance" \
  -H "X-API-Key: bsk_your_key"

GET/v4/info

Section info and limits

Parameters
`username`	optional	Telegram username (without @)

curl "https://api.blaack.shop/v4/info" \
  -H "X-API-Key: bsk_your_key"

GET/v4/quote

Price quote. type = stars | premium (quantity = stars count or premium months)

Parameters
`type`	required	stars \| premium
`quantity`	required	Quantity

curl "https://api.blaack.shop/v4/quote?type=stars&quantity=1" \
  -H "X-API-Key: bsk_your_key"

GET/v4/check

Check that a username can receive

Parameters
`type`	required	stars \| premium
`username`	required	Telegram username (without @)
`months`	optional	Premium months: 3 \| 6 \| 12

curl "https://api.blaack.shop/v4/check?type=stars&username=value" \
  -H "X-API-Key: bsk_your_key"

POST/v4/orders

Send Stars or Premium to a username

Parameters
`type`	required	stars \| premium
`username`	required	Telegram username (without @)
`quantity`	required	Quantity
`max_price`	optional	Optional. Highest total price (USD) you accept — the order is rejected if the price went up

curl -X POST "https://api.blaack.shop/v4/orders" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "stars", "username": "durov", "quantity": 100}'

GET/v4/orders

Your Stars/Premium orders

curl "https://api.blaack.shop/v4/orders" \
  -H "X-API-Key: bsk_your_key"

GET/v4/orders/{id}

Order status

Parameters
`id`	required	Id from the list endpoint

curl "https://api.blaack.shop/v4/orders/123" \
  -H "X-API-Key: bsk_your_key"

v5 — Game top-ups & gift cards https://api.blaack.shop/v5

GET/v5/balance

Your balance

curl "https://api.blaack.shop/v5/balance" \
  -H "X-API-Key: bsk_your_key"

GET/v5/games

Games (top-up)

Parameters
`q`	optional	Search text
`offset`	optional	Pagination offset
`limit`	optional	Page size

curl "https://api.blaack.shop/v5/games" \
  -H "X-API-Key: bsk_your_key"

GET/v5/games/{code}

Top-up packages of a game

Parameters
`code`	required	Game code from /v5/games

curl "https://api.blaack.shop/v5/games/pubgm" \
  -H "X-API-Key: bsk_your_key"

POST/v5/games/{code}/verify

Verify a player ID

Parameters
`code`	required	Game code from /v5/games
`player_id`	required	Player ID in the game
`server_id`	optional	Server / zone id (games that need it)

curl -X POST "https://api.blaack.shop/v5/games/pubgm/verify" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"player_id": "123456789", "server_id": "1234"}'

POST/v5/topups

Top up a game account

Parameters
`game`	required	Game code from /v5/games
`package`	required	Package name from /v5/games/{code}
`player_id`	required	Player ID in the game
`server_id`	optional	Server / zone id (games that need it)
`character`	optional	Character name (games that need it)

curl -X POST "https://api.blaack.shop/v5/topups" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"game": "pubgm", "package": "60 UC", "player_id": "123456789"}'

GET/v5/categories

Gift card categories

Parameters
`q`	optional	Search text
`offset`	optional	Pagination offset
`limit`	optional	Page size

curl "https://api.blaack.shop/v5/categories" \
  -H "X-API-Key: bsk_your_key"

GET/v5/products

Gift cards in a category

Parameters
`category`	required	Category id/slug

curl "https://api.blaack.shop/v5/products?category=value" \
  -H "X-API-Key: bsk_your_key"

POST/v5/vouchers

Buy gift card codes

Parameters
`product_id`	required	Product id from /v5/products
`quantity`	optional `1`	Quantity

curl -X POST "https://api.blaack.shop/v5/vouchers" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 77, "quantity": 1}'

GET/v5/orders

Your game/card orders

curl "https://api.blaack.shop/v5/orders" \
  -H "X-API-Key: bsk_your_key"

v6 — NFT market https://api.blaack.shop/v6

GET/v6/balance

Your balance

curl "https://api.blaack.shop/v6/balance" \
  -H "X-API-Key: bsk_your_key"

GET/v6/info

Open market sections, your linked wallets, balance and TON rate

curl "https://api.blaack.shop/v6/info" \
  -H "X-API-Key: bsk_your_key"

GET/v6/listings

Market listings (fixed price, Dutch, auctions)

Parameters
`type`	optional	all \| sale \| dutch \| auction (comma-separated allowed)
`kind`	optional	gift \| username \| number
`sort`	optional	new \| price_asc \| price_desc \| ending
`q`	optional	Search by title
`page`	optional	Page number (0, 1, 2…) — 30 items per page

curl "https://api.blaack.shop/v6/listings" \
  -H "X-API-Key: bsk_your_key"

GET/v6/listings/{address}

Listing details with live price / next bid

Parameters
`address`	required	Listing / bundle address from the list

curl "https://api.blaack.shop/v6/listings/EQ...listingAddress" \
  -H "X-API-Key: bsk_your_key"

POST/v6/listings/{address}/buy

Buy (or bid on an auction) from your balance. The NFT goes to one of your linked wallets

Parameters
`address`	required	Listing / bundle address from the list
`recipient`	required	One of your linked TON wallets (see /v6/info). Optional for gifts
`max_price_ton`	optional	Optional. Highest price in TON you accept — rejected with 409 if the price went up
`bid_ton`	optional	Auctions only: your bid in TON (at least next_bid_ton)

curl -X POST "https://api.blaack.shop/v6/listings/EQ...listingAddress/buy" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "UQ...yourWallet", "max_price_ton": 12.5}'

GET/v6/bundles

Bundles (several NFTs in one sale)

Parameters
`kind`	optional	gift \| username \| number
`sort`	optional	new \| price_asc \| price_desc
`page`	optional	Page number (0, 1, 2…) — 30 items per page

curl "https://api.blaack.shop/v6/bundles" \
  -H "X-API-Key: bsk_your_key"

GET/v6/bundles/{address}

Bundle details and items

Parameters
`address`	required	Listing / bundle address from the list

curl "https://api.blaack.shop/v6/bundles/EQ...listingAddress" \
  -H "X-API-Key: bsk_your_key"

POST/v6/bundles/{address}/buy

Buy a bundle from your balance

Parameters
`address`	required	Listing / bundle address from the list
`recipient`	required	One of your linked TON wallets (see /v6/info). Optional for gifts
`max_price_ton`	optional	Optional. Highest price in TON you accept — rejected with 409 if the price went up

curl -X POST "https://api.blaack.shop/v6/bundles/EQ...listingAddress/buy" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient": "UQ...yourWallet", "max_price_ton": 40}'

GET/v6/external

Offers from other marketplaces (sales and auctions)

Parameters
`type`	optional	all \| sale \| auction
`kind`	optional	gift \| username \| number
`sort`	optional	price_asc \| price_desc \| ending
`q`	optional	Search by title
`page`	optional	Page number (0, 1, 2…) — 30 items per page

curl "https://api.blaack.shop/v6/external" \
  -H "X-API-Key: bsk_your_key"

POST/v6/external/buy

Buy an external sale from your balance (gifts are delivered to your linked Telegram)

Parameters
`nft`	required	NFT address from /v6/external
`recipient`	optional	One of your linked TON wallets (see /v6/info). Optional for gifts
`max_price_ton`	optional	Optional. Highest price in TON you accept — rejected with 409 if the price went up

curl -X POST "https://api.blaack.shop/v6/external/buy" \
  -H "X-API-Key: bsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"nft": "EQ...nftAddress", "recipient": "UQ...yourWallet", "max_price_ton": 9}'

GET/v6/rentals

NFTs available for rent

Parameters
`kind`	optional	gift \| username \| number
`sort`	optional	new \| price_asc \| price_desc
`q`	optional	Search by title
`page`	optional	Page number (0, 1, 2…) — 30 items per page

curl "https://api.blaack.shop/v6/rentals" \
  -H "X-API-Key: bsk_your_key"

GET/v6/rentals/{address}

Rental listing details

Parameters
`address`	required	Listing / bundle address from the list

curl "https://api.blaack.shop/v6/rentals/EQ...listingAddress" \
  -H "X-API-Key: bsk_your_key"

GET/v6/rentals/{address}/quote

Rental price for a number of days

Parameters
`address`	required	Listing / bundle address from the list
`days`	optional	Rental days

curl "https://api.blaack.shop/v6/rentals/EQ...listingAddress/quote" \
  -H "X-API-Key: bsk_your_key"

GET/v6/orders

Your NFT purchase orders

curl "https://api.blaack.shop/v6/orders" \
  -H "X-API-Key: bsk_your_key"

GET/v6/orders/{id}

One order status

Parameters
`id`	required	Order id from /v6/orders

curl "https://api.blaack.shop/v6/orders/123" \
  -H "X-API-Key: bsk_your_key"