Skip to content

docs: add --allowed-ips and --allowed-recipients to bankr skill #257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sidrisov wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add --allowed-ips and --allowed-recipients to bankr skill #257

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions bankr/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,9 @@ bankr login email <user-email> --code <otp> --accept-terms --key-name "My Agent"

# Example read-only, no LLM
bankr login email <user-email> --code <otp> --accept-terms --key-name "Research Bot"

# Example with IP and recipient restrictions
bankr login email <user-email> --code <otp> --accept-terms --key-name "Restricted Agent" --read-write --allowed-ips 1.2.3.4 --allowed-recipients 0xABC...,7xKXtg...
```

#### Login options reference
Expand All @@ -102,6 +105,8 @@ bankr login email <user-email> --code <otp> --accept-terms --key-name "Research
| `--key-name <name>` | Display name for the API key (e.g. "My Agent"). Prompted if omitted |
| `--read-write` | Enable write operations: swaps, transfers, orders, token launches, leverage, Polymarket bets. **Without this flag, the key is read-only** (portfolio, balances, prices, research only) |
| `--llm` | Enable [LLM gateway](https://docs.bankr.bot/llm-gateway/overview) access (multi-model API at `llm.bankr.bot`). Currently limited to beta testers |
| `--allowed-ips <ips>` | Comma-separated IP allowlist — requests from other IPs will be blocked (e.g. `1.2.3.4,5.6.7.8`) |
| `--allowed-recipients <addresses>` | Comma-separated EVM/Solana addresses — agent will only send funds to these. Accepts mixed addresses; 0x-prefixed are classified as EVM, base58 as Solana (e.g. `0xABC...,7xKXtg...`) |

Any option not provided on the command line will be prompted interactively by the CLI, so you can mix headless and interactive as needed.

Expand Down Expand Up @@ -484,7 +489,9 @@ For full details — setup paths, model list, provider config, SDK examples, key

**Read-Only API Keys**: Keys with `readOnly: true` filter all write tools (swaps, transfers, staking, token launches, etc.) from agent sessions. The `/agent/sign` and `/agent/submit` endpoints return 403. Ideal for monitoring bots and research agents.

**IP Whitelisting**: Set `allowedIps` on your API key to restrict usage to specific IPs. Requests from non-whitelisted IPs are rejected with 403 at the auth layer.
**IP Whitelisting**: Set `allowedIps` on your API key to restrict usage to specific IPs. Requests from non-whitelisted IPs are rejected with 403 at the auth layer. Configure via CLI with `--allowed-ips` during login or at [bankr.bot/api](https://bankr.bot/api).

**Recipient Whitelisting**: Set `allowedRecipients` on your API key to restrict which addresses the agent can send funds to. Supports both EVM and Solana addresses. Configure via CLI with `--allowed-recipients` during login or at [bankr.bot/api](https://bankr.bot/api).

**Rate Limits**: 100 messages/day (standard), 1,000/day (Bankr Club), or custom per key. Resets 24h from first message (rolling window). LLM Gateway uses a credit-based system.

Expand Down Expand Up @@ -608,10 +615,11 @@ For comprehensive error troubleshooting, setup instructions, and debugging steps
1. Never share your API key or LLM key
2. Use a dedicated agent wallet with limited funds for autonomous agents
3. Use read-only API keys for monitoring and research-only agents
4. Set IP whitelisting for server-side agents with known IPs
5. Verify addresses before large transfers
6. Use stop losses for leverage trading
7. Store keys in environment variables, not source code — add `~/.bankr/` to `.gitignore`
4. Set IP whitelisting (`--allowed-ips`) for server-side agents with known IPs
5. Set recipient whitelisting (`--allowed-recipients`) to restrict where agents can send funds
6. Verify addresses before large transfers
7. Use stop losses for leverage trading
8. Store keys in environment variables, not source code — add `~/.bankr/` to `.gitignore`

See [references/safety.md](references/safety.md) for comprehensive safety guidance.

Expand Down
49 changes: 34 additions & 15 deletions bankr/references/safety.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ For full LLM Gateway setup details, see [llm-gateway.md](llm-gateway.md).

## API Key Access Control

Bankr API keys support granular access control configured at [bankr.bot/api](https://bankr.bot/api). Two key security features: **read-only mode** and **IP whitelisting**.
Bankr API keys support granular access control configured at [bankr.bot/api](https://bankr.bot/api) or via CLI flags during login. Three key security features: **read-only mode**, **IP whitelisting**, and **recipient whitelisting**.

### Read-Only API Keys

Expand Down Expand Up @@ -103,6 +103,11 @@ API keys support an `allowedIps` whitelist. When configured, requests from non-w
- **Empty array** (`[]`) = all IPs allowed (default)
- **Non-empty array** = only listed IPs can use the key

**Configure via CLI** during login (applies to both `email` and `siwe` flows):
```bash
bankr login email user@example.com --code 123456 --accept-terms --allowed-ips 1.2.3.4,5.6.7.8
```

**403 error response:**
```json
{
Expand All @@ -111,16 +116,29 @@ API keys support an `allowedIps` whitelist. When configured, requests from non-w
}
```

### Recipient Whitelisting

API keys support an `allowedRecipients` whitelist. When configured, the agent can only send funds to the listed addresses. Supports both EVM and Solana addresses in a structured format: `{ evm?: string[], solana?: string[] }`.

- **Not set** = agent can send to any address (default)
- **Set** = agent can only send funds to listed addresses

**Configure via CLI** during login — pass a comma-separated list of mixed addresses. The CLI auto-classifies by format (0x-prefixed → EVM, base58 → Solana):
```bash
bankr login email user@example.com --code 123456 --accept-terms --allowed-recipients 0xABC...,7xKXtg...
```

### Configuring Access Control

Manage API key settings at [bankr.bot/api](https://bankr.bot/api):
Manage API key settings at [bankr.bot/api](https://bankr.bot/api) or via CLI flags during `bankr login email` / `bankr login siwe`:

| Field | Type | Description |
|-------|------|-------------|
| `readOnly` | boolean | When true, only read tools are available |
| `allowedIps` | string[] | IP whitelist (empty = all allowed) |
| `agentApiEnabled` | boolean | Whether `/agent/*` endpoints are accessible |
| `llmGatewayEnabled` | boolean | Whether LLM Gateway endpoints are accessible |
| Field | Type | CLI Flag | Description |
|-------|------|----------|-------------|
| `readOnly` | boolean | `--read-write` (inverted) | When true, only read tools are available |
| `allowedIps` | string[] | `--allowed-ips` | IP whitelist (empty = all allowed) |
| `allowedRecipients` | `{ evm?: string[], solana?: string[] }` | `--allowed-recipients` | Recipient address whitelist |
| `agentApiEnabled` | boolean | — | Whether `/agent/*` endpoints are accessible |
| `llmGatewayEnabled` | boolean | `--llm` | Whether LLM Gateway endpoints are accessible |

## CLI Security

Expand Down Expand Up @@ -207,12 +225,12 @@ Replenish periodically rather than pre-loading large amounts.

Choose the right combination based on your agent's purpose:

| Use Case | readOnly | allowedIps | Funding Level |
|----------|----------|------------|---------------|
| Monitoring / analytics bot | Yes | Yes (server IP) | None needed |
| Trading bot (server-side) | No | Yes (server IP) | Limited trading capital |
| Development / testing | No | No | Minimal (test amounts) |
| Read-only research agent | Yes | No | None needed |
| Use Case | readOnly | allowedIps | allowedRecipients | Funding Level |
|----------|----------|------------|-------------------|---------------|
| Monitoring / analytics bot | Yes | Yes (server IP) | — | None needed |
| Trading bot (server-side) | No | Yes (server IP) | Yes (known wallets) | Limited trading capital |
| Development / testing | No | No | No | Minimal (test amounts) |
| Read-only research agent | Yes | No | — | None needed |

## Rate Limits

Expand Down Expand Up @@ -304,7 +322,8 @@ Before deploying an agent or integration:
- [ ] Use a **dedicated agent wallet** — not your personal account
- [ ] Fund the agent wallet with **limited amounts** appropriate to its purpose
- [ ] Set API key to **read-only** if the agent only needs to query data
- [ ] Configure **IP whitelisting** for server-side agents with known IPs
- [ ] Configure **IP whitelisting** (`--allowed-ips`) for server-side agents with known IPs
- [ ] Configure **recipient whitelisting** (`--allowed-recipients`) to restrict where agents can send funds
- [ ] Store keys in **environment variables** (`BANKR_API_KEY`, `BANKR_LLM_KEY`), never in source code or version control
- [ ] If using the CLI, ensure `~/.bankr/` is in `.gitignore` and has restricted file permissions
- [ ] Use **separate keys** for Agent API vs LLM Gateway if they need independent access controls or revocation
Expand Down