General API

FonProxy General API reference documentation.

FonProxy API — General

Base URL: https://api.fonproxy.io (production) / http://localhost:3100 (dev)

All protected endpoints require one of:

Method	Header	Example
JWT Bearer	`Authorization: Bearer <token>`	`Authorization: Bearer eyJhbGciOi...`
API Key	`x-api-key: <key>` or `?apikey=<key>`	`x-api-key: fnp_3eab...`

Email + code — POST /auth/send-code → receive 6-digit code via email → POST /auth/verify-code → get JWT token
Email + password — POST /auth/login → get JWT token
OAuth — GET /auth/external/:provider/redirect → callback → JWT token
Telegram — deep-link or /start command → POST /auth/telegram/verify → JWT token

Full auth docs: ./api-auth

The API uses the fp-locale header to determine the user's language.

fp-locale: uk

Every request: the backend reads fp-locale and uses it for server-rendered content (emails, Telegram notifications).
Logged-in users: if the header value differs from the stored locale, the backend automatically updates the user's locale in the database (fire-and-forget, no extra request needed).
Supported locales: en (English, default), uk (Ukrainian). More can be added by creating src/i18n/{code}.json.
Fallback: if the header is missing or the locale is unknown, en is used.

Channel	Translated by	How
Email (subjects, body)	Backend (`I18nService`)	Translated before rendering to HTML
Telegram messages	Backend (`I18nService`)	Translated before sending
API error messages	Frontend	Backend returns raw keys (e.g. `order.not_found`), frontend translates via next-intl
In-app notifications	Frontend	Backend stores raw keys in DB, frontend renders

The locale field is always returned in the user profile (GET /user/me) so the frontend can initialise its own i18n accordingly.

Header	Required	Description
`Authorization`	Yes (protected routes)	`Bearer <jwt>`
`x-api-key`	Alternative to JWT	API key for programmatic access
`fp-locale`	No	UI locale code (`en`, `uk`). Auto-synced to user profile.
`Content-Type`	Yes (POST/PATCH)	`application/json`

All responses are JSON. Success responses return the relevant data directly:

{
  "user": { "id": "k5Xz9qR2Wp", "name": "John", ... }
}

Error responses:

{
  "message": "order.not_found",
  "path": "/orders/80-12345",
  "timestamp": "2026-04-01T12:00:00.000Z"
}

The message field is a translation key — the frontend resolves it to a human-readable string.

All public-facing entity IDs are encoded with Hashids. Internal numeric IDs are never exposed.

Paginated endpoints accept:

Param	Default	Max	Description
`page`	`1`	—	Page number (1-based)
`limit`	`20`	`100`	Items per page

Response includes:

{
  "items": [...],
  "total": 142,
  "page": 1,
  "pages": 8
}

All prices and balances are stored in USD internally.
Display values are converted using live exchange rates.
The user's preferred display currency is set via PATCH /user/settings { "currency": "UAH" }.
Endpoints that return monetary values include both *Usd and *Display fields.

Throttled by IP address. Default: 60 requests/minute for most endpoints, 5/minute for auth endpoints.

When rate-limited, the API returns 429 Too Many Requests:

{ "message": "error.rate_limit" }