# Padington Shop API v1 — Full Documentation

REST API for automating purchases of digital goods through franchise bots.
Bearer token auth, JSON I/O, RUB pricing.

- **Base URL**: `https://api.padington.com/v1`
- **Docs (HTML)**: https://api.padington.com/docs
- **OpenAPI**: https://api.padington.com/openapi.json

---

## Getting Started

1. Open your bot → `👤 Profile` → `🔑 API keys`
2. Click `➕ Generate key`
3. Copy the key (format `pad_live_…`) — shown **only once**
4. Use in header: `Authorization: Bearer pad_live_…`

Max 5 active keys per user. Revoke old ones to free a slot.

---

## Authentication

Every request requires:

```
Authorization: Bearer pad_live_AbCd...XyZ
```

The key is bound to your profile in the bot. All charges debit your bot balance — same as a regular in-bot purchase.

### HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200  | OK |
| 400  | Invalid parameters — see `detail` field |
| 401  | Missing/invalid/revoked API key |
| 402  | Insufficient balance |
| 404  | Order not found or not owned by your key |
| 503  | API disabled by franchise owner |
| 500  | Internal error |

---

## Endpoints

### GET /v1/balance

Returns current balance in RUB.

```json
{
  "balance_rub": 5432.10
}
```

### GET /v1/catalog

Returns the full catalog with current prices in RUB.

```json
{
  "stars": {
    "min_quantity": 50,
    "max_quantity": 1000000,
    "price_per_star_rub": 1.27
  },
  "premium": [
    {"duration_months": 3, "price_rub": 1500.00},
    {"duration_months": 6, "price_rub": 2200.00},
    {"duration_months": 12, "price_rub": 3499.00}
  ],
  "chatgpt": [
    {"id": "plus_1m",  "name": "Chat GPT Plus 1 month",  "price_rub": 1499},
    {"id": "plus_12m", "name": "Chat GPT Plus 12 months", "price_rub": 14999},
    {"id": "pro_1m",   "name": "Chat GPT Pro 1 month",   "price_rub": 8999}
  ],
  "claude": [
    {"id": "pro",   "name": "Claude Pro",    "price_rub": 1299},
    {"id": "max5",  "name": "Claude Max 5",  "price_rub": 4999},
    {"id": "max20", "name": "Claude Max 20", "price_rub": 9999}
  ],
  "robux": [
    {"pack": "r80", "robux": 80, "name": "80 R$",   "price_rub": 88.00},
    {"pack": "r500","robux": 500,"name": "500 R$",  "price_rub": 410.00}
  ]
}
```

### POST /v1/order

Creates an order. Body shape depends on `category`. Balance is **atomically** debited at creation. If balance is insufficient → 402, no order created. If fulfillment fails later → balance auto-refunded.

#### ChatGPT / Claude (CDK) — synchronous

```json
{
  "category": "chatgpt",
  "item": "plus_1m"
}
```

Auto-fulfillment in ~5 seconds. Codes returned in the `error` field as JSON (legacy field name).

#### Robux

```json
{
  "category": "robux",
  "pack": "r500",
  "roblox_username": "PlayerNickname",
  "roblox_password": "your_password"
}
```

If Roblox demands 2FA / captcha, status becomes `needs_verification`. The `error` field holds JSON with `next_action` describing what's needed. Verification endpoint `POST /v1/order/{code}/verify` is in development.

#### Stars (Fragment, auto-delivery ~30-120 sec)

```json
{
  "category": "stars",
  "quantity": 100,
  "recipient": "telegram_username"
}
```

`quantity`: 50–1,000,000. `recipient`: Telegram username (no `@`). Auto-purchased via Fragment over TON.

#### Premium (Fragment, auto-delivery ~30-120 sec)

```json
{
  "category": "premium",
  "duration": 3,
  "recipient": "telegram_username"
}
```

`duration`: 3, 6 or 12 months. `recipient`: Telegram username (no `@`).

#### Response

```json
{
  "order_code": "API-1718183020-A3F5C9",
  "status": "pending",
  "amount_rub": 1499.00,
  "detail": {
    "category": "chatgpt",
    "item": "plus_1m",
    "name": "Chat GPT Plus 1 month"
  },
  "poll_url": "/v1/order/API-1718183020-A3F5C9"
}
```

### GET /v1/order/{order_code}

Polling endpoint for status check. CDK orders typically complete in 2-10 seconds.

| status | Description |
|--------|-------------|
| `pending` | Queued for processing |
| `processing` | Fulfillment in progress |
| `needs_verification` | Roblox requires 2FA (see `error.next_action`) |
| `completed` | Done — see `external_id` or `error.codes` |
| `failed` | Error occurred — balance refunded |

```json
{
  "order_code": "API-1718183020-A3F5C9",
  "category": "chatgpt",
  "item_key": "plus_1m",
  "amount_rub": 1499.00,
  "cost_rub": 0,
  "profit_rub": 1499.00,
  "status": "completed",
  "external_id": "XXXX-YYYY-ZZZZ",
  "error": "{\"codes\":[\"XXXX-YYYY-ZZZZ\"]}",
  "created_at": "2026-06-12 10:23:40",
  "completed_at": "2026-06-12 10:23:46"
}
```

