# max-banking

Adopt this skill: https://proskills.md/skills/other/appmaxbrasil-openclaw-max-banking-skill

Page: https://proskills.md/skills/other/appmaxbrasil-openclaw-max-banking-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8182
upstream: https://github.com/appmaxbrasil/openclaw-max-banking-skill/blob/HEAD/SKILL.md

````text
---
name: max-banking
description: "Operacoes financeiras da conta Max Bank via MCP. Use quando o usuario pedir saldo, fazer PIX (chave ou QR copia e cola), pagar boleto, conectar conta Max, ou enviar codigos PIX (00020...), linhas digitaveis de boleto ou imagens de QR/codigo de barras."
homepage: https://github.com/appmaxbrasil/openclaw-max-banking-skill
metadata: {"openclaw":{"requires":{"bins":["mcporter","node"]},"install":[{"id":"mcporter","kind":"node","package":"mcporter","bins":["mcporter"],"label":"Install mcporter (npm)"}]}}
---

# Max Banking Skill

**Reconhecimento Proativo:** Se o usuário enviar APENAS um código começando com 000201... (PIX Copia e Cola), uma linha cheia de números (Boleto), **ou fizer o upload de uma imagem/foto**, NÃO pergunte o que ele quer fazer. 
- Se for texto: Assuma a intenção de pagamento e inicie o Workflow 2 ou 3.
- Se for imagem: Assuma que é um QR Code ou Boleto. VOCÊ TEM A CAPACIDADE de ler essa imagem. Imediatamente use a tool `exec` executando `zbarimg -q --raw CAMINHO_DA_IMAGEM` para extrair o código e, em seguida, siga com o pagamento. Nunca tente ler os números da imagem apenas olhando para ela; confie exclusivamente no retorno do `zbarimg`.

## REGRA #1 — PROIBIDO CONFIRMAR APÓS EXECUÇÃO (prioridade máxima)

**Os comandos `pix` e `billet` criam pagamentos REAIS no backend no instante em que o script roda.** Não existe simulação, rascunho ou prévia. Se o script rodou e retornou sucesso, o pagamento JÁ FOI CRIADO.

**Após qualquer execução bem-sucedida de `pix` ou `billet`:**

1. O pagamento JÁ EXISTE no sistema. Trate como FATO CONSUMADO.
2. Use APENAS verbos no passado: "registrei", "foi criado", "seu pedido foi gerado".
3. Oriente o usuário a APROVAR no WhatsApp ou no app (prazo de 48h).

**LISTA DE FRASES PROIBIDAS após execução bem-sucedida (nunca use nenhuma delas):**
- "deseja confirmar?"
- "confirma o pagamento?"
- "você gostaria de confirmar?"
- "posso prosseguir?"
- "posso efetuar?"
- "está pronto para ser pago"
- "você está prestes a pagar"
- "gostaria de prosseguir?"
- "quer que eu efetue?"
- Qualquer pergunta sim/não sobre o pagamento que já foi executado

**Se o usuário responder "sim" após você já ter informado o sucesso:** NÃO execute novamente. Responda: "O pedido já foi criado! Falta apenas aprovar no WhatsApp ou no app."

**Violação desta regra causa pagamento duplicado e prejuízo financeiro ao usuário.**

---

## REGRA #2 — PROIBIDO INVENTAR VALOR (prioridade máxima)

**Nunca execute `pix` sem que o usuário tenha informado EXPLICITAMENTE o valor na conversa.** Valores que aparecem em exemplos técnicos deste documento (como 150.00) são ilustrativos — **NUNCA** os use como valor real.

**Antes de executar `pix` por chave, verifique:**
1. O usuário informou a chave? Se não → pergunte.
2. O usuário informou o valor em reais **nesta conversa**? Se não → pergunte.
3. Os DOIS dados vieram do usuário? Só então execute.

**PROIBIDO:**
- Usar qualquer valor que não foi dito pelo usuário (0, 1, 5, 10, 50, 100, etc.)
- Inferir valor a partir de contexto, histórico ou exemplos
- Executar `pix` com valor "padrão", "mínimo" ou "sugerido"

**Se o usuário disser "PIX para email@exemplo.com" sem mencionar valor:** NÃO execute. Pergunte: "Qual o valor em reais?"

