---
title: "Connect wallet (signup or recover)"
method: POST
path: "/v1/auth/wallet/connect"
tags: ["auth"]
---

# Connect wallet (signup or recover)

`POST /v1/auth/wallet/connect`

Connect a wallet to Grove by proving ownership via signature.

**New wallet**: Creates account + server wallet + EOA wallet and returns JWT.
**Existing wallet**: Regenerates the deterministic JWT and returns account details.

The JWT is deterministic: same signing_address + same JWT_SECRET = same token.

## Possible outcomes

| Case              | Result                                             | is_new_account |
|-------------------|----------------------------------------------------|----------------|
| New wallet        | Creates account, server wallet, returns new JWT     | true           |
| Existing account  | Returns existing JWT + account details              | false          |
| Invalid signature | 401 Unauthorized                                   | —              |

## Request body

- RecoverRequest — Wallet-based account ensure: recover existing OR create new account. Despite the "Recover" name, this model serves two purposes: - **Existing wallet**: Returns the existing account's JWT and details. - **Unknown wallet**: Creates a new account via wallet-based native signup (claim-then-provision pattern) and returns is_new_account=True. The client proves wallet ownership by signing a deterministic message.
  - `signing_address` string, required
  - `signature` string, required
  - `message` string, required
  - `referral_code` string, nullable
  - `network` string, nullable

## Response `200`

Successful Response

- RecoverResponse — Response from wallet-based account ensure (recovery or creation). Returned by POST /auth/recover for both existing and new accounts. The is_new_account flag distinguishes the two cases.
  - `account_id` string, required
  - `api_key` 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)
  - `metadata` object, nullable
  - `is_new_account` boolean
  - `referral_code` string, required
  - `referred_by_account_id` string, nullable
  - `eoa_wallet_required` boolean — True when the account has no EOA wallet and must complete one-time wallet provisioning.
  - `onchain_address` string, 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)