# Accounts SDK

> The @somnia-chain/accounts-sdk documentation: tutorials, how-to guides, reference and explanation.

This page is the map of the `@somnia-chain/accounts-sdk` documentation. The pages are grouped by
what you need right now: to learn, to finish a task, to look something up, or to understand a
design.

**Every TypeScript example on every page is compiled against the published API, and the ones making
a claim about a result are executed.** `scripts/generate-doc-examples.mjs` lifts each fenced `ts`
block into a module that `pnpm typecheck` compiles; a block marked `<!-- docexample: run -->` becomes
a real test instead, where every `// => value` you see in the prose is an assertion. CI fails if a
document drifts from either.

That second tier exists because compiling is not the same as being true: a page once claimed a
function returned `undefined` where it returns a value, and the example compiled perfectly. Anything
chain-free that asserts a result is now checked against the implementation on every run.

The tutorials need a funded testnet key; they are type-correct but have not been executed for you.

## Start here

Two lessons take you from an empty directory to acting from a sub-account on Somnia testnet. Follow
them in order. Each takes about 15 minutes.

1. [Create your first account](./tutorials/create-your-first-account). Derive an address offline,
   create the account and grant a session key with one signature, then act with no signature at all.
2. [Act from a sub-account](./tutorials/act-from-a-sub-account). An account owned by an account:
   create it, fund it, and sign through the parent to empty it.

## Do a task

Goal-shaped guides for a developer who already knows what they want.

- [Drive this SDK from another SDK](./how-to/integrate-with-another-sdk) — the executor adapter,
  and the five things to get right at that seam
- [Create accounts on every chain](./how-to/create-accounts-on-every-chain) — one signature, all
  three networks
- [Act without a signature](./how-to/act-without-a-signature) — the pre-validated path
- [Grant and revoke a session key](./how-to/grant-and-revoke-a-session-key)
- [Sponsor a transaction](./how-to/sponsor-a-transaction) — when a relayer pays
- [Sign with a browser wallet](./how-to/sign-with-a-browser-wallet)
- [Find an account](./how-to/find-an-account) — scanning, owner sets, the ownership graph
- [Use the indexer](./how-to/use-the-indexer) — the reverse lookup, history, and saying when
  the answer is old
- [Move funds between accounts](./how-to/move-funds-between-accounts)
- [Check an account is healthy](./how-to/check-an-account-is-healthy)
- [Handle errors and reverts](./how-to/handle-errors-and-reverts)

## Look something up

Neutral descriptions of the machinery. Facts, defaults and constraints, without instruction.

- [Addresses and chains](./reference/addresses-and-chains) — coverage, contract names, salt
  versions, and what an unsupported chain does
- [Account derivation](./reference/account-derivation) — the formula, and what follows from it
- [Account authorization](./reference/authorization) — the chain-agnostic EIP-712 surface, field
  by field
- [Gas](./reference/gas) — the limits, the floors, and why estimation does not work here
- [The call, and who may send it](./reference/the-call-and-who-may-send-it) — `Call` vs
  `SenderBoundCall`
- [Safe transactions](./reference/safe-transactions) — `SafeTx`, batching, hashing, the outer
  transaction, and the ABIs
- [Errors](./reference/errors) — every class, its fields, and Safe's own codes
- The API reference lists every function, type and constant, generated from the source. Build it
  with `pnpm --filter @somnia-chain/accounts-sdk docs`; it lands in `docs/api/` and is not
  committed.

## Understand the design

Discussion for reading away from the keyboard.

- [About the two-key model](./explanation/about-the-two-key-model) — what the owner/session split
  buys, and the fact that threshold 1 grants total authority
- [About accounts owning accounts](./explanation/about-accounts-owning-accounts) — why depth is
  cheap, and why only the acting account has a nonce
- [About data-first design](./explanation/about-data-first-design) — why there is no client
- [Architecture](./architecture) — module by module, the three seams, and every generated file's
  gate

## If you only read four things

The failures that cost the most time, in the order you will hit them:

1. **Gas cannot be estimated here, and the failure is silent.** [Gas](./reference/gas).
2. **A receipt is not a success.** Assert `receipt.status`; `submitCall` does it for you.
3. **`deployed: undefined` is not `deployed: false`.** An unanswered read rendered as "nothing
   there" shows a funded account as empty. [How to find an account](./how-to/find-an-account).
4. **A pre-validated call is valid from one address only.**
   [The call, and who may send it](./reference/the-call-and-who-may-send-it).

---

Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.