---
title: "Update account metadata"
method: POST
path: "/v1/account"
tags: ["account"]
---

# Update account metadata

`POST /v1/account`

Merge user-provided metadata into the account and return the updated snapshot.

Authentication: `Authorization: Bearer <CLIENT_JWT>`

Request body:
- `metadata` (object, optional): Arbitrary key/value pairs to merge. Existing keys are overwritten by new ones.

Notes / TODOs:
- Define allowed/reserved metadata keys and size limits before widening usage.
- Add email account support and determine how to integrate with other OAuth flows.

## Headers

- `authorization` string, nullable — Bearer JWT issued by Grove that identifies the account.

## Request body

- AccountUpdateRequest — Request model for updating account metadata.
  - `metadata` object, nullable

## Response `200`

Successful Response

- AccountGetResponse — Response model for account metadata and balances. Wallet architecture: - tipping_address: Server wallet (Grove-controlled, for sending tips) - earning_address: User's canonical earning wallet (Smart Account address) - smart_account_address: Alias of the canonical earning Smart Account address Balance fields: - balances: Legacy field - all balances across all wallets (for backwards compatibility) - wallet_balances: Per-wallet balance breakdown (tipping vs earning wallets)
  - `account_id` string, required
  - `tipping_address` string, required
  - `earning_address` string, nullable
  - `eoa_owner_address` string, nullable
  - `smart_account_address` string, nullable — ERC-4337 Smart Account address (the earning wallet)
  - `external_linked_wallets` string[] — External linked wallet addresses (profile references, non-earning)
  - `network` string, required
  - `metadata` object, nullable
  - `balances` AccountBalance[], required
    - `network` string, required
    - `token_symbol` string, required
    - `balance` string, required
    - `contract_address` string, nullable
  - `wallet_balances` WalletBalanceResponse[] — Per-wallet balance breakdown. Server wallet = tipping balance, others = earning balance.
    - `wallet_id` string, required — Wallet ID
    - `wallet_type` string, required — Wallet type: server (tipping), smart_account (earning), eoa_embedded (owner key), external_linked (profile)
    - `address` string, required — Wallet address
    - `network` string, required — Network (base, base-sepolia, etc.)
    - `is_earning_wallet` boolean, required — Whether this wallet can earn tips (true for smart_account wallets)
    - `smart_account_address` string, nullable — For eoa_embedded rows: the ERC-4337 Smart Account wrapping this EOA
    - `balances` AccountBalance[] — Token balances for this wallet address
      - `network` string, required
      - `token_symbol` string, required
      - `balance` string, required
      - `contract_address` string, nullable
    - `smart_account_balances` AccountBalance[] — Deprecated: Smart Account now has its own wallet row (wallet_type=smart_account). Always empty.
      - `network` string, required
      - `token_symbol` string, required
      - `balance` string, required
      - `contract_address` string, nullable
    - `owner_address` string, nullable, required
  - `handle` string, nullable
  - `referral_code` string, required
  - `referred_by_account_id` string, nullable
  - `referral_count` integer
  - `onboarding` OnboardingState — Onboarding funnel snapshot for an account. next_step: server-computed — first step in ``FunnelStep.ORDER`` whose completed_at is NULL and whose dismissed_until is either NULL or in the past. NULL when all_complete is True. all_complete: True iff every step has a completed_at set. Dismissal does not count as completion. Frontend should route / render based on next_step and NOT re-derive from step state client-side.
    - `next_step` string, nullable
    - `all_complete` boolean
    - `steps` object
  - `onchain_address` string, required
  - `embedded_wallet_address` string, nullable, required
  - `client_address` string, nullable, required
  - `earnings_wallet` EarningsWallet, required — Dual earnings-wallet representation (owner EOA + Smart Account).
    - `eoa_address` string, nullable — Owner EOA address (non-earning key)
    - `smart_account_address` string, nullable — Smart Account address used as canonical earning wallet
    - `earnings_address` string, nullable, required — Canonical earnings address for sender-path use.
  - `earnings_address` string, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/versions/f286b48a8105/schema)