Birgen Store / Seller API v2

Seller API: guide and reference

The Birgen Seller API lets your server list products, quote a purchase, place an order, and retrieve its delivery.

The purchase flow

The Birgen Seller API lets your server list products, quote a purchase, place an order, and retrieve its delivery.

01 / 05

Get access

Create a key under Profile → My API in the Birgen Store bot. Store the key and secret in your backend configuration.

02 / 05

Read the catalog

Call GET /products?currency=USDT. Use a product’s id and check available, price, and stock.

03 / 05

Quote before buying

Call GET /quote?product_id=123&quantity=2&currency=USDT. This does not debit your balance. Use the returned quote_token while the price is current.

04 / 05

Place one order

Send POST /orders with external_order_id, product ID, quantity, currency, quote token, and an Idempotency-Key. A successful POST creates a real purchase.

05 / 05

Get the result

Poll GET /orders/{id}. After a timeout, look up the existing order by external_order_id before retrying the same POST.

Sign every private request

Every method except GET /health requires these headers. Sign the exact HTTP method, path including query string, and raw request body bytes. Keep monetary values as strings in JSON.

  • X-Api-Key — key for the Birgen Store account.
  • X-Timestamp — Unix time in seconds; allowed clock skew is five minutes.
  • X-Nonce — fresh 16–128 character value using A–Z a–z 0–9 _ -; do not reuse within ten minutes.
  • X-Signature — lowercase hexadecimal HMAC-SHA256 signature.
HMAC-SHA256
HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body)
Generate a new nonce for every attempt. For an idempotent order retry, keep the original request body and Idempotency-Key.

Python: signed catalog request

This example reads credentials from environment variables and makes no purchase.

Python 3
import hashlib, hmac, json, os, secrets, time
from urllib.request import Request, urlopen

path = "/api/v1/products?currency=USDT"
timestamp = str(int(time.time()))
nonce = secrets.token_urlsafe(24)
body = b""
payload = b".".join((timestamp.encode(), nonce.encode(), b"GET", path.encode(), body))
signature = hmac.new(os.environ["BIRGEN_API_SECRET"].encode(), payload, hashlib.sha256).hexdigest()
request = Request("https://grinberg.cc" + path, headers={
    "X-Api-Key": os.environ["BIRGEN_API_KEY"],
    "X-Timestamp": timestamp, "X-Nonce": nonce, "X-Signature": signature,
})
with urlopen(request, timeout=15) as response:
    products = json.load(response)["products"]

Methods

Base URL: https://grinberg.cc/api/v1

GET

/api/v1/health

Public health response {"ok":true,"service":"seller_api"}.

GET

/api/v1/products?currency=USDT

Product array and rub_per_usdt. Each product includes ID, title, price, availability, and max quantity; stock appears when known.

GET

/api/v1/balances

Balances for the key owner, e.g. {"balances":{"USDT":"12.50"}}.

GET

/api/v1/quote?product_id=123&quantity=2&currency=USDT

Quote with unit price, total, availability, max quantity, optional stock, and quote_token. No debit.

POST

/api/v1/orders

Creates a purchase. Requires Idempotency-Key and JSON fields external_order_id, product_id, quantity, currency, quote_token.

GET

/api/v1/orders/{order_id}

Returns the owning account’s order, status, amount, product, timestamps, and delivery text when delivered.

GET

/api/v1/orders/by-external?external_order_id=…

Finds the owning account’s order after a network timeout or key rotation.

Orders and delivery

Use a unique external_order_id per purchase and a 16–128 character Idempotency-Key. A replay with the same key and identical body returns the same order without a second debit. Changing the body under the same key, or assigning an existing external ID to another purchase, causes a conflict.

POST /api/v1/orders · JSON
{
  "external_order_id": "my-order-10069",
  "product_id": 123,
  "quantity": 2,
  "currency": "USDT",
  "quote_token": "<token from GET /quote>"
}
PROCESSINGWait and poll; do not create another order.
DELIVEREDRead delivery_text; it remains available on later reads.
REFUNDEDThe supplier purchase was refunded to the store balance.
SUPPORT_REQUIREDContact support with the order number.
The delivery format is product-dependent. Do not assume that a blank line always separates units.

Errors and safe retries

  • 400 — invalid request, JSON, quote, currency, or missing idempotency key.
  • 401 — missing or invalid authentication headers, expired timestamp, or bad signature.
  • 404 — product or order not found.
  • 409 — price change, order rejection, duplicate nonce, or idempotency/external ID conflict.
  • 413 — request body too large. 429 — rate limit.
  • 500 or timeout — recover by external order ID before any POST retry.

For the exact current schema and field descriptions, open the live OpenAPI reference.