**Violação desta regra causa prejuízo financeiro ao usuário.**

---

## Regras de comunicação (obrigatórias)

- **Respostas curtas e objetivas.** Evite textos longos; vá direto ao ponto.
- **PROIBIDO exibir ao usuário:** comandos, exemplos de formato técnico, nomes de parâmetros, scripts, IDs ou qualquer sintaxe de código. A resposta ao usuário deve ser 100% em linguagem natural.
- **Coleta de dados:** pergunte de forma natural. Para **chave PIX** (e-mail, CPF, telefone, chave aleatória): chave e valor. Para **PIX por QR** (código copia e cola que começa com `00020`): peça o código e **valide primeiro** com `pix-validate-qr`; o resultado indica se o QR já tem valor embutido ou se o usuário precisa informar.
- Após executar, responda de forma amigável. Nunca exiba saída técnica ou IDs brutos.
- Trate o usuário como cliente final: linguagem simples, sem jargão.
- **Comando inexistente:** se o usuário pedir algo que não existe (ex: saque, extrato, cartão), responda com a lista de ações disponíveis: *saldo*, *conta conectada*, *PIX*, *boleto* ou *conectar conta*.
- **PIX e boleto:** colete o que a API exige antes de executar. **Chave PIX:** sem valor informado → pergunte o valor; nunca invente valor. **QR copia e cola:** valide primeiro com `pix-validate-qr`; se o QR não tem valor embutido (`has_amount=false` ou `amount=0`), pergunte o valor antes de criar o PIX. **Boleto:** só a linha/código.
- **Ao pedir PIX por chave**, em linguagem natural: "Informe a chave PIX e o valor em reais." (chave = CPF, e-mail, celular ou chave aleatória.) Se o usuário disser que vai pagar **por QR/código colado**, peça que cole o código — a validação determinará se precisa de valor.

## Quando usar

Quando o usuário pedir para consultar saldo, fazer PIX, pagar boleto, ou conectar/configurar a conta Max Bank.

## Como executar

Todas as ações usam a tool `exec`. O script principal é `scripts/maxbank.sh`, relativo ao diretório desta skill (onde este SKILL.md está).

> **Resolução de caminho (obrigatório):** Antes de chamar `exec`, resolva `scripts/maxbank.sh` contra o diretório desta skill para obter o **caminho absoluto**. Use esse caminho absoluto no comando. **Nunca** passe o texto literal `{baseDir}` ou um caminho relativo para o shell — isso causa "No such file or directory".

> Nunca tente adivinhar o caminho do bash (`/bin/bash`, `/usr/bin/bash`, etc.) — usar apenas `bash` funciona.

```bash
bash <resolved>/scripts/maxbank.sh ACAO [ARGUMENTOS]
```

(`<resolved>` = caminho absoluto do diretório desta skill, obtido antes de chamar exec)

Ações válidas: `saldo`, `conta`, `setup`, `pix-validate-qr`, `pix`, `billet`, `status`.
Aliases aceitos (funcionam mas prefira os nomes acima): `balance` (= saldo), `boleto` (= billet), `connect`/`conectar`/`configurar`/`instalar`/`auth`/`login` (= setup), `session`/`sessao`/`info`/`account` (= conta).
Ações que NÃO existem: pix-criar, extrato, saque, transferencia, cartao, investir.

**Regra crítica (uso interno da IA) — PIX:**

**SEMPRE use o formato POSICIONAL (argumentos separados por espaço). NUNCA misture posicional com nomeado.**

- **Chave PIX:** dois argumentos posicionais — `CHAVE` e `VALOR`.
- **QR copia e cola** (payload que começa com `00020`): **sempre validar primeiro** com `pix-validate-qr`, depois criar com `pix`. Se o QR não tem valor embutido, passe o valor como segundo argumento posicional.
- **QR com espaços no texto:** o EMV copia e cola pode conter espaços (ex.: nome fantasia, cidade). No `exec` com bash, o código inteiro deve ser **um único argumento** — use **aspas simples** em volta do payload. Sem aspas, o shell quebra o código em várias palavras e a validação ou o PIX falham.

