User API

FonProxy User API reference documentation.

FonProxy API — User

All /user/* endpoints require Authorization: Bearer <token>.

User

`GET /user/me`

Get the authenticated user's profile.

Query parameters:

Param	Required	Description
`visitorToken`	no	Visitor token from `POST /track/init`. Links the visitor's attribution data (UTM, referrer, landing page) to this user. Useful for users who were already logged in when they arrived via a campaign link. Always overwrites any previous visitor link for this token.

Example with visitor token:

GET /user/me?visitorToken=visitor_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Response (200):

{
  "user": {
    "id": "k5Xz9qR2Wp",
    "name": "John Doe",
    "displayName": "John Doe",
    "email": "user@example.com",
    "initials": "JD",
    "avatarUrl": "/avatars/1-a3f8c2d1.jpg",
    "role": "user",
    "balance": 10.00,
    "displayBalance": 415.20,
    "currency": "UAH",
    "hasPassword": true,
    "invitedBy": "xK9mR2pL1w",
    "createdAt": "2026-03-15T12:00:00.000Z"
  }
}

invitedBy — hashId of the user who referred this user via a referral link. null if not referred.

`PATCH /user/settings`

Update user settings. All fields are optional — send only what you want to change.

Request body:

{
  "name": "John Doe",
  "currency": "UAH",
  "password": "newPassword123",
  "currentPassword": "oldPassword123"
}

Field	Type	Required	Description
`name`	string	no	Display name. Send empty string to clear.
`currency`	string	no	Display currency code.
`password`	string	no	Set or change password. If user already has one, `currentPassword` is required.
`currentPassword`	string	no	Required only when changing an existing password.

Response (200): Full updated user profile.

`GET /user/currencies`

Get all supported display currency codes.

Response (200):

{
  "currencies": ["USD", "EUR", "GBP", "PLN", "CZK", "HUF", "RON", "SEK", "NOK", "DKK", "CHF", "HRK", "BGN", "UAH", "TRY"]
}

`GET /user/transactions`

List the authenticated user's balance transactions (paginated, filterable).

Query params: ?page=1&limit=20&type=deposit&status=completed&from=2026-01-01&to=2026-03-16&currency=UAH

Param	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 100)
`type`	string	—	Filter by type: `deposit`, `withdrawal`, `purchase`, `refund`, `bonus`, `correction`
`status`	string	—	Filter by status: `pending`, `completed`, `failed`, `cancelled`
`from`	string	—	ISO date — start of date range
`to`	string	—	ISO date — end of date range
`currency`	string	user account currency	Override display currency

Response (200):

{
  "currency": "UAH",
  "transactions": [
    {
      "id": "k5Xz9qR2Wp",
      "type": "deposit",
      "status": "completed",
      "amount": 4100.00,
      "currency": "UAH",
      "balanceBefore": 0,
      "balanceAfter": 4100.00,
      "exchangeRate": 41.0,
      "amountUsd": 100.00,
      "balanceBeforeUsd": 0,
      "balanceAfterUsd": 100.00,
      "originalAmount": 4100,
      "originalCurrency": "UAH",
      "description": "Top-up via Monobank",
      "referenceType": "topup",
      "referenceId": "aBcDeFgHiJ",
      "receiptUrl": "https://api.fonproxy.io/receipts/k5Xz9qR2Wp",
      "meta": { "gateway": "monobank", "invoiceId": "abc123" },
      "createdAt": "2026-03-15T12:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 3
}

`GET /user/graphs/balance`

Get balance history graph data. Returns the universal graph format.

Query params: ?from=2026-02-14&to=2026-03-16&granularity=day&currency=UAH

Param	Type	Default	Description
`from`	string	30 days ago	ISO date — start of range
`to`	string	now	ISO date — end of range
`granularity`	string	auto	`hour`, `day`, `week`, or `month`
`currency`	string	user account currency	Override display currency

Response (200):

{
  "graph": "balance_history",
  "granularity": "day",
  "from": "2026-02-14T00:00:00.000Z",
  "to": "2026-03-16T00:00:00.000Z",
  "series": [
    {
      "key": "balance",
      "label": "Balance",
      "color": "#E6318B",
      "points": [
        { "t": "2026-02-14T00:00:00.000Z", "v": 0 },
        { "t": "2026-02-15T00:00:00.000Z", "v": 430.85 }
      ]
    }
  ],
  "meta": {
    "currency": "UAH",
    "startBalance": 0,
    "endBalance": 337.15,
    "startBalanceUsd": 0,
    "endBalanceUsd": 8.25,
    "exchangeRate": 41.0
  }
}

Avatar

`GET /avatar/:identifier`

Serve the user's avatar. Public — no auth required.

If user has avatarUrl → 302 redirect
If user has no avatarUrl → deterministic SVG with initials

Examples:

GET /avatar/k5Xz9qR2Wp       ← by hashid
GET /avatar/user@example.com ← by email

`POST /user/avatar`

Upload a new avatar image. Requires JWT.

Content-Type: multipart/form-data Field name: file Accepted formats: JPEG, PNG, WebP, GIF Max size: 5 MB

Response (200):

{
  "avatarUrl": "/avatars/1-a3f8c2d1.jpg",
  "user": { "...": "full updated user profile" }
}

`DELETE /user/avatar`

Remove the current avatar. Requires JWT.

Response (200):

{
  "user": { "...": "full updated user profile with avatarUrl: null" }
}