Limit Status

Who calls these endpoints?External API (s2s)

Base path: /api/v1/wallet
Identity: Ed25519 request signature — X-Key-Id, X-Date, X-Nonce, Digest (when there is a body), X-Signature. ±5 min clock window, single-use nonce, optional per-key IP allow-list.
Authorization: The key must carry the wallet product and the wallet permission the call requires; a call without it gets 403 WALLET_INSUFFICIENT_SCOPE. Permissions per endpoint: Key permissions.
Cross-surface: The same read exists in the merchant panel; the end user reads their own limits through the portal. Limit schemes are defined in the panel only. This endpoint requires a wallet read permission (wallet:enduser:read) on your key.

GET /api/v1/wallet/end-users/{id}/limits

Returns the user's current limit usage: which cap applies, how much has been used and how much is left. How limits are defined and counted is described in Limits; this page covers the read endpoint only.

Query parameters

Parameter	Type	Rule and meaning
`operationType`	string	Up to 32 characters; letters, digits and `_`. Case-insensitive. If given, only the counters that bind this operation type are returned (see below). If omitted, every row of your scheme is returned.
`currency`	string	3–8 letters. Defaults to `TRY`.

Send operation type names as operationType; for example W2W_TRANSFER, W2IBAN_WITHDRAW, WITHDRAW_BANK, PAYMENT_BUY, BILL_PAY, TOPUP_CARD. To see your scheme's wallet-total row (*), omit the parameter; * is not accepted in this parameter.

Which rows are returned

Rows are taken from the limit scheme assigned to your program, for the user's effective KYC level and the requested currency.

Without operationType: one row per operation type defined in your scheme for this level and currency (bucket: OPERATION_TYPE), and, if there is a wallet-total row, two more rows: the outflow total (WALLET_TOTAL_OUTFLOW) and the inflow total (WALLET_TOTAL_INFLOW). These two rows carry operationType *.
With operationType: the type's own row (if defined) and the wallet-total row that binds the type (if defined). For an operation to go through, every returned row must have room.

The operation types counted as inflow are TOPUP_CARD, TOPUP_TRANSFER, TOPUP_AGENT, TOPUP_REFUND and REFUND_CREDIT; they are added to the WALLET_TOTAL_INFLOW total. Every other type is an outflow and is added to the WALLET_TOTAL_OUTFLOW total.

Example

curl "https://api-gateway.lunixi.com/api/v1/wallet/end-users/8d4c2a1f-3b6e-4f7a-9c5d-2e8b1a0f6c34/limits?operationType=W2W_TRANSFER&currency=TRY" \
  -H "X-Key-Id: …" -H "X-Date: …" -H "X-Nonce: …" -H "X-Signature: …"

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "statuses": [
      {
        "operationType": "W2W_TRANSFER",
        "bucket": "OPERATION_TYPE",
        "currency": "TRY",
        "kycLevel": "LOW",
        "schemeId": "a41c7e2b-9d3f-4b8a-8e5c-2f1d6b9a0c37",
        "singleMax": "500000",
        "daily": {
          "amountLimit": "1000000",
          "amountUsed": "125000",
          "amountRemaining": "875000",
          "countLimit": 20,
          "countUsed": 3,
          "countRemaining": 17
        },
        "monthly": {
          "amountLimit": "3000000",
          "amountUsed": "410000",
          "amountRemaining": "2590000",
          "countLimit": null,
          "countUsed": 11,
          "countRemaining": null
        }
      },
      {
        "operationType": "W2W_TRANSFER",
        "bucket": "WALLET_TOTAL_OUTFLOW",
        "currency": "TRY",
        "kycLevel": "LOW",
        "schemeId": "a41c7e2b-9d3f-4b8a-8e5c-2f1d6b9a0c37",
        "singleMax": null,
        "daily": {
          "amountLimit": "2000000",
          "amountUsed": "180000",
          "amountRemaining": "1820000",
          "countLimit": null,
          "countUsed": 5,
          "countRemaining": null
        },
        "monthly": {
          "amountLimit": "5000000",
          "amountUsed": "650000",
          "amountRemaining": "4350000",
          "countLimit": null,
          "countUsed": 19,
          "countRemaining": null
        }
      }
    ],
    "sharedCaps": []
  },
  "requestId": "…"
}

`statuses[]` fields

Field	Type	Meaning
`operationType`	string	The operation type of the row; `*` on wallet-total rows (when queried without `operationType`) or the type you queried.
`bucket`	string	The counter kind: `OPERATION_TYPE` (type-specific counter), `WALLET_TOTAL_OUTFLOW` (shared total of all outflows), `WALLET_TOTAL_INFLOW` (shared total of all inflows).
`currency`	string	The counter currency.
`kycLevel`	string	The effective KYC level used (`NONE`, `LOW`, `SUBSTANTIAL`, `HIGH`).
`schemeId`	UUID	The limit scheme applied.
`singleMax`	string \| null	Highest amount allowed in a single operation (minor-unit). `null` = no single-operation cap.
`daily`, `monthly`	object	The daily and monthly window.
`….amountLimit`	string \| null	Amount cap in the window (minor-unit). `null` = no amount cap in this window.
`….amountUsed`	string	Amount used in the window (minor-unit).
`….amountRemaining`	string \| null	Remaining amount. `null` if there is no cap.
`….countLimit`	number \| null	Operation count cap in the window. `null` = no count cap.
`….countUsed`	number	Number of operations in the window.
`….countRemaining`	number \| null	Remaining count. `null` if there is no cap.

Used amount and count include the reservations of operations that have started but not yet settled; details: Limits — Reservations and operation lifetime.

`sharedCaps[]` — cross-channel shared cap

If your program has a cap shared by selected outflow channels, its usage is returned in sharedCaps. If not, the list is empty.

Field	Type	Meaning
`capCode`	string	The cap code.
`description`	string \| null	Description.
`members`	string[]	The operation types that fill this cap together.
`currency`, `kycLevel`, `schemeId`	string	Same meaning as in `statuses[]`.
`daily`, `monthly`	object	Same fields as in `statuses[]`.

Show the remaining limit while the user types the amount. For a definitive answer before a money movement, call the relevant quote endpoint: the limitBlocked field in the quote response tells you the operation cannot be started because of a limit.

Errors

HTTP	Code	When
400	`VALIDATION_ERROR`	`operationType` or `currency` does not match the format
400	—	`{id}` is not a UUID
403	`WALLET_INSUFFICIENT_SCOPE`	The key has no wallet read permission
404	`WALLET_NOT_FOUND`	The user does not exist or is not yours
503	`WALLET_LIMIT_UNAVAILABLE`	The limit counters could not be read at that moment; retry shortly

Balances Wallets & Accounts