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": "+1234567890",
  "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"
}
PreviousObox APINextStorage Allocation Management

Last updated