> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/http-apis/obox-api/owner-profile-and-wallet-management.md).

# Owner Profile and Wallet Management

### **Owner Profile Management**

These endpoints manages creation, retrieval, and updates to owner profiles linked to wallets and storage activities.

#### **Get Owner by Wallet ID**

* **Path:** `/v2/owner/wallet/:ID`
* **Method:** `GET`
* **Access:** CSRF API
* **Description:** Public profile fetch by wallet ID.
* **Path Params:** `ID` (string)
* **Response:**

```json
{
  "user_id": "abcdef123456",
  "username": "johndoe",
  "biography": "Short bio here",
  "avatar": "<base64>",
  "background": "<base64>",
  "created_at": "2024-05-30T12:34:00"
}
```

* **Error:** `{"error": "owner not found"}`

#### **Get Current Owner**

* **Path:** `/v2/owner`
* **Method:** `GET`
* **Access:** Signature API
* **Response:**

```json
{
  "user_id": "abcdef123456",
  "phone_number": "+1234567890",
  "username": "johndoe",
  "email": "john@example.com",
  "biography": "Short bio here",
  "avatar": "<base64>",
  "background": "<base64>",
  "created_at": "2024-05-30T12:34:00"
}
```

#### **Update Owner**

* **Path:** `/v2/owner`
* **Method:** `PUT`
* **Access:** Signature API
* **Form Data:**
  * `username` (optional)
  * `avatar` (optional file)
  * `background` (optional file)
  * `biography` (optional string)
* **Response:**

```json
{
  "message": "updated owner details successfully"
}
```

#### **Delete Owner**

* **Path:** `/v2/owner`
* **Method:** `DELETE`
* **Access:** Private API
* **Response:**

```json
{
  "message": "owner deleted successfully"
}
```

* Deletes: DB record, Elasticsearch index, Stripe subscriptions, Firebase account.

#### **Autocomplete Owners by Name**

* **Path:** `/v2/owner/autocomplete`
* **Method:** `GET`
* **Access:** Signature API
* **Query Parameters:**
  * `name` (required)
  * `app_type` (required)
  * `offset`, `limit`, `order` (optional)
* **Response:**

```json
[
  {
    "user_id": "abcdef123456",
    "username": "johndoe",
    "biography": "Short bio here",
    "avatar": "<base64>",
    "background": "<base64>",
    "created_at": "2024-05-30T12:34:00"
  }
]
```

### **Wallet Management**

These endpoints enables wallet creation, updates, and funding workflows essential for interacting with the Züs network.

#### **Create Wallet**

* **Path:** `/v2/wallet`
* **Method:** `POST`
* **Access:** Signature API
* **Description:**\
  Creates a new wallet for the authenticated user. Can optionally include a referral code and custom mnemonic.
* **Form Data (multipart/form-data):**
  * `name` (string, optional): Wallet name.
  * `description` (string, optional): Wallet description.
  * `mnemonic` (string, optional): Predefined mnemonic (if restoring).
  * `pub_encryption_key` (string, optional): Public encryption key.
  * `refcode` (string, optional): Referral code.
* **Response (201 Created):**

```json
{
  "client_id": "abcdef123456",
  "wallet_id": 123,
  "name": "My Wallet",
  "description": "Personal wallet",
  "mnemonic": "word1 word2 ...",
  "public_key": "abcdef...",
  "last_update": "2024-06-01T12:00:00",
  "referral_success": false
}
```

* **Error Response:**

```json
{
  "error": "owner not found"
}
```

#### **Update Wallet**

* **Path:** `/v2/wallet`
* **Method:** `PUT`
* **Access:** Signature API
* **Description:**\
  Updates metadata for an existing wallet.
* **Form Data:**
  * Any wallet metadata fields from `handler.WalletDetails` such as:
    * `name`, `description`, `pub_encryption_key`, etc.
* **Response:**

```json
{
  "message": "wallet updated successfully"
}
```

* **Error Response:**

```json
{
  "error": "wallet not found"
}
```

#### **Delete Wallet**

* **Path:** `/v2/wallet`
* **Method:** `DELETE`
* **Access:** Signature API
* **Description:**\
  Deletes a wallet for the authenticated user.
* **Query Parameters:**
  * `wallet_id` (string, required): ID of wallet to be deleted.
* **Response:**

```json
{
  "message": "wallet deleted successfully"
}
```

#### **Set Active Wallet**

* **Path:** `/v2/wallet`
* **Method:** `PUT`
* **Access:** Signature API
* **Description:**\
  Sets the currently active wallet for an app type (e.g., Vult/Blimp).\
  Also updates the user's profile and rewards signup tokens if first-time setup.
* **Form Data (multipart/form-data):**
  * `refcode` (string, optional): Referral code for reward.
* **Response:**

```json
{
  "owner_id": 123,
  "wallet_id": "abcdef123456",
  "app_type": "vult",
  "kms_public_key": "kms_pub_key_value"
}
```

