Operational Limits
Operational Limits
Operational limits control how much value an identity can move through Virtual Accounts within a configured compliance window. Limits apply per person (legal identity), not per virtual account: a person with multiple virtual accounts shares the same limit pool.
Virtual Accounts enforces limits on both directions: incoming deposits and outgoing payouts each consume the identity's operational limit. If the same identity also operates RAMPS, see RAMPS Operational Limits for the exchange limits that apply there.
How Limits Work
- Type
VIRTUAL_ACCOUNTS: this is the limit the Virtual Accounts product consumes. It is independent from theEXCHANGEandREMITTANCElimits of the same identity, which belong to other products. - Denominated in USDT: operational limits for Virtual Accounts are stored in USDT and apply to all transfers regardless of the local fiat currency. You can request limits converted to any supported asset using the
assetquery parameter. - Both directions consume the same pool: incoming deposits and outgoing payouts draw down one shared monthly and yearly balance. A round trip of 1,000 USDT therefore consumes 2,000 USDT of the allowance.
- Monthly and yearly only: there is no daily window for Virtual Accounts. A transfer is blocked if it would exceed the monthly or the yearly balance.
- Per identity, not per account: limits are tied to the legal ID (
numberId) of the person, not to individual virtual account records.
| Situation | Behavior |
|---|---|
| Within monthly and yearly limits | Transfer proceeds |
| Near threshold (10% remaining) | COMPLIANCE_NOTICE webhook fires with CLOSE_TO_OPERATION_LIMIT |
| Limit updated by compliance team | COMPLIANCE_NOTICE webhook fires with OPERATION_LIMIT_UPDATED |
| Outgoing payout exceeds limit | Payout fails asynchronously (CANCELLED with R3); it is not rejected at request time |
| Incoming deposit exceeds limit | Deposit is not credited: the funds are automatically returned to the sender |
Querying Limits
GET /wallet/v1/limits/{numberId}
GET /wallet/v1/limits/{numberId}?asset=USDT
GET /wallet/v1/limits?legalIdNationality=ARG&legalId=20406620000
GET /wallet/v1/limits?legalIdNationality=ARG&legalId=20406620000&asset=USDT
Returns the current limit state for an identity. Two lookup variants are supported and return the same response shape:
- By Manteca
numberId: path parameter. Use under the End-user model, where the partner holds a Manteca user record per end-user. - By legal identity:
legalIdNationality+legalIdas query parameters. Use under the Principal Accounts model, where the partner only holds the end-user's legal identity (the value declared insender.legalId).
Query Parameters
| Parameter | Required | Description |
|---|---|---|
legalIdNationality | Conditional | ISO country code of the legal identity (e.g. ARG, BRA, MEX). Required when querying by legal identity instead of numberId. Must be sent together with legalId. |
legalId | Conditional | National ID or tax number of the end-user (matches the value used in sender.legalId). Required when querying by legal identity instead of numberId. Must be sent together with legalIdNationality. |
asset | No | Convert limit amounts to this asset (e.g. USDT, BTC, ETH). If omitted, amounts are returned in the user's native limit currency. Uses live market prices for conversion. |
Response
The response is an array. For Virtual Accounts it always contains exactly one record, the
VIRTUAL_ACCOUNTS limit of the identity. The EXCHANGE and REMITTANCE limits of the same
identity are not part of this contract and are never returned here.
[
{
"exchangeCountry": "BRA",
"type": "VIRTUAL_ACCOUNTS",
"asset": "USDT",
"yearlyLimit": "120000.00000000",
"availableYearlyLimit": "118500.00000000",
"monthlyLimit": "10000.00000000",
"availableMonthlyLimit": "8500.00000000"
}
]| Field | Description |
|---|---|
exchangeCountry | ISO country code for the limit jurisdiction |
type | Limit type, always VIRTUAL_ACCOUNTS for Virtual Account transfers |
asset | Denomination asset: matches the asset query parameter if provided, otherwise USDT |
yearlyLimit | Total allowed per year |
availableYearlyLimit | Remaining yearly allowance |
monthlyLimit | Total allowed per month |
availableMonthlyLimit | Remaining monthly allowance |
Note: There are no
dailyLimit/availableDailyLimitfields: Virtual Accounts has no daily window.
Note: An identity that has never moved funds through a Virtual Account has no limit record yet. Querying it returns the full default allowance rather than an error, and does not create anything.
Note: When using
asset, amounts are converted using live market prices at the time of the request. The same limit queried at different times may return slightly different values as prices fluctuate.
Compliance Webhooks
The platform emits COMPLIANCE_NOTICE events for limit-related state changes that affect Virtual Account transfers.
| Event | Trigger |
|---|---|
CLOSE_TO_OPERATION_LIMIT | Identity has 10% or less of an operational limit remaining |
OPERATION_LIMIT_UPDATED | Compliance team adjusted the identity's operational limit |
Subscribe to COMPLIANCE_NOTICE to proactively surface limit proximity to users before transfers are blocked.
When a Limit Is Exceeded
The limit is evaluated after the transfer is accepted, not at request time. POST /wallet/v1/transfers still returns 2xx; the outcome arrives asynchronously.
Outgoing payouts that exceed a limit move to CANCELLED and carry the generic error code R3 in genericErrorMessage:
R3: Exceeds virtual account limits
Watch the transfer status webhook, or poll GET /wallet/v1/transfers/{transferAnyId}, to detect it. Do not retry as-is: the outcome will not change until the limit resets (monthly/yearly cycle), the user uploads fund-origin documentation, or the compliance team raises the limit. See Raise Limits and the error handling reference for the full catalog.
Incoming deposits that would exceed a limit are not credited to the virtual account. The funds are automatically returned to the sender: no manual action is required on your side, and no separate error is returned to the account owner. Query the identity's limits if you want to surface remaining allowance before the deposit is attempted.
Implementation Requirements
- Parse and persist
internalStatusfrom every non-2xx response. - Show clear user-facing messaging for blocked transfers: do not surface raw error codes.
- Avoid blind retries when a limit is exceeded.
- Route blocked cases to your review or escalation path.
Default Limits
Every legal identity starts with the same Virtual Accounts allowance, denominated in USDT and consumed by both incoming deposits and outgoing payouts:
| Monthly | Yearly |
|---|---|
| 10,000 | 120,000 |
Note: Because both directions share the pool, 10,000 USDT per month is roughly 5,000 USDT of round-trip volume.
Note: Monthly and yearly limits are calendar-based, not rolling. Users who upload fund-origin documentation, or whose limit the compliance team raises, operate above these defaults.
Relationship with RAMPS
Operational limits are configured per legal identity (numberId). The VIRTUAL_ACCOUNTS cap is independent from the RAMPS caps: moving funds through a Virtual Account does not consume the identity's EXCHANGE or REMITTANCE allowance, and vice versa.
For the limits that apply to RAMPS operations, see RAMPS Operational Limits.
Raising Limits
Use Raise Limits for the escalation and reprocessing sequence when a user needs a higher outbound threshold.
Updated 27 days ago