Seller API guide and reference

Русский · English · OpenAPI JSON

Seller API is for a server-side plugin or backend only. Never put the API secret in a FunPay listing, browser, client mod, or public repository. Create the key in “My API” and save both values; they are shown once. When rotated, the old key stops only after confirmation. The new key still belongs to the same Telegram account, so it sees that account’s balance and previous API orders.

Base URL: https://grinberg.cc/api/v1. Send and read every monetary JSON value as a string, for example "3.09"; never use floats. The store calculates the RUB amount using its own rate.

Sign every authenticated request

Send X-Api-Key, X-Timestamp (Unix seconds), X-Nonce (unique 16–128 A-Za-z0-9_- characters), and X-Signature. The signature is lowercase hex HMAC-SHA256(secret, timestamp + "." + nonce + "." + METHOD + "." + path_with_query + "." + raw_body). Clock skew is five minutes; a nonce cannot be reused for ten minutes. GET uses an empty raw body. Generate a new nonce for every attempt, including an idempotent retry.

Normal purchase flow

1. Call GET /products?currency=USDT and select an id. A product with available: false cannot be purchased.
2. Call GET /quote?product_id=123&quantity=3&currency=USDT. It does not debit anything and returns unit_price, total, available, max_quantity, and quote_token; stock is included when the quantity is known.
3. When available, immediately POST the returned quote_token, a new external_order_id, and a new Idempotency-Key.
4. Poll GET /orders/{id} or GET /orders/by-external?external_order_id=.... After a timeout, look up the order first; do not start another purchase.

If the price rises after quote, the API returns 409 price_changed; no order and no debit are created. A lower price is accepted and the lower amount is charged. Stock and balance reservation are atomic.

Statuses

PROCESSING: keep polling and do not create a duplicate order. DELIVERED: delivery_text contains the purchased product data and is returned on subsequent requests. REFUNDED: funds were returned to the balance. SUPPORT_REQUIRED: contact support with the order number. Retrieve order status and delivery through the API.

Python signature and catalogue example

Use your credentials only on your server. The query order and encoding in the signature must match the request exactly. Sign an order the same way using the exact JSON bytes and the Idempotency-Key header.

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

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

For integration with Codex / Claude / another AI, provide this guide without real credentials. Only make a real test purchase with your permission.

GET /health is public and returns {"ok":true,"service":"seller_api"}. Every other method requires the guide’s signature.

GET /products?currency=USDT|RUB returns products[] and rub_per_usdt. The store calculates RUB values and the rate; do not use a fixed external rate in an integration. A product has id, names/title, brand/type/denomination/category/region, delivery_type, price, prices, available, and max_quantity. stock is included when the quantity is known; stock: 0 means zero stock. If available: false, the product cannot be purchased.

GET /balances returns {"balances":{"USDT":"12.50","RUB":"0.00"}} for the key owner.

GET /quote?product_id=123&quantity=2&currency=USDT returns quote, for example {"ok":true,"quote":{"product_id":123,"quantity":2,"currency":"USDT","unit_price":"3.09","total":"6.18","available":true,"max_quantity":5,"stock":7,"quote_token":"..."}}. When unavailable, price, total and token are null; this is not an authorization to POST.

POST /orders requires Idempotency-Key. Body example: {"external_order_id":"funpay-10069","product_id":123,"quantity":2,"currency":"USDT","quote_token":"..."}. A new order returns 201 and idempotent_replay:false; a correct retry returns 200 and idempotent_replay:true.

GET /orders/{order_id} and GET /orders/by-external?external_order_id=funpay-10069 return only the owning account’s orders, including orders made under a replaced key. Fields are id, external_order_id, status, string amount, currency, product:{title,quantity}, and timestamps; delivery_text appears only in DELIVERED. Statuses are PROCESSING, DELIVERED, REFUNDED, and SUPPORT_REQUIRED.

When individual units are available separately, they are separated by a blank line; one unit may itself contain multiple lines. When delivery is a single text, its formatting is preserved, so splitting automatically on blank lines is not guaranteed.

Example order response (illustrative data):

{
  "ok": true,
  "order": {
    "id": 10069,
    "external_order_id": "funpay-10069",
    "status": "DELIVERED",
    "amount": "6.18",
    "currency": "USDT",
    "product": {"title": "Example — Standard", "quantity": 2},
    "created_at": "2026-01-01T12:00:00+00:00",
    "delivered_at": "2026-01-01T12:01:00+00:00",
    "delivery_text": "Example delivery data"
  }
}

All errors use {"ok":false,"error":{"code":"...","message":"..."}}. Important codes: 400 invalid_request, invalid_json, invalid_quote, invalid_currency, idempotency_required; 401 auth failures; 404 not found; 409 price_changed, order_rejected, idempotency/external conflicts, nonce_reused, order_processing; 413 payload too large; 429 rate limited; 500 internal error. Errors are neutral and never disclose internal processing. On a timeout or 500, recover using external ID before any retry.