---
title: "Retrieve account metadata and cached balances"
method: GET
path: "/v1/account"
tags: ["account"]
---

# Retrieve account metadata and cached balances

`GET /v1/account`

Get a snapshot of the authenticated account, including:

- `account_id`: Grove account ID bound to the JWT.
- `tipping_address`: The Grove-managed custodial wallet address (for sending tips).
- `earning_address`: The user's canonical earning wallet (ERC-4337 Smart Account).
- `smart_account_address`: Alias of the canonical earning Smart Account address.
- `network`: The VM type for this account (e.g., "base-sepolia" for EVM).
- `metadata`: Arbitrary key/value metadata (currently unvalidated).
- `balances`: Cached balances across networks/tokens (no provider refresh).
- `referral_code`: This account's shareable referral code (e.g., "GRV-ABC123").
- `referred_by_account_id`: Account ID of who referred this user (if any).
- `referral_count`: Number of accounts this user has referred.

Authentication: `Authorization: Bearer <CLIENT_JWT>`

Notes:
- Balances are returned from the database cache by default.
- Pass `resync=true` to trigger a background balance resync from on-chain.
- Metadata structure is TBD; today it is returned as-is.

## Query parameters

- `resync` boolean — Force a fresh balance sync from on-chain. Use for onramp flows where balances may have changed externally.

## Headers

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

## 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/revisions/f286b48a8105/schema)