docs(bankr): W19 weekly skill update

bankr/SKILL.md

@@ -507,6 +507,17 @@ bankr llm setup claude                     # Print Claude Code env vars
 bankr llm claude                           # Launch Claude Code through gateway
 ```
 
+### Agent Credit Top-Up
+
+The AI agent can top up your LLM credits directly in conversation — no CLI or web dashboard needed:
+
+```bash
+bankr agent prompt "Top up my LLM credits with $25"
+bankr agent prompt "Add $10 of LLM credits using my ETH"
+```
+
+1 credit = $1 USD. Paid in USDC on Base by default; any other Base ERC-20 token you hold is auto-swapped to USDC at checkout. Maximum $1,000 per top-up.
+
 ### Model Deprecation
 
 The gateway supports model deprecation with auto-redirect to replacement models. Deprecated models return `X-Model-Deprecated` and `X-Model-Replacement` response headers. Hard-deprecated models return HTTP 410 — update your model ID to the replacement indicated in the header.
@@ -662,14 +673,47 @@ The agent has a built-in headless browser for web interactions:
 
 ## Safety & Access Control
 
-**Dedicated Agent Wallet**: When building autonomous agents, create a separate Bankr account rather than using your personal wallet. This isolates agent funds — if a key is compromised, only the agent wallet is exposed. Fund it with limited amounts and replenish as needed.
+Bankr has two independent layers of safety controls. A transaction must satisfy **both** to broadcast.
+
+### Wallet-Level Security (bankr.bot → Security)
+
+User-controlled settings that apply to every surface — chat, agent, API, CLI. Configured at [bankr.bot](https://bankr.bot) → Security; requires web authentication (an API key cannot change them).
+
+| Control | Default | Effect |
+|---------|---------|--------|
+| Pause all transactions | Off | Blocks every outbound transaction until unpaused |
+| Daily spending limit | $500 / 24h | Rejects any tx that pushes rolling-24h USD outflow past the limit |
+| Per-transaction limit | $500 | Rejects any single tx priced above the limit |
+| Permitted recipients | Off | Restricts transfers/swaps to an allowlist; new entries enter a configurable cooldown (default 24h) |
+| Disable arbitrary contract calls | Off | Blocks `write_contract`, raw `/wallet/submit`, and arbitrary transaction tools (named operations like swaps still work) |
+
+If USD pricing is unavailable and a limit is enabled, the transaction is **rejected** (fail-closed) rather than waved through. Your own wallet addresses are always implicitly allowed as recipients.
+
+### API-Key Level Controls (bankr.bot/api)
+
+Per-key settings configured at [bankr.bot/api](https://bankr.bot/api):
 
 **API Key Types**: Bankr uses a single key format (`bk_...`) with capability flags (`walletApiEnabled`, `agentApiEnabled`, `tokenLaunchApiEnabled`, `llmGatewayEnabled`). You can optionally configure a separate LLM Gateway key via `bankr config set llmKey` or `BANKR_LLM_KEY` — useful when you want independent revocation or different permissions for agent vs LLM access.
 
 **Read-Only API Keys**: New keys default to `readOnly: true`. This filters all write tools (swaps, transfers, staking, token launches, etc.) from agent sessions. The `/wallet/sign`, `/wallet/submit`, and `/wallet/transfer` write endpoints return 403. Use `--read-write` during login or toggle in the web settings to disable. Ideal for monitoring bots and research agents.
 
 **IP Whitelisting**: Set `allowedIps` on your API key to restrict usage to specific IPs or CIDR ranges (e.g., `10.0.0.0/24`). Requests from non-whitelisted IPs are rejected with 403 at the auth layer.
 
+**Recipient Allowlist**: Restrict which addresses the key can send funds to. Independent from the wallet-level permitted recipients — when both are configured, both must pass.
+
+### Incident Response
+
+If you suspect a key is compromised:
+
+1. **Pause** the wallet at [bankr.bot](https://bankr.bot) → Security — halts every outbound transaction immediately
+2. **Revoke** the key at [bankr.bot/api](https://bankr.bot/api)
+3. **Rotate** — generate a new key and update deployments
+4. **Audit** — review recent transactions and agent job history before unpausing
+
+### General
+
+**Dedicated Agent Wallet**: When building autonomous agents, create a separate Bankr account rather than using your personal wallet. This isolates agent funds — if a key is compromised, only the agent wallet is exposed. Fund it with limited amounts and replenish as needed.
+
 **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.
 
 **Key safety rules:**
@@ -921,6 +965,12 @@ See [references/safety.md](references/safety.md) for comprehensive safety guidan
 - "Deploy a token called BankrFan with symbol BFAN on Base"
 - "Claim fees for my token MTK"
 
+### LLM Credits
+
+- "Top up my LLM credits with $25"
+- "Add $50 of LLM credits"
+- "Top up LLM credits using my ETH"
+
 ### x402 Paid API Calls
 
 - "Find x402 endpoints for sentiment analysis"

bankr/references/llm-gateway.md

@@ -97,6 +97,17 @@ bankr llm credits auto --disable
 
 When credits are exhausted, gateway requests will fail with HTTP 402.
 
+### Agent Credit Top-Up
+
+The AI agent can also top up credits directly in conversation:
+
+```bash
+bankr agent prompt "Top up my LLM credits with $25"
+bankr agent prompt "Add $10 of LLM credits using my ETH"
+```
+
+1 credit = $1 USD. Paid in USDC on Base by default; any other Base ERC-20 token you hold is auto-swapped to USDC at checkout. Maximum $1,000 per top-up.
+
 > **LLM credits vs trading wallet:** These are completely separate balances on the same account and API key. Your trading wallet (ETH, SOL, USDC) is for on-chain transactions. LLM credits (USD) are for gateway API calls. Having crypto does NOT give you LLM credits.
 
 ## LLM Gateway Setup

bankr/references/safety.md

@@ -1,6 +1,52 @@
 # Safety & Access Control Reference
 
-Comprehensive safety guidance for building agents and integrations with the Bankr API and CLI. Covers API key types, access controls, wallet separation, rate limits, and operational best practices.
+Comprehensive safety guidance for building agents and integrations with the Bankr API and CLI. Covers wallet-level security settings, API key access controls, wallet separation, rate limits, and operational best practices.
+
+Bankr has two independent layers of safety controls: **wallet-level** (configured at [bankr.bot](https://bankr.bot) → Security; applies to every surface) and **per-API-key** (configured at [bankr.bot/api](https://bankr.bot/api); applies to one key). Both run independently — a transaction must satisfy both to broadcast.
+
+## Wallet-Level Security Settings
+
+User-controlled wallet safety features configured at [bankr.bot](https://bankr.bot) → Security. These apply to every surface — chat, agent, API, CLI — because they are enforced at the transaction broadcast chokepoint. Modifying them requires web (Privy) authentication; an API key cannot change them.
+
+### Controls
+
+| Control | Default | Effect |
+|---------|---------|--------|
+| Pause all transactions | Off | Blocks every outbound transaction until unpaused |
+| Daily spending limit | $500 / 24h | Rejects any tx that pushes rolling-24h USD outflow past the limit |
+| Per-transaction limit | $500 | Rejects any single tx priced above the limit |
+| Permitted recipients | Off | Restricts transfers/swaps to an allowlist; new entries enter a configurable cooldown |
+| Disable arbitrary contract calls | Off | Blocks `write_contract`, raw `/wallet/submit`, and arbitrary transaction tools (named operations like swaps still work) |
+
+USD limits accept `1` to `1,000,000`. Setting `0` is rejected — disable the limit instead. Cooldown accepts `0` to `168` hours (default 24h).
+
+### Pricing & Fail-Closed Behavior
+
+Bankr prices each transaction at submission time using on-chain quotes (0x for EVM, Jupiter for Solana). If pricing is unavailable and a USD limit is enabled, the transaction is **rejected** rather than waved through. Disable the limit if you need to proceed unpriced.
+
+### Recipient Cooldown
+
+Newly-added entries on the permitted-recipients list wait the configured cooldown (default 24h) before they're usable. Re-adding a previously-removed recipient restarts the cooldown. Your own EVM and Solana addresses are always implicitly allowed.
+
+### Spend Tracking
+
+Successful transactions are recorded in a per-wallet spend log, idempotent on transaction hash, so retries can't inflate the daily counter.
+
+### Relationship to API-Key Controls
+
+The wallet-level permitted-recipients list is independent from the API-key `allowedRecipients`. When both are configured, both must pass:
+
+- **API-key allowlist** = where this key is allowed to send
+- **Wallet allowlist** = where this wallet is allowed to send, regardless of key
+
+### Incident Response
+
+If you suspect a key is compromised:
+
+1. **Pause** the wallet at [bankr.bot](https://bankr.bot) → Security. Halts every outbound transaction immediately, including in-flight broadcasts. Revoking the key alone does not stop transactions already past auth.
+2. **Revoke** the key at [bankr.bot/api](https://bankr.bot/api).
+3. **Rotate** — generate a new key with the same access profile and update deployments.
+4. **Audit** — review recent transactions and agent job history before unpausing.
 
 ## API Key Types & Separation
 
@@ -211,12 +257,13 @@ 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 | Recipient Allowlist | Wallet Daily Limit |
+|----------|----------|------------|---------------------|-------------------|
+| Monitoring / analytics bot | Yes | Yes (server IP) | — | — |
+| Trading bot (server-side) | No | Yes (server IP) | Yes | Yes ($500–$5,000) |
+| Public-facing demo | Yes | No | — | — |
+| Development / testing | No | No | No | Yes ($100) |
+| Read-only research agent | Yes | No | — | — |
 
 ## Rate Limits
 
@@ -307,6 +354,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
+- [ ] Review **wallet-level security settings** at [bankr.bot](https://bankr.bot) → Security — set appropriate daily and per-transaction USD limits
+- [ ] Enable **permitted recipients** with cooldown if the agent sends to a known set of addresses
 - [ ] Set API key to **read-only** if the agent only needs to query data
 - [ ] Configure **IP whitelisting** for server-side agents with known IPs
 - [ ] Store keys in **environment variables** (`BANKR_API_KEY`, `BANKR_LLM_KEY`), never in source code or version control
@@ -317,3 +366,4 @@ Before deploying an agent or integration:
 - [ ] Implement **error handling** for rate limits (429) and access control errors (403)
 - [ ] Monitor the agent's **daily message usage** against your tier limit
 - [ ] Review and **rotate all keys** (API and LLM) periodically; revoke immediately if compromised
+- [ ] Know the **incident response** procedure: pause wallet → revoke key → rotate → audit