Transfers

POST /v1/transfers

Initiates a transfer from your nuez wallet.

Requires scope: transfer:write
Requires header: Idempotency-Key

Request

curl -X POST https://api.nuez.app/v1/transfers \
  -H "Authorization: Bearer nz_sk_live_..." \
  -H "Idempotency-Key: inv-2026-04-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "destination": "proveedor.empresa",
    "description": "Invoice #42"
  }'

Body parameters

Parameter	Type	Required	Description
`amount`	`number`	✓	Amount in ARS. Minimum: `1`.
`destination`	`string`	✓	CVU (22 digits), CBU (22 digits), or alias
`description`	`string`		Transfer description. Max 140 chars.

Response — completed

{
  "id": "txn_01HXYZ...",
  "status": "completed",
  "amount": 5000,
  "destination": "proveedor.empresa",
  "description": "Invoice #42",
  "created_at": "2026-04-23T14:32:00Z",
  "completed_at": "2026-04-23T14:32:02Z"
}

Response — approval required

When amount ≥ threshold, the request holds open (long poll, up to 5 minutes) until the owner approves or rejects. On approval:

{
  "id": "txn_01HXYZ...",
  "status": "approved",
  "amount": 50000,
  "destination": "proveedor.empresa",
  "approved_at": "2026-04-23T14:33:15Z",
  "completed_at": "2026-04-23T14:33:16Z"
}

Error codes

HTTP	Code	Description
`402`	`insufficient_balance`	Balance below requested amount
`402`	`rejected`	Owner rejected WhatsApp approval
`408`	`expired`	Approval timed out (5 min)
`422`	`invalid_destination`	CVU/CBU/alias could not be resolved
`422`	`allowlist_violation`	Destination not in key allowlist

GET /v1/transfers/{id}

Retrieve a single transfer by ID.

Requires scope: transactions:read

curl https://api.nuez.app/v1/transfers/txn_01HXYZ... \
  -H "Authorization: Bearer nz_sk_live_..."

Returns the same shape as the POST response.