> For the complete documentation index, see [llms.txt](https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/security/best-practices.md).

# Best practices

## API keys

* Store in a secret manager. Never commit to git, never use `VITE_*` / `NEXT_PUBLIC_*` env vars.
* Use a different key per environment (`dev`, `staging`, `prod`).
* Rotate quarterly, or immediately on any suspected leak.
* Audit `Dashboard → Security → API keys` for keys you don't recognize.

## Policies

* Start tight, loosen over time. It's painful to discover you were too loose only after a loss.
* Always set `max_tx_usdc` — even a high one. It's your last-resort circuit breaker.
* Use an `allowlist` whenever the set of valid recipients is known ahead of time.
* Re-review policies quarterly.

## Wallets

* One agent wallet per workflow. Don't share.
* Don't fund agents with more than \~1 week of their daily limit.
* Freeze wallets you're not using.

## Approvals

* Send `approval.pending` to a **channel**, not a person. People go on vacation.
* Have an on-call rotation with a 30-minute SLA on approvals.
* Require **two** approvers for any wallet that holds > $10k worth of USDC (set `approval_threshold` low and use the dashboard's dual-approval mode — roadmap).

## Webhooks

* Always verify HMAC signatures.
* Always check timestamp freshness (reject > 5 minutes old).
* Always deduplicate on `event_id`.
* Don't run business logic synchronously inside the webhook handler — enqueue and respond 2xx immediately.

## Monitoring

* Alert on `tx.blocked` — these often indicate misconfiguration or attempted abuse.
* Track spend rate per agent and alert on anomalies (e.g. 3× the trailing 7-day average).
* Subscribe to `approval.pending` age — if > 30 minutes, page on-call.

## Incident response

If a key leaks or a wallet behaves unexpectedly:

1. **Rotate the API key.** Dashboard → Developers → Rotate.
2. **Freeze the wallet.** Dashboard → Agents → Freeze.
3. **Audit recent activity.** Dashboard → Transactions, filter by wallet.
4. **Move remaining funds** to a treasury wallet you control.
5. Contact support with the request IDs from your logs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://black-sheep-finance.gitbook.io/black-sheep-finance-docs/security/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.