wapu 0.4.0

CLI for interacting with the WapuPay backend

Wapu CLI

Qué es

wapu-cli es una interfaz de línea de comandos para integrar depósitos por Lightning y retiros fiat desde herramientas, scripts y flujos automatizados. Está pensada para developers, operadores y equipos que quieran conectar productos sobre Bitcoin/Lightning con una experiencia real de entrada y salida para usuarios finales.

El problema que resuelve es reducir la fricción en la adopción de Lightning, permitiendo mover valor entre el ecosistema Lightning y moneda local de manera simple, programable y utilizable desde software. En ese sentido, el proyecto funciona como un puente para builders que ya están construyendo sobre Lightning/Bitcoin y necesitan una vía práctica de off-ramp para sus usuarios.

La propuesta se apoya directamente en Lightning como parte central del flujo:

• permite crear depósitos Lightning
• expone la Lightning Address del usuario para recibir fondos
• habilita automatización y operación desde terminal, scripts y agentes

Alcance y arquitectura

Este CLI consume el backend para resolver problemas que incluye operaciones con dinero fiat, ejecución de retiros, escrow entre el P2P y el usuario.

La idea del proyecto es ofrecer una interfaz simple y programable sobre ese flujo, de forma que nuevos productos puedan integrar depósitos Lightning y retiros ARS sin tener que reinventar la operación completa. Aportando valor en la experiencia de integración que habilita para el ecosistema Lightning.

Instalación

Instalación recomendada para uso normal:

uv tool install wapu

Luego puedes usar directamente:

wapu --help

También puedes correrlo de forma efímera sin instalarlo globalmente:

uvx wapu --help

Desarrollo local

Si quieres clonar el repositorio y trabajar sobre el código:

uv venv
uv sync --dev

Luego puedes usar:

uv run wapu --help
uv run python -m wapu_cli --help

Configuración

Precedencia de configuración:

1. flags del comando
2. variables de entorno
3. credenciales guardadas en ~/.config/wapu-cli/config.json

Variables soportadas:

• WAPU_API_BASE_URL
• WAPU_ACCESS_TOKEN
• WAPU_API_KEY

Backend de test por default:

https://be-prod.wapu.app

Auth

Guardar una API key:

wapu auth login --api-key '...'

Guardar un JWT:

wapu auth login --email [e-mail] --password '...'

Ver estado local:

wapu auth status

Borrar credenciales:

wapu auth logout

Comandos

Balance:

wapu balance

Crear depósito Lightning:

wapu deposit lightning create --amount 10 --currency SAT

Crear depósito on-chain:

wapu deposit crypto --amount 100 --currency USDT --network POLYGON

Obtener la Lightning address:

wapu deposit lightning address

Listar transacciones:

wapu tx list

Obtener una transacción:

wapu tx get 2b753493-687b-431f-8d85-f9b4cb99199e

Cancelar una transacción:

wapu tx cancel 2b753493-687b-431f-8d85-f9b4cb99199e

Cotizar monto tentativo:

wapu tx tentative-amount --amount 10000 --currency-payment ARS --currency-taken USDT --type fiat_transfer

Direct payment:

wapu tx direct-payment create \
  --amount-ars 25000 \
  --type fiat_transfer \
  --alias juan.perez.alias \
  --receiver-name 'Juan Perez' \
  --funding-method LIGHTNING \
  --network LIGHTNING

wapu tx direct-payment funding <tentative_uuid>

wapu tx direct-payment create-and-fund \
  --amount-ars 25000 \
  --type fast_fiat_transfer \
  --alias juan.perez.alias \
  --receiver-name 'Juan Perez' \
  --funding-method USDT \
  --network POLYGON

Follow-up del flujo direct payment:

# inspeccionar el depósito/funding emitido
wapu tx get <deposit_transaction_id>

# cuando ya tengas el executed_transaction_id (por ejemplo desde backend/local DB),
# inspeccionar la fiat transfer emitida
wapu tx get <executed_transaction_id>

Transferencia interna:

wapu tx inner-transfer --amount 10 --currency USDT --receiver-username johndoe

Crear retiro ARS:

wapu withdraw ars --type fiat_transfer --alias test.alias --amount 100 --receiver-name 'Test Receiver'
wapu withdraw ars --type fast_fiat_transfer --alias test.alias --amount 100

Crear retiro crypto:

wapu withdraw crypto --address TCZ7Gm6gmZhAFLLZWT12XwNLRwaWaxcVqA --network TRON --currency USDT --amount 25 --receiver-name 'Jane Doe'

Contactos:

wapu contacts list
wapu contacts list --filter-type favourite
wapu contacts favourite 1 --value true
wapu contacts delete 1

API token:

wapu api-token status

Usuario:

wapu user spending-limit
wapu user referral
wapu user referral --email [e-mail] --phone [phone]
wapu user profile get
wapu user profile update --username newusername --telegram my_telegram_handle
wapu user settings get
wapu user settings update --language ES --beta-version --favourite-currency ARS

Salida

Formatos:

wapu --json balance
wapu --yaml balance
wapu --output json balance
wapu --output yaml balance
wapu --output table tx list

Modo silencioso:

wapu --quiet balance

Tests

uv run pytest

Backend local / staging

Puedes apuntar el CLI a otro backend con --api-base-url o WAPU_API_BASE_URL:

wapu --api-base-url http://127.0.0.1:8000 auth login --email [e-mail] --password test
wapu --api-base-url http://127.0.0.1:8000 tx direct-payment create-and-fund ...

Smoke Test Manual

Para correr un smoke test real del CLI contra stage usando comandos uv run wapu ..., usa:

uv run python scripts/smoke_test_cli.py

La guía completa y las variables de entorno soportadas están en docs/smoke-test-cli.md.