Bipa CLI

There are two paths to create a Bipa account:

Step 1: Register via web (agent can guide this)

Direct the user to https://bipa.app/cadastro — Bipa's web KYC flow. Walk them through it:

1. CPF — Enter their CPF (Brazilian tax ID, 11 digits). This starts the registration.
2. Terms — Accept Bipa's terms of service and privacy policy.
3. Email — Enter email, then verify with a 6-digit PIN sent to that email.
4. Phone — Enter phone number (Brazilian +55), then verify with a 6-digit PIN via SMS.
5. Occupation — Select occupation from a list.
6. Income — Declare monthly income range.
7. PEP — Declare if they are a politically exposed person (most people: "No").
8. Address — Enter CEP (postal code), the system auto-fills street/district. Add number + complement.
9. Document verification — Scan a QR code on their phone to take a selfie + photo of their ID document (RG or CNH). Bipa uses automated KYC verification.
10. Processing — Account is reviewed (usually approved within minutes).

Requirements:

• Valid Brazilian CPF
• Brazilian phone number (+55)
• Valid email address
• Brazilian residential address
• ID document (RG or CNH)

Step 2: Wait for approval

The user receives an email when their account is approved. They can also check by revisiting https://bipa.app/cadastro — the page reflects the current status.

Step 3: Activate the account in the Bipa app

This step requires the mobile app — it cannot be done on the web. The user must:

1. Download the Bipa app
   • iOS: https://apps.apple.com/br/app/bipa/id1560985113
   • Android: https://play.google.com/store/apps/details?id=app.bipa
2. Log in using the same phone number or email they registered with. Bipa sends a PIN to verify.
3. Verify their identity via liveness check (face authentication) to activate the new device.
4. Complete in-app onboarding:
   • Create a Bipa Tag — a unique username (like @joao) used as their identity on Bipa and for Lightning payments.
   • Set a security PIN — a numeric PIN for additional transaction security.
   • Create their first Pix key — this registers a Pix key (CPF, email, or phone) with the Central Bank so they can receive Pix transfers.

Once onboarding is complete, the account is fully active. The user can now receive Pix, buy/sell Bitcoin, and use all Bipa features.

Step 4: Connect to Bipa CLI

Now the user can log in to Bipa CLI and connect their agent. After this, they only need to open the Bipa app to approve or reject payments requested by their agent — everything else is automated.

If they DO have an account → proceed to install & login

Install Bipa CLI

# Managed installer (recommended for users and agents)
curl -fsSL https://agents.bipa.app/install.sh | sh

Authenticate

Login now requires an explicit method flag:

# OAuth login — prints URL for agent-friendly workflows
bipa login --web

# OAuth login — opens browser automatically (human-friendly)
bipa login --web --open

# PIN-based login via email (two-step)
bipa login --pin --email [email protected]
bipa verify <PIN>

# PIN-based login via phone
bipa login --pin --phone "+55 11 99999 0000"
bipa verify <PIN>

Running bipa login without flags prints a usage summary.

For agents: prefer --web (prints the auth URL to stdout so you can present it to the user). For humans at the keyboard: use --web --open.

Check session status

bipa whoami          # human-readable
bipa whoami -f json  # includes expires_at, expires_in_seconds, auth_method

Set Up MCP for Claude Desktop

bipa mcp install --client claude
# Restart Claude Desktop to pick up the change

The MCP server reuses saved credentials. No tokens in config files.

Remote MCP is also available at https://mcp.bipa.app/mcp with automatic OAuth 2.1 (for Claude.ai, ChatGPT, Cursor, VS Code, and other remote-capable clients).

MCP Tools

CLI Commands

