> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/builder-guides/account-security-monitoring.md).

# Account security monitoring

Show users what can act on their Hyperliquid account, and alert them when a permission changes or money leaves.

On Hyperliquid, several things can act for an account besides its main key: API wallets, builder fee approvals and multi-sig signers. Each has a request that lists it, so an app can show the full picture and notice when it changes.

Wallets, trading apps and security tools usually need to:

* show which keys and apps can act on an account
* notice a new API wallet, builder approval or multi-sig change
* alert when money leaves an account

**What can act on an account**

| Question                                                         | Use                                                                                                                                                                                         |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Is this address a user, a sub-account, a vault or an API wallet? | [userRole](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/userrole.md)                                                                                                       |
| Which API wallets can trade for it, and when do they expire?     | [extraAgents](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/extraagents)                                                                                                    |
| Which apps can charge it a builder fee, and how much?            | [approvedBuilders](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/approvedbuilders), [maxBuilderFee](https://docs.hydromancer.xyz/readme/rest-api/delegations/maxbuilderfee) |
| Is it a multi-sig, and who signs?                                | [userToMultiSigSigners](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/usertomultisigsigners)                                                                                |
| Which multi-sig accounts does an address sign for?               | [multiSigsBySigner](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/multisigsbysigner)                                                                                        |

**Reading the answers**

[userRole](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/userrole) returns the `role` and, for a sub-account or an API wallet, the account behind it. A sub-account comes back as `subAccount` with its `master` address.

[extraAgents](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/extraagents) returns one row per named API wallet: its `name`, its `address` and `validUntil`, the expiry in milliseconds. The unnamed API wallet is in [webData3](https://docs.hydromancer.xyz/readme/rest-api/user-position-data/webdata3) as `agentAddress`, with `agentValidUntil`.

[approvedBuilders](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/approvedbuilders) returns the builder addresses the user has approved. For each one, [maxBuilderFee](https://docs.hydromancer.xyz/readme/rest-api/delegations/maxbuilderfee) returns the approved ceiling in tenths of a basis point, so `1000` means 1%.

[userToMultiSigSigners](https://docs.hydromancer.xyz/readme/rest-api/roles-and-agents/usertomultisigsigners) returns the signers in `authorizedUsers` and the number that must sign in `threshold`. It returns `null` when the address is not a multi-sig.

**Checking for changes**

Permission changes are not ledger events, so no deposit or transfer stream shows them. Request the items above on a schedule and compare each answer with the last one. A new row in `extraAgents`, a new address in `approvedBuilders` or a different signer list is what to show the user.

**Money leaving**

Subscribe to [userNonFundingLedgerEvents](https://docs.hydromancer.xyz/readme/websocket/user-data/usernonfundingledgerevents) for the addresses you protect. It streams withdrawals, sends, transfers and vault deposits as they happen.

Each event has an `eventType` (such as `Withdraw`, `Send` or `SpotTransfer`), the `user`, the `counterparty`, the `amount` and `token`, and a `role` of `sender` or `receiver`. Filter on `role` to keep the outgoing side.

[allUserNonFundingLedgerEvents](https://docs.hydromancer.xyz/readme/websocket/funding-and-deposits-data/allusernonfundingledgerevents) carries these events for every account. Builders can cover every user who approved their builder fee with [builderApprovedNonFundingLedgerEvents](https://docs.hydromancer.xyz/readme/websocket/builder-data/builderapprovednonfundingledgerevents); see [Monitor approved builder users](https://docs.hydromancer.xyz/readme/builder-guides/monitor-approved-builder-users).

Alert on a destination the account has not sent to before, not on every send.

**Putting it together**

1. When a user connects, load the five requests in the table and show the result on one screen.
2. Store the answers, and repeat the requests on a schedule to detect changes.
3. Subscribe to `userNonFundingLedgerEvents` for the user's address, and alert on outgoing events.
