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:

{
  "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:

{
  "user_id": "abcdef123456",
  "phone_number": "[phone]",
  "username": "johndoe",
  "email": "[email protected]",
  "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:

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

Delete Owner

• Path: /v2/owner

• Method: DELETE

• Access: Private API

• Response:

{
  "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:

[
  {
    "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):

{
  "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:

{
  "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:

{
  "message": "wallet updated successfully"
}

• Error Response:

{
  "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:

{
  "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:

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

• Error Response:

{
  "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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "message": "setting KMS successfully"
}

Call Contact Wallets

• Path: /v2/contact/wallets

• Method: GET

• Access: Signature API

• Description: Retrieves wallets associated with user contacts.

• Response:

[
  {
    "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:

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

• Response (201 Created):

{
  "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:

{
  "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:

{
  "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):

{
  "message": "funding task successful"
}

• If nothing was deleted:

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