DEX State APIs and User Notifications

DEX State APIs

These endpoints manage a user’s participation or workflow stage within a DEX (Decentralized Exchange) lifecycle.

Create DEX State

• Path: /v2/dex/state

• Method: POST

• Access: Signature API

• Description: Initializes a DEX state record for the authenticated user, typically when beginning a DEX-related process or session.

• Body: Follows handler.DexState structure.

{
  "wallet_id": 12345,
  "stage": "active",
  "reference": "some-reference-string"
}

• Response (200 OK):

{
  "wallet_id": 12345,
  "stage": "active",
  "reference": "some-reference-string",
  "last_update": "2025-06-09T12:00:00"
}

Update DEX State

• Path: /v2/dex/state

• Method: PUT

• Access: Signature API

• Description: Updates the current stage or status of the DEX state. Typically used when moving from one process step to another.

• Body: handler.DexState

{
  "wallet_id": 12345,
  "stage": "completed",
  "reference": "updated-reference"
}

• Response:

{
  "message": "updating dex state successful"
}

• If no update occurred:

{
  "message": "no dex state was updated for these details"
}

Get DEX State

• Path: /v2/dex/state

• Method: GET

• Access: Signature API

• Description: Retrieves the current DEX state for the authenticated wallet.

• Response:

{
  "wallet_id": "abcdef123456",
  "stage": "active",
  "reference": "",
  "last_update": "2025-06-09T12:00:00"
}

Delete DEX State

• Path: /v2/dex/state

• Method: DELETE

• Access: Signature API

• Description: Deletes the DEX state for the authenticated user. This is typically used to reset or clear participation records.

• Response (Success):

{
  "message": "deleting dex state successful"
}

• If nothing was deleted:

{
  "message": "no dex state was deleted for these details"
}

---

User Notifications

These APIs allow users to retrieve and manage system notifications, such as share requests, updates, or alerts. Notifications are typically pushed over WebSocket but can be fetched via API for redundancy or polling.

Fetch Unread Notifications

• Path: /v2/user/notifications

• Method: GET

• Access: Signature API

• Description: Retrieves all unread notifications for the authenticated user.

• Response (200 OK):

[
  {
    "id": 1,
    "entity_id": "abcdef123456",        // The associated entity (e.g., user)
    "entity_type": "user",
    "title": "You have a new share request",
    "body": "body of notification",
    "read": false,
    "created_at": "2025-06-09T12:00:00",
    "updated_at": "2025-06-09T12:00:00",
    "client_id": "client_id_xyz",
    "app_type": "vult"
  }
]

Delete Notifications (Mark as Read)

• Path: /v2/user/notifications

• Method: DELETE

• Access: Signature API

• Description: Deletes all unread notifications (i.e., marks them as read) for the current user.

• Response (200 OK):

{
  "message": "notifications deleted successfully"
}