Módulo Wallet

Wallet · CVU + Balance

Cuenta operativa donde tu agente trabaja. Un master pool con CVU propio y, opcionalmente, un sub-wallet por agente con cap acotado. History append-only sobre un ledger de doble entrada.

Estado: rail simulado
Los movimientos son asientos en el ledger interno. El rail bancario real (BindX) todavía no está integrado: POST /v1/wallet/fund acredita saldo directo hasta que lo reemplace el webhook del provider. La lógica de wallet, sub-wallets, caps y aprobaciones ya es la definitiva.

Autenticación

Todas las rutas viven bajo https://argentive.ai/api/v1/wallet y aceptan tanto el JWT de sesión (cookie) como un personal token Bearer argentive_sk_.... La CLI @argentive/pay usa el token: corré apay auth login para obtenerlo.

Unidades de monto

  • Los balances en las respuestas vienen en unidades (2 decimales, ej 50000.00).
  • initial_amount (al crear un sub-wallet) va en unidades.
  • amount_cents, threshold_cents y los *_cents del approval config van en centavos.

GET /v1/wallet

Devuelve la wallet del usuario autenticado. Provisioning idempotente: crea la wallet on-demand la primera vez que la consultás.

curl
curl -X GET https://argentive.ai/api/v1/wallet \
  -H "Authorization: Bearer argentive_sk_..."

Response 200

response
{
  "id":         "wal_01HW3F...",
  "cvu":        "0000034456789012345678",
  "alias":      "juan.argentive",
  "currency":   "ARS",
  "balance": {
    "available":  145892.50,
    "pending":         0.00,
    "total":     145892.50
  },
  "sub_wallets": [
    {
      "id":        "swal_01HW3F...",
      "agent":     "claude-desktop",
      "purpose":   "Suscripciones SaaS",
      "payees":    ["alias:openai.pagos"],
      "cvu":       "0000034456789012345679",
      "balance":   45000.00,
      "currency":  "ARS",
      "status":    "active",
      "approval_config": {
        "auto_approve_under_cents": 100000,
        "whatsapp_threshold_cents": 1000000,
        "panic_limit_24h_cents":    5000000
      },
      "created_at": "2026-07-01T12:04:33Z"
    }
  ],
  "provider":   "simulated",
  "approval_config": {
    "auto_approve_under_cents": 100000,
    "whatsapp_threshold_cents": 1000000,
    "panic_limit_24h_cents":    5000000
  },
  "created_at": "2026-05-14T09:22:00Z",
  "updated_at": "2026-07-01T12:04:33Z"
}

GET /v1/wallet/fund-info

Datos para transferir plata a tu wallet (CVU, alias, titular, CUIT, rails).

response
{
  "cvu":         "0000034456789012345678",
  "alias":       "juan.argentive",
  "holder_name": "Juan Pérez",
  "tax_id":      "20-12345678-9",
  "rails":       ["CVU", "transferencia 3.0"]
}

POST /v1/wallet/fund

Fondeo simulado del master wallet (acredita saldo directo mientras no haya rail real). Cuando se integre BindX lo reemplaza el webhook del provider.

curl
curl -X POST https://argentive.ai/api/v1/wallet/fund \
  -H "Authorization: Bearer argentive_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 10000000 }'

Response 200 — la wallet actualizada (mismo shape que GET /v1/wallet).

GET /v1/wallet/history

Lista los movimientos de la wallet (créditos, débitos, allocations). Paginado, ordenado desc por fecha.

curl
curl -X GET "https://argentive.ai/api/v1/wallet/history?limit=25&type=all" \
  -H "Authorization: Bearer argentive_sk_..."

Query params

  • limit — 1-100 (default 25)
  • cursor — para paginar (opaque, viene en response)
  • type — credit | debit | all
  • module — filtrar por módulo origen: wallet, send, pay, etc

Response 200

response
{
  "data": [
    {
      "id":         "wev_01HW3F...",
      "type":       "debit",
      "module":     "pay",
      "amount":     25000.00,
      "currency":   "ARS",
      "balance_after": 145892.50,
      "reference":  { "type": "wallet_scheduled", "id": "appr_01HW3F..." },
      "metadata":   { "payee": "openai.pagos", "agent": "claude-desktop" },
      "description": "Pago programado a openai.pagos (claude-desktop)",
      "created_at":  "2026-07-01T12:04:33Z"
    }
  ],
  "next_cursor": "cur_MjAyNi0wNy0wMVQxMjowM..."
}

