diff --git a/bankr/SKILL.md b/bankr/SKILL.md index 8fad3253..6de9fbf7 100644 --- a/bankr/SKILL.md +++ b/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,7 +673,25 @@ 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. @@ -670,6 +699,21 @@ The agent has a built-in headless browser for web interactions: **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" diff --git a/bankr/references/llm-gateway.md b/bankr/references/llm-gateway.md index f49db64d..ba12ce3f 100644 --- a/bankr/references/llm-gateway.md +++ b/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 diff --git a/bankr/references/safety.md b/bankr/references/safety.md index 039b290e..748e934d 100644 --- a/bankr/references/safety.md +++ b/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