```bash
# PIX por chave (posicional: CHAVE VALOR) — VALOR vem do usuário, nunca inventar
bash <resolved>/scripts/maxbank.sh pix CHAVE VALOR

# Validar QR (aspas simples se houver espaços)
bash <resolved>/scripts/maxbank.sh pix-validate-qr 'CODIGO_QR_COMPLETO'

# PIX por QR com valor (posicional: CODIGO VALOR)
bash <resolved>/scripts/maxbank.sh pix 'CODIGO_QR_COMPLETO' VALOR

# PIX por QR sem valor adicional (QR já tem valor embutido)
bash <resolved>/scripts/maxbank.sh pix 'CODIGO_QR_COMPLETO'
```

**PROIBIDO:** `pix email@teste.com amount:VALOR` ou `pix code=email amount:VALOR` — misturar formatos causa erro de parsing.

**Validação de QR (`pix-validate-qr`):** retorna JSON com campos:
- `has_amount` — `true` se o QR tem valor embutido > 0
- `amount` — valor em reais do QR (0 se sem valor)
- `can_modify_final_amount` — `true` se o pagador pode/deve definir o valor
- `pix_key` — chave PIX de destino
- `qr_type` — tipo do QR
- `expiration_date` — validade do QR (quando existir)

**Boleto — um único argumento para a API:** a tool `
````

## File: README.md
upstream: https://github.com/appmaxbrasil/openclaw-max-banking-skill/blob/HEAD/README.md

````text
# MaxBank Skill para OpenClaw

[![CodeQL](https://github.com/appmaxbrasil/openclaw-max-banking-skill/actions/workflows/codeql.yml/badge.svg)](https://github.com/appmaxbrasil/openclaw-max-banking-skill/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/appmaxbrasil/openclaw-max-banking-skill/badge)](https://securityscorecards.dev/viewer/?uri=github.com/appmaxbrasil/openclaw-max-banking-skill)

Skill que conecta seu OpenClaw ao MaxBank para consultar saldo, fazer PIX e pagar boletos.

Toda a comunicação é via **MCP** (Model Context Protocol). O MCP roda hospedado — a autenticação (Agent API Key) é injetada diretamente via header no mcporter, sem necessidade de proxy local.

## Ambientes

| Ambiente | Uso | MCP URL |
|----------|-----|---------|
| **prod** | Produção (padrão) | `https://maxbank-mcp.max.com.br/mcp` |
| **homolog** | Validação | `https://mcp-homologacao.maxbank.ai/mcp` |
| **local** | Dev com ngrok | `https://seu-ngrok.ngrok-free.app/mcp` |

