Policy engine

Every payout — from POST /v1/withdraws or the request_payout MCP tool — is evaluated by the policy engine before anything moves. There are no scopes and no per-key policy: thresholds are configured per user, and every API key belonging to that user shares the same policy.

Decisions

The engine returns one of three decisions:

Decision	Meaning
allow	Payout executes immediately against the bank rail
require_approval	Payout attempt is created with status: "pending_approval"; a WhatsApp/Telegram approval request is sent
deny	Request is rejected outright with 422 PAYOUT_DENIED — no approval possible

Rule order

The first rule that matches returns immediately — later rules are never evaluated.

1. KYC incomplete → deny (kyc_incomplete) if the user has no linked bank-rail account yet or onboarding != "done".
2. Invalid amount → deny (amount_invalid) if amount <= 0.
3. Whitelist fast-path → allow if the destination CBU is in whitelist_cbus and amount <= per_tx_limit_ars. If the destination is whitelisted but exceeds the per-tx limit, evaluation continues to the next rules instead of stopping here.
4. Absolute cap → require_approval (absolute_cap) if require_approval_above_ars > 0 and amount >= require_approval_above_ars.
5. Per-transaction limit → require_approval (per_tx_limit) if per_tx_limit_ars > 0 and amount > per_tx_limit_ars.
6. Daily limit → require_approval (daily_limit) if daily_limit_ars > 0 and daily_spent_so_far + amount > daily_limit_ars.
7. Monthly limit → require_approval (monthly_limit) if monthly_limit_ars > 0 and monthly_spent_so_far + amount > monthly_limit_ars.
8. Default → allow.

Caution

This is the current 8-rule pipeline. There is no velocity check, fragmentation/smurfing detection, or “new destination” rule in the running code, even if older internal notes mention them — don’t rely on those.

Thresholds

Read and write the thresholds behind these rules with GET/PUT /v1/thresholds or the get_thresholds / propose_threshold_change MCP tools:

{
  "per_tx_limit_ars": 100000,
  "daily_limit_ars": 300000,
  "monthly_limit_ars": 2000000,
  "require_approval_above_ars": 500000,
  "whitelist_cbus": ["0000003100010000123456"]
}

If a user has no thresholds row yet, nuez falls back to the server defaults (env vars DEFAULT_PER_TX_LIMIT_ARS, DEFAULT_DAILY_LIMIT_ARS, DEFAULT_MONTHLY_LIMIT_ARS, DEFAULT_REQUIRE_APPROVAL_ABOVE_ARS) rather than erroring.

Note

propose_threshold_change (MCP) always sends a WhatsApp confirmation and never applies the change directly — it’s a proposal, not a write. PUT /v1/thresholds (REST), by contrast, writes immediately with no approval step. Use the REST endpoint for programmatic policy management and the MCP tool when an agent is proposing a change on a user’s behalf.

Whitelist

whitelist_cbus is a flat list of CBU/CVU strings. It only grants a fast-path to allow — it never bypasses rules 1–2, and a whitelisted destination above per_tx_limit_ars still falls through to the threshold rules like any other payout.

Spend tracking

daily_spent_so_far and monthly_spent_so_far are computed live from SumDailySpent / SumMonthlySpent over the user’s payout attempts — there’s no separate ledger to keep in sync.