GET /v1/wallet/sub-wallets

Lista los sub-wallets por agente.

response
{ "data": [ /* SubWallet[] — mismo shape que sub_wallets en GET /v1/wallet */ ] }

POST /v1/wallet/sub-wallets

Crea un sub-wallet para un agente. Acota el blast-radius: el agente solo opera sobre este cap, no sobre el master. Idempotente por (wallet, agent_label) — recrear con el mismo label devuelve el sub-wallet existente.

curl
curl -X POST https://argentive.ai/api/v1/wallet/sub-wallets \
  -H "Authorization: Bearer argentive_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_label":     "claude-desktop",
    "initial_amount":  50000,
    "purpose":         "Suscripciones SaaS",
    "payees":          ["alias:openai.pagos"],
    "threshold_cents": 1000000
  }'

Body

  • agent_label — requerido, string
  • initial_amount — cap inicial en unidades (default 0)
  • purpose — opcional, para qué usa la plata el agente
  • payees — opcional, lista de destinatarios permitidos
  • threshold_cents — opcional, umbral WhatsApp en centavos (mapea a whatsapp_threshold_cents)
  • approval_config — opcional, override completo (auto_approve_under_cents, whatsapp_threshold_cents, panic_limit_24h_cents)

Response 201 — el SubWallet creado.

PATCH /v1/wallet/sub-wallets/:id

Edita la config del sub-wallet. Todos los campos son opcionales; solo se aplica lo presente. 404 si el sub-wallet no es tuyo.

curl
curl -X PATCH https://argentive.ai/api/v1/wallet/sub-wallets/swal_01HW3F... \
  -H "Authorization: Bearer argentive_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "purpose":         "Solo infra cloud",
    "payees":          ["alias:aws.pagos", "alias:vercel.pagos"],
    "threshold_cents": 500000
  }'

Response 200 — el SubWallet actualizado.

POST /v1/wallet/sub-wallets/:id/allocate

Sube el cap operativo del sub-wallet (master → agente). Valida la invariante sum(sub_caps) <= master.available.

curl
curl -X POST https://argentive.ai/api/v1/wallet/sub-wallets/swal_01HW3F.../allocate \
  -H "Authorization: Bearer argentive_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 2000000 }'

Response 200 — el SubWallet con el cap nuevo. 409 insufficient_funds si el master no alcanza.

GET /v1/wallet/scheduled

Lista los pagos programados (recurrentes vía cron u one-shot). Cada fire dispara un approval humano por WhatsApp; el débito real lo hace el webhook al aprobar.

response
{
  "data": [
    {
      "id":             "sched_01HW3F...",
      "agentLabel":     "claude-desktop",
      "payee":          "openai.pagos",
      "payeeCvu":       null,
      "payeeAlias":     "alias:openai.pagos",
      "amountCents":    2500000,
      "currency":       "ARS",
      "reason":         "Suscripción ChatGPT Team",
      "cronExpression": "0 9 1 * *",
      "nextRunAt":      "2026-08-01T12:00:00Z",
      "lastRunAt":      "2026-07-01T12:00:00Z",
      "lastStatus":     "completed",
      "status":         "active",
      "createdAt":      "2026-06-01T09:00:00Z"
    }
  ]
}
amountCents en centavos
A diferencia de los balances (unidades), /scheduled devuelve amountCents en centavos. Dividí por 100 para mostrar.

Errores comunes

errores
401  unauthorized              Falta o es inválido el Bearer token
400  agent_label_required      POST sub-wallets sin agent_label
400  invalid_amount            amount_cents <= 0 (fund / allocate)
404  not_found                 El sub-wallet no es del usuario (PATCH / allocate)
409  insufficient_funds        allocate excede el available del master

CLI

Todo lo anterior está cableado en @argentive/pay:

apay
apay wallet                     # overview: CVU, balance, agentes
apay wallet fund --amount 100000
apay wallet agents create --agent claude-desktop --amount 50000 \
  --purpose "SaaS" --payee alias:openai.pagos --threshold 10000
apay wallet agents allocate <id> --amount 20000
apay wallet agents edit <id> --threshold 5000
apay wallet scheduled
apay wallet history --limit 25