# Padington Shop API v1

> REST API for automating purchases of digital goods (Stars, Telegram Premium, ChatGPT/Claude codes, Roblox Robux) through franchise bots. Bearer token authentication, JSON requests/responses, RUB pricing.

## Base
- API base URL: `https://api.padington.com/v1`
- Docs (HTML): https://api.padington.com/docs
- Docs (Markdown for LLMs): https://api.padington.com/llms-full.txt
- OpenAPI spec: https://api.padington.com/openapi.json
- Content-Type: `application/json`, UTF-8

## Authentication
Every request requires header `Authorization: Bearer pad_live_<token>`.
Keys are generated by users inside their bot (Profile → 🔑 API keys, max 5 active per user).
Balance is charged from the user's bot balance — same as a normal in-bot purchase.

## Endpoints
- `GET /v1/balance` — current user balance in RUB
- `GET /v1/catalog` — full catalog with current RUB prices (markups applied, USD-rate-dependent)
- `POST /v1/order` — create order (atomic balance debit; body schema depends on `category`)
- `GET /v1/order/{order_code}` — order status
- `GET /v1/orders?limit=N&offset=N` — paginated order history
- `GET /v1/rent/{category}` — list available NFTs for rent (categories: `gifts`, `numbers`, `usernames`)
- `POST /v1/rent` — pay rent (body: category, nft_address, duration_days, optional expected_price_rub)
- `GET /v1/rentals?limit=N&offset=N` — your active and past rentals

## Order categories (POST /v1/order)
- `chatgpt` — `item` ∈ `plus_1m`, `plus_12m`, `pro_1m` (CDK, synchronous fulfillment)
- `claude` — `item` ∈ `pro`, `max5`, `max20` (CDK, synchronous)
- `robux` — `pack` ∈ `r80`/`r500`/etc, `roblox_username`, `roblox_password` (may require 2FA → `status=needs_verification`)
- `stars` — `quantity` (50–1,000,000), `recipient` (telegram username) — Fragment auto-delivery (~30-120 sec)
- `premium` — `duration` ∈ `3`/`6`/`12`, `recipient` — Fragment auto-delivery (~30-120 sec)

## Rent categories (POST /v1/rent)
- `gifts` — Telegram Gifts
- `numbers` — Anonymous Numbers
- `usernames` — Telegram Usernames

Body: `{category, nft_address, duration_days (1-365), expected_price_rub?}`. `expected_price_rub` is optional — if set, server returns 409 if real price drifted >5% (race protection).

## Status codes
- `200` OK
- `400` invalid params (see `detail`)
- `401` invalid/revoked key
- `402` insufficient balance
- `404` order not found / not yours
- `503` API disabled by franchise owner
- `500` internal error

## Order statuses
- `pending` — queued
- `processing` — being fulfilled
- `needs_verification` — Roblox requires 2FA, see `error.next_action`
- `completed` — done; see `external_id` or `error.codes`
- `failed` — error; balance auto-refunded

## Pricing
Catalog prices float with USD rate. Price is locked at order creation (`POST /v1/order`). Fetch fresh `/catalog` before each batch of orders.

## Limits
- Max 5 active API keys per user
- Atomic debit: balance subtracts only on HTTP 200; refunded on failed fulfillment
- Concurrent requests from the same user_id are serialized (no double-spend possible)
- Polling interval recommendation: 2–3 seconds for `GET /v1/order/{code}`

## Quick example (curl)
```
curl -H "Authorization: Bearer pad_live_..." https://api.padington.com/v1/balance
curl -X POST https://api.padington.com/v1/order \
  -H "Authorization: Bearer pad_live_..." \
  -H "Content-Type: application/json" \
  -d '{"category":"chatgpt","item":"plus_1m"}'
```

## Support
Create a ticket via the "Support" section inside your bot.