How it works

Onboarding

1. POST /v1/users with email, phone_e164, and a password. nuez creates the account, a default API key for MCP use, and (in widget onboarding mode) an identity verification widget URL.
2. Complete KYC through the widget URL.
3. Receive your CVU once onboarding finishes — GET /v1/cvu or the get_cvu MCP tool.
4. Fund your wallet by transferring to that CVU from any Argentine bank, Mercado Pago, or Ualá.
5. Generate additional API keys per agent if you want independent revocation — POST /v1/api-keys.

Until KYC (onboarding = "done") completes, the policy engine denies every payout with kyc_incomplete — see Policy engine.

Two execution flows

Under the threshold — agent executes autonomously

AGENT → POST /v1/withdraws (or request_payout MCP tool)
       → policy.Evaluate() → decision: allow
       → payout submitted to the bank rail
       → status: submitted
       → webhook: payout.requested, payout.submitted

No human involved. The payout attempt is created with decision: "allow" and executes immediately.

Over the threshold — WhatsApp or Telegram approval

1. Agent calls request_payout (MCP) or POST /v1/withdraws (REST) with an amount that trips one of the threshold rules.
2. The policy engine returns require_approval and the payout attempt is created with status: "pending_approval" — the call returns immediately with an approval_id and expires_in (seconds), it does not block or long-poll.
3. nuez sends a notification to the account owner via WhatsApp or Telegram, whichever channel is linked, with a 6-character challenge token and an amount/destination summary.
4. The owner replies APPROVE:XXXXXX / REJECT:XXXXXX (or taps a button, which sends the same format). nuez resolves the approval and updates the payout attempt to approved or rejected.
5. If approved, nuez submits the withdraw to the bank rail. A signed webhook (payout.approved, then payout.submitted/payout.confirmed) fires on your configured endpoint.
6. If no response arrives within APPROVAL_EXPIRY_MINUTES (default 5 minutes), a background worker marks it expired and fires payout.expired.

There is no MCP tool or REST endpoint to approve a payout directly — approval only happens by replying to the WhatsApp/Telegram message. Poll GET /v1/withdraws/{id} or get_payout_status to check whether a pending payout has resolved, or just wait for the webhook.

Design principle: the human only appears when it matters. Below the threshold, full autonomy. Above it, approval via a channel the owner already has open.

Architecture

┌─────────────────┐
│   AI Agent      │  Claude Desktop, Cursor, CLI, custom agent
└────────┬────────┘
         │  POST /mcp (JSON-RPC)   OR   REST /v1/* (JWT)
         ▼
┌──────────────────────────┐
│  nuez API (single :8080) │
└────────┬──────────────────┘
         │
         ▼
┌─────────────────┐
│  Policy engine  │  KYC · amount · whitelist · absolute cap ·
│                 │  per-tx / daily / monthly limits
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 Execute   Pause + notify (WhatsApp/Telegram)
    │         │
    └────┬────┘
         ▼
┌─────────────────┐
│   Bank rail     │  CVU/CBU/alias payout rail
└────────┬────────┘
         │
         ▼
  Signed webhook (X-Nuez-Signature) → your endpoint

Cards, bill payments, and crypto off-ramp follow the same pattern — MCP tool or REST call → store → underlying rail — but bill payments and card issuance are gated by their own whitelist/balance checks rather than the payout policy engine. See Cards, Bill payments, and Crypto off-ramp.