User API

FonProxy user endpoints: profile, settings, email change, currencies, transactions, balance graph, and avatar.

Updated 2026-04-09 16:13:00

For authentication and common headers, see API General.

User

Get Current User Auth required

GET /user/me

Get the authenticated user's profile. @re

Response

{
  "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",
    "locale": "en",
    "hasPassword": true,
    "invitedBy": "xK9mR2pL1w",
    "createdAt": "2026-03-15T12:00:00.000Z"
  }
}

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

Update Settings Auth required

PATCH /user/settings

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

Request Body

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

Response

Full updated user profile.

Request Email Change Auth required

POST /user/email/request-change

Send a 6-digit confirmation code to the new email address. The code expires in 10 minutes. Previous pending codes for the same address are invalidated.

Request Body

Name	Type	Description	Required
`email`	`string`	New email address	Yes

Response

{ "message": "user.email_change_code_sent" }

Errors:

{ "message": "user.email_required" }
{ "message": "user.email_already_taken" }

Confirm Email Change Auth required

POST /user/email/confirm

Confirm the email change by submitting the code that was sent to the new address. On success the user's email is updated and the full updated profile is returned.

Request Body

Name	Type	Description	Required
`email`	`string`	New email address (must match the request)	Yes
`code`	`string`	6-digit confirmation code	Yes

Response

{ "user": { "...": "full profile with updated email" } }

Errors:

{ "message": "user.email_change_code_invalid" }
{ "message": "user.email_already_taken" }

List Currencies Auth required

GET /user/currencies

Get all supported display currency codes.

Response

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

List Transactions Auth required

GET /user/transactions

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

Query Parameters

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

Response

{
  "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
}

Balance History Graph Auth required

GET /user/graphs/balance

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

Query Parameters

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

Response

{
  "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 },
        ...
      ]
    }
  ],
  "meta": {
    "currency": "UAH",
    "startBalance": 0,
    "endBalance": 337.15,
    "startBalanceUsd": 0,
    "endBalanceUsd": 8.25,
    "exchangeRate": 41.0
  }
}

Avatar

Get 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

Accepts ID or email as identifier:

GET /avatar/k5Xz9qR2Wp
GET /avatar/user@example.com

Upload Avatar Auth required

POST /user/avatar

Upload a new avatar image.

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

Response

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

Delete Avatar Auth required

DELETE /user/avatar

Remove the current avatar.

Response

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

API Reference

Copy page as Markdown for AI / LLM