Seller API: guide and reference
The Birgen Seller API lets your server list products, quote a purchase, place an order, and retrieve its delivery.
Quick start / API
The purchase flow
The Birgen Seller API lets your server list products, quote a purchase, place an order, and retrieve its delivery.
Get access
Create a key under Profile → My API in the Birgen Store bot. Store the key and secret in your backend configuration.
Read the catalog
Call GET /products?currency=USDT. Use a product’s id and check available, price, and stock.
Quote before buying
Call GET /quote?product_id=123&quantity=2¤cy=USDT. This does not debit your balance. Use the returned quote_token while the price is current.
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.
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 usingA–Z a–z 0–9 _ -; do not reuse within ten minutes.X-Signature— lowercase hexadecimal HMAC-SHA256 signature.
HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body)Python: signed catalog request
This example reads credentials from environment variables and makes no purchase.
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
/api/v1/health
Public health response {"ok":true,"service":"seller_api"}.
/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.
/api/v1/balances
Balances for the key owner, e.g. {"balances":{"USDT":"12.50"}}.
/api/v1/quote?product_id=123&quantity=2¤cy=USDT
Quote with unit price, total, availability, max quantity, optional stock, and quote_token. No debit.
/api/v1/orders
Creates a purchase. Requires Idempotency-Key and JSON fields external_order_id, product_id, quantity, currency, quote_token.
/api/v1/orders/{order_id}
Returns the owning account’s order, status, amount, product, timestamps, and delivery text when delivered.
/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.
{
"external_order_id": "my-order-10069",
"product_id": 123,
"quantity": 2,
"currency": "USDT",
"quote_token": "<token from GET /quote>"
}delivery_text; it remains available on later reads.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.500or timeout — recover by external order ID before any POST retry.
For the exact current schema and field descriptions, open the live OpenAPI reference.