* **Error Response:**

```json
{
  "error": "Cannot switch wallet"
}
```

#### **Get Wallet Keys**

* **Path:** `/v2/wallet/keys`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Retrieves public keys and metadata of the currently active wallet.
* **Response:**

```json
{
  "client_id": "abcdef123456",
  "wallet_id": 123,
  "name": "My Wallet",
  "public_key": "abcdef..."
}
```

#### **Check Wallet Exists**

* **Path:** `/v2/wallet/exist`
* **Method:** `GET`
* **Access:** CSRF API
* **Headers:** Non-auth headers required
* **Description:**\
  Checks whether a wallet already exists for the user.
* **Response:**

```json
{
  "field": "wallet",
  "exists": true
}
```

#### **Get Wallet List**

* **Path:** `/v2/wallet/list`
* **Method:** `GET`
* **Access:** CSRF API
* **Headers:** Non-auth headers required
* **Query Parameters (optional):**
  * `limit` (string)
  * `offset` (string)
* **Response:**

```json
[
  {
    "client_id": "abcdef123456",
    "wallet_id": 123,
    "name": "My Wallet",
    "public_key": "abcdef..."
  }
]
```

#### **Get Active Wallet**

* **Path:** `/v2/wallet/list` *(Overloaded)*
* **Method:** `GET`
* **Access:** CSRF API
* **Description:**\
  Fetches the currently active wallet for the logged-in user.
* **Response:**

```json
{
  "owner_id": "abcdef123456",
  "wallet_id": 123,
  "kms_public_key": "abcdef...",
  "app_type": "vult"
}
```

#### **Update KMS Keys**

* **Path:** `/v2/wallet/kms`
* **Method:** `PUT`
* **Access:** Signature API
* **Description:**\
  Updates the KMS (Key Management Service) public key for encryption purposes.
* **Form Data (multipart/form-data):**
  * Fields from `handler.WalletKMSDetails`, e.g.:
    * `kms_public_key`, etc.
* **Response:**

```json
{
  "message": "setting KMS successfully"
}
```

#### **Call Contact Wallets**

* **Path:** `/v2/contact/wallets`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Retrieves wallets associated with user contacts.
* **Response:**

```json
[
  {
    "name": "abcdef123456",
    "phone_number": "walletid1",
    "pub_encryption_key": "johndoe",
    "client_id": "vult"
  }
]
```

### **Wallet Funding Tasks (ZBOX)**

These endpoints allow users to receive initial funding (one-time) to perform actions like creating allocations.

#### **Create Funding Task Wallet**

* **Path:** `/zbox/fund/wallet`
* **Method:** `POST`
* **Access:** Signature API
* **Description:**\
  Creates a new funding task for a wallet. This enables one-time token funding per owner/app type for bootstrapping usage.
* **Headers Required:**\
  `X-App-Client-ID`, `X-App-Client-Key`, `X-App-Timestamp`, `X-App-ID-TOKEN`, `X-App-Phone-Number`, `X-CSRF-TOKEN`, `X-APP-TYPE`
* **Body:**

```json
{
  "client_id": "abcdef123456",
  "description": "Initial funding for allocation"
}
```

* **Response (201 Created):**

```json
{
  "id": 1,
  "client_id": "abcdef123456",
  "owner_id": 123,
  "amount": 100000000,
  "checkout_session": null,
  "description": "Initial funding for allocation",
  "funded": false,
  "tx_done": false,
  "tx_hash": "",
  "app_type": "vult",
  "funding_type": "allocation",
  "cool_down": 0
}
```

#### **Get Funding Task**

* **Path:** `/v2/zbox/fund/:ID`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Retrieves a specific funding task using its ID.
* **Path Param:** `ID` (integer)
* **Response:**

```json
{
  "id": 1,
  "client_id": "abcdef123456",
  "owner_id": 123,
  "amount": 100000000,
  "checkout_session": null,
  "description": "Initial funding for allocation",
  "funded": false,
  "tx_done": false,
  "tx_hash": "",
  "app_type": "vult",
  "funding_type": "allocation",
  "cool_down": 0
}
```

#### **Get Wallet Spending Status**

* **Path:** `/v2/zbox/fund/spent/status`
* **Method:** `GET`
* **Access:** Signature API
* **Description:**\
  Returns wallet’s current spending usage stats (daily/weekly) to prevent abuse.
* **Response:**

```json
{
  "owner_id": 123,
  "daily_spent": 50000000,
  "weekly_spent": 200000000,
  "app_type": "vult"
}
```

#### **Delete Funding Task**

* **Path:** `/v2/zbox/fund/:ID`
* **Method:** `DELETE`
* **Access:** Signature API
* **Description:**\
  Deletes a previously created funding task.
* **Path Param:** `ID` (integer)
* **Response (Success):**

```json
{
  "message": "funding task successful"
}
```

* **If nothing was deleted:**

```json
{
  "message": "no funding task was deleted for these details"
}
```