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 the EXCHANGE and REMITTANCE limits 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 asset query 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.
SituationBehavior
Within monthly and yearly limitsTransfer proceeds
Near threshold (10% remaining)COMPLIANCE_NOTICE webhook fires with CLOSE_TO_OPERATION_LIMIT
Limit updated by compliance teamCOMPLIANCE_NOTICE webhook fires with OPERATION_LIMIT_UPDATED
Outgoing payout exceeds limitPayout fails asynchronously (CANCELLED with R3); it is not rejected at request time
Incoming deposit exceeds limitDeposit 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 + legalId as query parameters. Use under the Principal Accounts model, where the partner only holds the end-user's legal identity (the value declared in sender.legalId).

Query Parameters

ParameterRequiredDescription
legalIdNationalityConditionalISO 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.
legalIdConditionalNational 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.
assetNoConvert 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"
  }
]
FieldDescription
exchangeCountryISO country code for the limit jurisdiction
typeLimit type, always VIRTUAL_ACCOUNTS for Virtual Account transfers
assetDenomination asset: matches the asset query parameter if provided, otherwise USDT
yearlyLimitTotal allowed per year
availableYearlyLimitRemaining yearly allowance
monthlyLimitTotal allowed per month
availableMonthlyLimitRemaining monthly allowance

Note: There are no dailyLimit / availableDailyLimit fields: 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.

EventTrigger
CLOSE_TO_OPERATION_LIMITIdentity has 10% or less of an operational limit remaining
OPERATION_LIMIT_UPDATEDCompliance 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 internalStatus from 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:

MonthlyYearly
10,000120,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.


Did this page help you?