bipa pix pay --key <PIX_KEY> --amount <BRL> --agent-message "reason" [--note "memo"]
bipa pix pay --key <PIX_KEY> --amount-cents <CENTS> --agent-message "reason"
bipa pix pay --brcode <COPIA_E_COLA> [--amount <BRL>] --agent-message "reason"
bipa pix pay --trusted-contact <ID> --amount <BRL> --agent-message "reason"
bipa pix pay --recipient <ID> --amount <BRL> --agent-message "reason"
bipa pix balance
bipa pix history [--limit N] [TRANSACTION_ID]
bipa pix brcode <BRCODE_STRING>
bipa pix keys
bipa pix deposit
bipa pix limits
bipa pix recipient-suggestions
bipa pix trusted-contacts
bipa pix account
bipa whoami
bipa login --web [--open]
bipa logout
bipa skill

Pix Key Types

Recipients are identified by Pix keys. The tool normalizes these automatically:

• CPF: 123.456.789-00 → 12345678900
• CNPJ: 12.345.678/0001-99 → digits only
• Phone: +55 (11) 99999-9999 → +5511999999999
• Email: [email protected] → as-is
• EVP (random key): UUID like 550e8400-e29b-41d4-a716-446655440000

Pass the key in any common format — normalization is handled internally.

Critical Rules

1. Check saved recipients first. When the user asks to pay someone by name, always call bipa_pix_recipient_suggestions first. If the person is in the list, use bipa_pix_pay_recipient — it's faster and avoids Pix key lookup. Only fall back to bipa_pix_pay_key (with a Pix key) when no saved recipient matches.

2. bipa_pix_pay_key includes recipient lookup. bipa_pix_pay_key resolves the recipient automatically. Never try to look up a Pix key separately before paying.

3. agent_message is required for every payment. This text is shown to the human in the Bipa app during the approval step. Write a clear, honest explanation of why the agent is making this payment (e.g., "User asked me to pay João R$20 for lunch"). Payments without agent_message are rejected.

4. Payments require human approval. After calling bipa_pix_pay_key or bipa_pix_pay_recipient, the payment enters awaiting_approval status. The user must approve it in the Bipa mobile app via biometric (Face ID / Touch ID). Exception: trusted contact payments (bipa_pix_pay_trusted_contact) skip approval and settle immediately. Always inform the user and suggest checking bipa_history later.

5. Amounts. MCP takes amount_cents (integer, must be > 0). CLI takes --amount in BRL (e.g., 12.34 or 12,34) or --amount-cents. "R$50" = amount_cents: 5000.

6. Idempotency is automatic. The system generates unique keys internally. No need to pass request_id or idempotency_key.

7. Never search Pix keys without payment intent. Only resolve keys when the user explicitly wants to pay.

Workflows

Pay Someone by Pix Key

User: "Pay [email protected] R$20 for lunch"

MCP:

{
  "name": "bipa_pix_pay_key",
  "arguments": {
    "key": "[email protected]",
    "amount_cents": 2000,
    "note": "lunch",
    "agent_message": "User asked me to pay João R$20 for lunch"
  }
}

Response:

{
  "status": "awaiting_approval",
  "key": "[email protected]",
  "owner_name": "João Silva",
  "amount_brl": "R$ 20.00",
  "note": "lunch",
  "message": "Payment submitted. The user must approve this operation in the Bipa app. Use bipa_history to check the transaction status."
}

Tell the user: "I've submitted the R$20 payment to João Silva. Please approve it in the Bipa app."

CLI:

bipa pix pay --key [email protected] --amount 20 --note "lunch" --agent-message "Paying João for lunch"

Pay a QR Code / Copia e Cola

Preferred: use bipa_pix_pay_brcode (preview + transfer in one call):

{
  "name": "bipa_pix_pay_brcode",
  "arguments": {
    "brcode": "<COPIA_E_COLA>",
    "agent_message": "Paying invoice from QR code"
  }
}

For fixed-amount codes, amount_cents is optional (taken from the code). For custom-amount codes, pass amount_cents.

Preview first (when you need to show details before paying):

1. bipa_pix_brcode_preview with the raw string → returns name, document_masked, total_value_cents, kind (dynamic/static), amount_type (fixed/custom)
2. Show the user: recipient name, masked document, and amount
3. bipa_pix_pay_brcode with the same brcode and agent_message

CLI:

