agentis-pay 0.1.3

# agentis-pay

## Install

### Managed installer (recommended)

Use the managed installer for the best CLI experience. This is the default install path for users and AI agents, and it is the only install mode we intend to auto-update silently.

```bash
curl -fsSL https://agentispay.com/install.sh | sh
```

Optional flags:

```bash
curl -fsSL https://agentispay.com/install.sh | sh -s -- --bin-dir ~/.local/bin
curl -fsSL https://agentispay.com/install.sh | sh -s -- --version v0.1.1
```

The managed installer places a stable launcher in `~/.local/bin/agentis-pay` by default and keeps managed payloads under `~/.agentis-pay/`.

### Alternative install methods

#### Cargo

```bash
cargo install agentis-pay
```

#### Build from source

```bash
./scripts/install-agentis-pay.sh
```

Options for the source-build installer:

- `--bin-dir` to change the binary destination (default: `~/.local/bin`).

## Usage

Discover available commands with:

```bash
agentis-pay --help
agentis-pay pay --help
```

Example commands:

```bash
agentis-pay signup --email user@example.com --cpf 123.456.78901 --phone "+55 (11) 99999 0000"
agentis-pay pay --key 12345678901 --amount 12,34 --note "coffee"
agentis-pay pay --key 12345678901 --amount-cents 1234 --note "coffee"
agentis-pay keys
agentis-pay history --limit 10
```

## MCP

Install and run the local MCP server:

```bash
agentis-pay login
agentis-pay mcp install --client claude
```

The generated JSON can be pasted directly into Claude Desktop config.
For local MCP clients, `agentis-pay mcp serve` automatically reuses the session already saved by the CLI. Sensitive session material is stored in the OS-native credential store (Keychain on macOS, Credential Manager on Windows, native keyring on Linux when available), while non-sensitive metadata remains in `~/.agentis-pay/credentials.json`. When `mcp install` writes Claude Desktop config, it uses an atomic write and restricts file permissions on Unix systems.

For container/server deployments, set `AGENTIS_PAY_SERVER_MODE=true` and inject runtime credentials via environment variables (for example from Kubernetes Secrets synchronized from Google Secret Manager). In server mode, `mcp serve` does not read `credentials.json` and does not initialize the native keyring.

For local agents, prefer the managed installer so the CLI can stay on the supported update path.

The local MCP server currently exposes these agent-facing tools:

- `agentispay_whoami`
- `agentispay_account`
- `agentispay_balance`
- `agentispay_history` (supports `id?` and `limit?`)
- `agentispay_brcode_decode`
- `agentispay_deposit`
- `agentispay_pix_keys`
- `agentispay_limits`
- `agentispay_pay` (and alias `agentispay_pix_send`)

Host/bootstrap commands such as `login`, `verify`, `logout`, `mcp serve`, and `mcp install` remain CLI-only.
Trust-related tools are intentionally omitted from MCP for now.

Most local agents should use the saved-login flow above and avoid embedding JWTs in config files. If you must pre-seed a config snippet with a token, prefer `agentis-pay mcp install --jwt-file /path/to/token` or `agentis-pay mcp install --jwt-stdin` over passing secrets on the command line. For advanced runtime cases, MCP still supports explicit env overrides:

```bash
AGENTIS_PAY_OUTPUT=json \
AGENTIS_PAY_JWT=<token> \
AGENTIS_PAY_AGENT_NAME=<name> \
AGENTIS_PAY_DEVICE_ID=<device-id> \
agentis-pay mcp serve --stdio
```

For non-interactive server deployments, prefer env-only auth and include refresh metadata so the process can renew tokens in memory without touching local files:

```bash
AGENTIS_PAY_SERVER_MODE=true \
AGENTIS_PAY_OUTPUT=json \
AGENTIS_PAY_JWT=<token> \
AGENTIS_PAY_REFRESH_TOKEN=<refresh-token> \
AGENTIS_PAY_JWT_EXPIRES_AT=<unix-seconds> \
AGENTIS_PAY_AGENT_NAME=<name> \
AGENTIS_PAY_DEVICE_ID=<stable-device-id> \
agentis-pay mcp serve --stdio
```

Include a `request_id` and optional `idempotency_key` for production-safe retries:

```json
{
  "name": "agentispay_pay",
  "arguments": {
    "key": "alice@pix",
    "amount_cents": 1250,
    "request_id": "request-123e4567",
    "idempotency_key": "idem-123e4567"
  }
}
```

`agentispay_pay` returns the transfer result:

```json
{
  "request_id": "request-123e4567",
  "status": "paid",
  "key": "alice@pix",
  "owner_name": "Alice Cooper",
  "key_type": "pix",
  "amount_cents": 1250,
  "amount_brl": "R$ 12.50",
  "note": ""
}
```