Wallets
The caller's own wallets: the list, one wallet by id, one by address, its
The caller's own wallets: the list, one wallet by id, one by address, its token balance, and its transaction history.
privy_get_wallet_by_address is the one to reach for when you hold an address
and not a wallet id. It still checks ownership, so an address that is not the
caller's answers the same not-found as one that is not on the chain.
privy_update_custom_metadata
Merge (shallow) the given `custom_metadata` keys into the authenticated Privy user's existing map. Hits `PATCH /v1/users/{user_id}/custom_metadata` (Privy's PATCH is a shallow merge, not a deep merge). Keys you pass are added or replaced; keys you do not pass are untouched. Pass `userId` to target a different user (and the call will 403 if it does not match the caller's). Returns the updated `User` object. Use this for incremental updates to the agent's per-user state — e.g. `privy_update_custom_metadata({ customMetadata: { lastSeenAt: Date.now() } })` on every chat turn. To overwrite the whole map, use `privy_set_custom_metadata` instead.
privy_list_my_wallets
List every wallet the authenticated user owns. Hits `GET /v1/wallets?user_id={callerDID}` (the `user_id` filter is set server-side from the auth context — callers cannot enumerate other users' wallets). Returns `{ data: PrivyWallet[], next_cursor: string | null }`. The list is cursor-paginated: pass the previous page's `next_cursor` as the `cursor` arg to fetch the next page. The tool is the right starting point for a `what wallets do I have?` view; for a single wallet by id, use `privy_get_wallet`; for an address lookup, use `privy_get_wallet_by_address`.