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 API NextStorage Allocation Management

Last updated 4 months ago