Payzor

Programmable money for AI agents — register agents, allocate capital, define spending rules, and monitor every transaction in real time.

Estructura del proyecto

payzor/
├── package.json          # scripts root (orquestador) + deps Express
├── server.js             # API REST (Express, puerto 3040 por defecto — ver `PORT` en `.env`)
├── payzor.js             # Engine core: agentes, políticas, Wompi
├── frontend/             # Frontend Next.js (puerto 3001) — evita conflicto con carpeta `web/`
│   ├── app/              # rutas: dashboard, /agents, /transactions, /settings
│   ├── components/       # UI (shadcn) + componentes payzor (sidebar, kpi, chart, feed)
│   └── lib/              # data layer + hooks (use-payzor.ts)
├── web/                  # shim: `npm run dev` aquí delega a `frontend/` (no hay `app/` en web)
├── DOCS.md               # documentación de producto
└── .env                  # **solo en tu máquina** — secretos (Wompi, DB, JWT, consola). No commitear

Crea en la raíz un archivo .env tú mismo (no hay plantilla en el repo) y, para la consola Next, un frontend/.env.local con el mismo PAYZOR_CONSOLE_TOKEN que en .env si usas el token de consola. Nunca subas esos archivos: ya están en .gitignore.

Para tu agente IA (CLI + skills)

Payzor expone una CLI (payzor) y un set de SKILL.md estilo Anthropic/OpenClaw para que cualquier agente compatible (Cursor, Claude Code, OpenClaw, custom) sepa cómo gastar, cobrar y transferir dentro de tus políticas.

Setup (5 segundos, sin npm publish)

# Hace `payzor` accesible globalmente (mientras no publiquemos a npm).
# Symlink — actualiza solo cuando edites el archivo, no necesita re-link.
ln -sf "$PWD/bin/payzor.mjs" /opt/homebrew/bin/payzor   # o /usr/local/bin con sudo
payzor --version

Una vez publicado a npm: npm install -g payzor o npx payzor … funcionan igual desde cualquier máquina.

Publicar a npm

El paquete publicado es slim: solo bin/ + skills/ + README.md, sin runtime deps. Tarball ≈ 17 KB, install ≈ 200 ms. Express/Postgres/Twilio/Playwright se quedan en este repo (dev/prod del backend), no viajan al registro.

# 1. Inspecciona qué se va a publicar (no toca el registro)
npm run publish:dry

# 2. Login en npm (una vez por máquina; abre tu navegador)
npm login

# 3. Publica — REQUIERE OTP de 6 dígitos si tu cuenta tiene 2FA
NPM_OTP=123456 npm run publish:cli
# o equivalentemente:
npm run publish:cli -- --otp 123456

El código OTP es el de 6 dígitos de tu Authenticator (Google Authenticator, Authy, 1Password, etc.). Sin él npm devuelve 403 Two-factor authentication … is required to publish packages. El OTP es válido ~30 s — pásalo y dale Enter rápido.

Notas:

• Tras publicar la primera vez, bumpea la versión antes del siguiente publish: npm version patch (también bumpea git tag si hay repo).
• El comando payzor server falla limpio en instalaciones npm (no incluye server.js) y dirige al usuario a clonar el repo o apuntar a un Payzor remoto vía PAYZOR_API_URL.
• Para CI sin 2FA interactivo: crea un granular access token en https://www.npmjs.com/settings/<tu-user>/tokens con la opción "Allow publishing without 2FA", ponlo en ~/.npmrc como //registry.npmjs.org/:_authToken=npm_… y omite --otp.

Flujo end-to-end (todo desde la CLI, verificado)

# 1. Arranca el server (in-memory: sin Postgres, sin nada)
payzor server --in-memory --port 3055 --detach

# 2. Crea un agente con saldo inicial y guarda sus credenciales
payzor agents create \
  --name shopper-bot \
  --initial-balance 5000000 \
  --api-url http://localhost:3055 \
  --login                                  # ← guarda la pz_sk_ devuelta