### GET /v1/orders?limit=20&offset=0

List your orders in reverse chronological order. `limit` capped at 100.

```json
{
  "orders": [...],
  "limit": 20,
  "offset": 0
}
```

---

## NFT Rent

Rent Telegram-native NFTs (Gifts, Anonymous Numbers, Usernames). Powered by marketapp.ws.

Categories: `gifts`, `numbers`, `usernames`.

### GET /v1/rent/{category}?cursor=...

List available NFTs for rent with RUB prices (markup of your franchise applied).

```json
{
  "category": "numbers",
  "items": [
    {
      "nft_address": "EQAIhwN...",
      "name": "",
      "price_per_day_rub": 232.28,
      "raw": {"price_per_day_nano": "910000000"}
    }
  ],
  "next_cursor": "..."
}
```

### POST /v1/rent

```json
{
  "category": "numbers",
  "nft_address": "EQAIhwN...",
  "duration_days": 7,
  "expected_price_rub": 1625.96
}
```

- `duration_days`: 1–365
- `expected_price_rub`: optional. If real price drifted >5% you get **409 Conflict** — re-fetch listing and retry.

Atomic balance debit. On marketapp failure → automatic refund.

Response:

```json
{
  "rental_id": 42,
  "status": "active",
  "category": "numbers",
  "nft_address": "EQAIhwN...",
  "nft_name": "",
  "duration_days": 7,
  "total_rub": 1625.96,
  "total_ton": 6.37,
  "tx_hash": "...",
  "ends_at_unix": 1786200000
}
```

### GET /v1/rentals?limit=20&offset=0

Your rentals (active + history).

```json
{
  "rentals": [
    {
      "id": 42,
      "category": "numbers",
      "nft_address": "...",
      "nft_name": "",
      "duration_sec": 604800,
      "paid_rub": 1625.96,
      "total_ton": 6.37,
      "status": "active",
      "tx_hash": "...",
      "started_at": "2026-06-12 13:10:00",
      "end_at": 1786200000
    }
  ]
}
```

---

## Pricing

- Catalog prices **float** with the USD exchange rate — may change throughout the day.
- Price is **locked at order creation** (`POST /v1/order`). The amount won't change after that, even if the catalog moves.
- For batch orders: fetch `GET /v1/catalog` fresh to see current prices.

---

## Behavior & Limits

- **Max 5 active keys** per user. Revoke an old key to create a new one.
- **Atomic debit**: balance decreases strictly on HTTP 200/201. On failed fulfillment it's refunded automatically.
- **Idempotency**: each `POST /v1/order` creates a new order. Repeating identical requests = new purchases.
- **Polling**: check status every 2–3 seconds via `GET /v1/order/{code}`.

---

## Examples

### curl

```bash
API_KEY="pad_live_..."

# Balance
curl -H "Authorization: Bearer $API_KEY" \
  https://api.padington.com/v1/balance

# Catalog
curl -H "Authorization: Bearer $API_KEY" \
  https://api.padington.com/v1/catalog

# Buy ChatGPT Plus
curl -X POST https://api.padington.com/v1/order \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"chatgpt","item":"plus_1m"}'

# Poll status
curl -H "Authorization: Bearer $API_KEY" \
  https://api.padington.com/v1/order/API-1718183020-A3F5C9
```

### Python

```python
import requests, time

API_KEY = "pad_live_..."
BASE = "https://api.padington.com/v1"
H = {"Authorization": f"Bearer {API_KEY}"}

# Balance
print(requests.get(f"{BASE}/balance", headers=H).json())

# Buy Claude Pro
r = requests.post(
    f"{BASE}/order",
    headers={**H, "Content-Type": "application/json"},
    json={"category": "claude", "item": "pro"},
).json()
code = r["order_code"]
print(f"Order: {code}, amount: {r['amount_rub']} RUB")

# Poll until done
while True:
    o = requests.get(f"{BASE}/order/{code}", headers=H).json()
    if o["status"] in ("completed", "failed"):
        print(o)
        break
    time.sleep(2)
```

### JavaScript / Node

```javascript
const API_KEY = "pad_live_...";
const BASE = "https://api.padington.com/v1";
const H = { "Authorization": `Bearer ${API_KEY}` };

const balance = await fetch(`${BASE}/balance`, { headers: H }).then(r => r.json());
console.log(balance);

const order = await fetch(`${BASE}/order`, {
  method: "POST",
  headers: { ...H, "Content-Type": "application/json" },
  body: JSON.stringify({ category: "chatgpt", item: "plus_1m" }),
}).then(r => r.json());
console.log(order);
```

---

## Support

For questions and bugs, create a ticket via the **"Support"** section inside your bot.

Padington Shop API v1 · build 2026-06-12