diff --git a/bankr/SKILL.md b/bankr/SKILL.md index c138db9b..1753c608 100644 --- a/bankr/SKILL.md +++ b/bankr/SKILL.md @@ -91,6 +91,9 @@ bankr login email --code --accept-terms --key-name "My Agent" # Example read-only, no LLM bankr login email --code --accept-terms --key-name "Research Bot" + +# Example with IP and recipient restrictions +bankr login email --code --accept-terms --key-name "Restricted Agent" --read-write --allowed-ips 1.2.3.4 --allowed-recipients 0xABC...,7xKXtg... ``` #### Login options reference @@ -102,6 +105,8 @@ bankr login email --code --accept-terms --key-name "Research | `--key-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 ` | Comma-separated IP allowlist — requests from other IPs will be blocked (e.g. `1.2.3.4,5.6.7.8`) | +| `--allowed-recipients ` | 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. @@ -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. @@ -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. diff --git a/bankr/references/safety.md b/bankr/references/safety.md index 7d4d199d..1798d3b4 100644 --- a/bankr/references/safety.md +++ b/bankr/references/safety.md @@ -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 @@ -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 { @@ -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 @@ -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 @@ -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