# 3. El agente IA ya puede operar:
payzor balance                                                                # saldo + política + estado
payzor policy show                                                            # solo política
payzor topup --amount 1000000                                                 # recargar (ledger interno)
payzor pay --amount 50000 --category shop --description "Hosting Vercel"      # ← Wompi
payzor collect --amount 250000 --description "Asesoría legal"                 # ← link Wompi
payzor transfer --to-agent agent_xxx --amount 50000 --description "Comisión"  # ← A2A, sin Wompi
payzor audit --filter TRANSFER --limit 10                                     # historial filtrado

# 4. Logout cuando termines
payzor auth logout

Discovery para LLMs

payzor --llms          # lista compacta — JSON consumible por un LLM
payzor --llms-full     # lista completa con todos los parámetros
payzor pay --schema    # JSON schema de un comando específico
payzor info            # GET /api de la instancia (versión, endpoints, auth notes)

Modo MCP (Cursor / Claude Code / Cline / Windsurf)

Payzor también es un servidor MCP zero-deps. Añádelo a tu .mcp.json y tu agente descubre los tools automáticamente:

{
  "mcpServers": {
    "payzor": {
      "command": "npx",
      "args": ["-y", "payzor", "mcp"],
      "env": {
        "PAYZOR_API_URL": "http://localhost:3040",
        "PAYZOR_API_KEY": "pz_sk_…",
        "PAYZOR_AGENT_ID": "agent_…"
      }
    }
  }
}

8 tools expuestos: payzor_balance, payzor_policy_show, payzor_pay, payzor_collect, payzor_transfer, payzor_topup, payzor_audit, payzor_auth_status. Cada uno con inputSchema JSON Schema autodescriptivo derivado del CLI.

Verifica con payzor mcp (lee JSON-RPC 2.0 por stdin, responde por stdout, logs por stderr — no rompe el protocolo).

Instalar los skills en tu proyecto

payzor init                       # autodetecta .cursor/, .claude/, o crea AGENTS.md
payzor init --target cursor       # forzar destino
payzor init --target agents-md    # bloque idempotente en AGENTS.md

Skills disponibles (en skills/):

| Skill | Para qué sirve | |---|---| | pay-with-payzor | Agente paga con políticas + rieles LatAm (Wompi/PSE/Nequi/Daviplata/Bre-B) | | collect-with-payzor | Agente genera link Wompi de cobro | | transfer-with-payzor | A2A — transferencia agente↔agente (sin Wompi en el medio) |

Ver skills/README.md para la comparativa con Stripe Link.

Variables de entorno

| Variable | Default | Para qué | |---|---|---| | PAYZOR_API_URL | http://localhost:3040 (o $PORT) | URL de la API contra la que opera la CLI | | PAYZOR_API_KEY | — | Override de la pz_sk_ guardada en ~/.payzor/credentials.json | | PAYZOR_AGENT_ID | — | Override del agentId guardado | | PAYZOR_CONSOLE_TOKEN | (de .env) | Para payzor agents create/list (rutas restringidas a consola) |

Endpoints principales (API)

| Método | Path | Descripción | |---|---|---| | GET | /health | health check | | GET | /dashboard | snapshot completo (kpis + agents + tx + volumen) | | GET | /agents | listar agentes | | POST | /agents | crear agente | | POST | /agents/:id/pay | ejecutar pago (con policy check) | | POST | /agents/:id/collect | generar link Wompi de cobro | | GET | /agents/:id/audit | audit trail del agente | | POST | /transfer | transferencia A2A |

Más detalle en DOCS.md.

Stack

Backend — Node.js + Express + Wompi (sandbox) Frontend — Next.js 16 + React 19 + Tailwind v4 + shadcn/ui + Recharts + SWR

Estado

Prototipo — v0.1. Para escalado a producción ver el roadmap en DOCS.md.