> 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/key-custody.md).

# Key custody

## How keys are stored

1. On wallet creation, a Solana Ed25519 keypair is generated server-side using `tweetnacl`.
2. The 64-byte secret key is encrypted with **XChaCha20-Poly1305** (libsodium) using a master key held in our secrets vault.
3. The ciphertext + nonce are stored in Postgres. The plaintext is wiped from memory.
4. The public key is stored unencrypted (it's public).

## How keys are used

When a send is allowed by policy:

1. The encrypted secret is loaded from the DB.
2. Decrypted in-memory inside the server function for the wallet's owner.
3. A `VersionedTransaction` is built and signed.
4. Signed bytes are sent to a Solana RPC.
5. The plaintext secret goes out of scope and is garbage-collected.

The decrypted secret never:

* Leaves the server function's memory.
* Is logged.
* Is written to disk.
* Is returned in any HTTP response.

## Master key

The master encryption key is held in the platform's secrets vault, separate from the application database. Access requires both:

* Application code path (server function).
* Vault access (held by infra, not application code).

Rotating the master key re-wraps all secrets in a single migration.

## What you should still do

* Treat agent wallets as **hot wallets** — keep balances proportional to weekly spending.
* Use **policies** as your last line of defense, not custody assumptions.
* For very large balances, use a self-custodied multisig and let Black Sheep agents draw from a smaller hot wallet.

## BYO custody

For teams that require self-custody, contact us about BYO-key mode: you hold and sign with the key on your side; Black Sheep handles policy evaluation, approvals, audit, and webhooks but never sees the secret.


---

# 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/key-custody.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.