bipa pix pay --brcode "<COPIA_E_COLA>" --agent-message "Paying invoice from QR code"
bipa pix pay --brcode "<COPIA_E_COLA>" --amount 50 --agent-message "Custom amount payment"

Offline decode (no auth needed):

• bipa_pix_brcode_decode parses the TLV structure locally without server contact

Pay a Trusted Contact

Trusted contacts are pre-approved recipients — no Pix key lookup needed, and payment skips biometric approval.

1. bipa_pix_trusted_contacts → list all enabled contacts with id, name, document_masked, limit_cents, and bank details
2. Find the right contact and confirm with the user
3. bipa_pix_pay_trusted_contact with pix_trusted_contact_id, amount_cents, and agent_message

MCP:

{
  "name": "bipa_pix_trusted_contacts",
  "arguments": {}
}

{
  "name": "bipa_pix_pay_trusted_contact",
  "arguments": {
    "pix_trusted_contact_id": 42,
    "amount_cents": 5000,
    "agent_message": "User asked to pay Maria R$50 — trusted contact"
  }
}

Pay a Saved Recipient (Preferred for Repeat Payments)

When the user asks to pay someone by name (not by Pix key), check their saved recipients first. This is faster than a Pix key lookup and covers most "pay X" requests.

1. bipa_pix_recipient_suggestions → returns the user's top 10 most frequent/recent PIX recipients
2. Match by name or bank_name — confirm with the user ("Is this João at Nubank?")
3. bipa_pix_pay_recipient with the recipient's id (as pix_payment_recipient_id), amount_cents, and agent_message

If no match is found in the suggestions list, fall back to bipa_pix_pay_key with the user's Pix key.

MCP:

{
  "name": "bipa_pix_recipient_suggestions",
  "arguments": {}
}

{
  "name": "bipa_pix_pay_recipient",
  "arguments": {
    "pix_payment_recipient_id": 42,
    "amount_cents": 2000,
    "agent_message": "User asked to pay João R$20 for lunch — saved recipient"
  }
}

CLI:

bipa pix recipient-suggestions
bipa pix pay --recipient 42 --amount 20 --agent-message "Paying João for lunch"

Pay by BIPA Tag

BIPA tags are user nicknames starting with $ (e.g. $bipatag).

1. bipa_pix_tag_preview → confirm recipient name, masked CPF
2. bipa_pix_pay_tag with tag, amount_cents, and agent_message

MCP:

{
  "name": "bipa_pix_pay_tag",
  "arguments": {
    "tag": "$bipatag",
    "amount_cents": 1000,
    "agent_message": "User asked to send R$10 to $bipatag"
  }
}

Financial Snapshot

1. bipa_balance → available_cents
2. bipa_history (limit: 20) → recent transactions with direction (credit/debit), amounts, counterparty names, timestamps (BRT)

Present a clean summary: balance in R$, last transactions grouped by direction.

Detect Recurring / Duplicate Transactions

1. bipa_history with limit: 50 (maximum)
2. Group by counterparty name and direction
3. Flag same-counterparty + same-amount entries

Check Limits Before Large Transfers

bipa_limits returns daily_limit_cents, nightly_limit_cents, and reset timeframes. Present these before big payments so the user knows if it'll go through.

Error Handling

Transaction Statuses

• awaiting_approval — waiting for user approval in Bipa app
• scheduled — approved, queued for settlement
• succeeded / confirmed — settled
• pending — in progress
• failed — transfer failed
• created — initial state

Key Facts

• All amounts in BRL. MCP uses cents (integer). CLI accepts BRL decimals and cents.
• Transactions show credit (in) and debit (out) directions.
• Timestamps in BRT (UTC-3).
• Rate limits: 5 payments/min, 20 brcode decodes/min.
• Credentials stored in OS keychain (macOS Keychain, Windows Credential Manager).
• Transaction details include structured sections with labeled fields for full receipt info.
• Bipa CLI currently supports Pix. Bitcoin, stablecoins (USDC/USDT), and Lightning are coming soon via the same Bipa infrastructure.