Health check do MCP em produção: [https://maxbank-mcp.max.com.br/health](https://maxbank-mcp.max.com.br/health).

## Funcionalidades

| Comando | Descrição |
|---------|-----------|
| `maxbank.sh saldo` | Consulta saldo da conta |
| `maxbank.sh conta` | Exibe dados da conta conectada |
| `maxbank.sh pix CHAVE VALOR` | Cria transferência PIX (chave, e-mail, telefone ou QR) |
| `maxbank.sh pix code=CHAVE amount:N` | PIX com formato nomeado |
| `maxbank.sh billet LINHA_DIGITAVEL` | Paga boleto pela linha digitável |
| `maxbank.sh billet code=LINHA_DIGITAVEL` | Boleto com formato nomeado |
| `maxbank.sh status` | Exibe status da configuração mcporter |
| `maxbank.sh setup <codigo> <env> [url]` | Conecta conta (pareamento + config) |

## Instalação

### Via git clone (recomendado enquanto não está no ClawHub)

```bash
# Clone direto no diretório de skills do OpenClaw
git clone https://github.com/appmaxbrasil/openclaw-max-banking-skill.git \
  ~/.openclaw/skills/max-banking

# Ou, se usar workspace:
git clone https://github.com/appmaxbrasil/openclaw-max-banking-skill.git \
  ~/.openclaw/workspace/skills/max-banking
```

Reinicie o gateway do OpenClaw após instalar.

### Via ClawHub (em breve)

```bash
clawhub install max-banking
```

## Setup (conectar conta)

O setup pode ser feito via chat ou manualmente:

### Via chat (recomendado)

Diga ao assistente: **"Quero conectar minha conta max, código AX7K-92QF"**

O assistente executa o setup completo: mcporter, pareamento e configuração do header de autenticação.

### Manual

```bash
# Prod (padrão)
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 prod

# Homolog
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 homolog

# Local (requer URL do ngrok)
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 local https://xxx.ngrok-free.app/mcp
```

O setup faz:
1. Instala/verifica mcporter
2. Configura `openclaw.json`
3. Pareia via MCP (tool `pairing_exchange`)
4. Configura mcporter com `Authorization: Bearer <agent_key>` no header

## Pagamentos

### PIX

Aceita formato posicional ou nomeado:

```bash
# Posicional: chave + valor
maxbank.sh pix email@exemplo.com 50.00
maxbank.sh pix 11999998888 100

# Nomeado
maxbank.sh pix code=email@exemplo.com amount:50.00

# QR Code (copia-e-cola)
maxbank.sh pix 00020126...
```

Chaves aceitas: e-mail, telefone (10-11 dígitos), CPF/CNPJ, EVP (aleatória) ou payload QR (começa com `00020`).

### Boleto

Aceita apenas a linha digitável (o valor é extraído automaticamente dela):

```bash
# Posicional
maxbank.sh billet 23793.38128 60000.000003 00000.000008 1 10250000012345

# Nomeado
maxbank.sh billet code="23793.38128 60000.000003 00000.000008 1 10250000012345"
```

> **Importante:** Não envie `amount` ou outros parâmetros para boleto — apenas `code` com a linha digitável completa.

## Arquitetura

```
Usuário → OpenClaw (LLM) → exec maxbank.sh → mcporter → MCP hospedado → Banking API
                                                ↑
                                     Authorization: Bearer <agent_key>
                                     (injetado via header no mcporter config)
```

### Arquivos

```
skills/max-banking/
├── SKILL.md                    # Instruções para a LLM
├── README.md                   # Este arquivo
└── scripts/
    ├── maxbank.sh              # Wrapper unificado (entry point)
    ├── setup.sh                # Setup: pareamento + config mcporter
    └── connect-mcp.js          # Pareamento via MCP JSON-RPC
```

### Armazenamento

Tokens e sessão ficam em `~/.openclaw/secrets/maxbank/` com permissões restritas:

| Arquivo | Conteúdo | Permissão |
|---------|----------|-----------|
| `agent_key` | Agent API Key (longa duração) | `600` |
| `session.json` | Ambiente, telefone, account_id, data de conexão | `600` |

### Configuração mcporter

Após o setup, o mcporter fica configurado assim (equivalente a `mcporter config list`):

```json
{
  "banking": {
    "type": "http",
    "url": "https://maxbank-mcp.max.com.br/mcp",
    "headers": {
      "Authorization": "Bearer max_live_..."
    }
  }
}
```

## Configuração do OpenClaw

O `setup.sh` configura automaticamente. Para referência manual:

```json
{
  "skills": {
    "entries": {
      "mcporter": { "enabled": true },
      "max-banking": { "enabled": true }
    }
  },
  "tools": {
    "allow": ["exec", "process", "read", "write", "edit", "apply_patch"],
    "exec": { "host": "gateway" }
  }
}
```

## Troubleshooting

**"pairing not done"** — Execute o setup com um código de pareamento válido.

**"agent_key invalid"** — Chave revogada ou inválida. Refaça o pareamento com um novo código.

**"servidor 'banking' não encontrado no mcporter"** — O mcporter perdeu a configuração. Execute `maxbank.sh setup` novamente ou reconfigure manualmente:
```bash
mcporter config add banking --http-url https://maxbank-mcp.max.com.br/mcp --header '{"Authorization": "Bearer <sua_agent_key>"}'
```

**Agente não reconhece comandos** — Verifique:
1. Skill está em `~/.openclaw/skills/max-banking/SKILL.md`
2. `openclaw.json` tem `max-banking` habilitada
3. Permissão `exec` está em `tools.allow`
4. Inicie uma nova sessão (`/new`) após alterar configurações

**BILLET_TOO_MANY_ARGS** — O boleto aceita apenas a linha digitável em `code=`. Não envie `amount=`, `description=` ou outros parâmetros extras.
````
