> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bleepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Widget Events

> List widget events (state transitions) for a business.

`GET /api/v1/widgets/events`

Returns a paginated list of widget events that record every state transition in a deposit session's lifecycle. Each event has a type indicating what changed, and a payload with the full event data.

## Parameters

### Query

| Name               | Type      | Required | Description                                                           |
| ------------------ | --------- | -------- | --------------------------------------------------------------------- |
| `businessId`       | `string`  | Yes      | The business ID                                                       |
| `depositSessionId` | `string`  | No       | Filter by deposit session ID                                          |
| `widgetId`         | `string`  | No       | Filter by widget ID                                                   |
| `type`             | `string`  | No       | Filter by event type. See event types below                           |
| `status`           | `string`  | No       | Filter by event status: `PENDING`, `ENABLED`, `DISABLED`, `SUSPENDED` |
| `limit`            | `integer` | No       | Number of items (default 20, max 100)                                 |
| `offset`           | `integer` | No       | Pagination offset                                                     |
| `since`            | `integer` | No       | Unix timestamp (ms) -- return items created after this time           |
| `until`            | `integer` | No       | Unix timestamp (ms) -- return items created before this time          |

### Event types

| Type                | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| `deposit.created`   | A new deposit session was created                                            |
| `deposit.pending`   | A matching on-chain transaction was detected but not yet confirmed           |
| `deposit.confirmed` | The deposit has been confirmed on-chain                                      |
| `deposit.expired`   | The deposit session expired before a matching transaction was found          |
| `deposit.failed`    | The deposit could not be processed                                           |
| `deposit.underpaid` | The on-chain amount is less than the requested amount                        |
| `deposit.overpaid`  | The on-chain amount is more than the requested amount                        |
| `deposit.unmatched` | An on-chain transaction was detected but could not be matched to any session |

## Request example

```shell theme={null}
curl --request GET 'https://payments.bleepay.com/api/v1/widgets/events?businessId=biz_abc123&type=deposit.confirmed&since=1717200000000&limit=20' \
  --header 'Authorization: Bearer <business_token>'
```

## Response

### Response schema

| Field              | Type     | Description                                                 |
| ------------------ | -------- | ----------------------------------------------------------- |
| `id`               | `string` | Unique event identifier                                     |
| `businessId`       | `string` | The business ID                                             |
| `depositSessionId` | `string` | The deposit session ID                                      |
| `type`             | `string` | Event type (e.g. `deposit.created`)                         |
| `payload`          | `object` | Full event data specific to the event type                  |
| `status`           | `string` | Event status: `PENDING`, `ENABLED`, `DISABLED`, `SUSPENDED` |
| `createdAt`        | `string` | ISO 8601 creation timestamp                                 |
| `updatedAt`        | `string` | ISO 8601 last update timestamp                              |

### Example response

```json theme={null}
[
  {
    "id": "evt_abc123",
    "businessId": "biz_abc123",
    "depositSessionId": "dep_a1b2c3d4e5f6",
    "type": "deposit.confirmed",
    "payload": {
      "amount": "100",
      "currency": "USDC",
      "network": "polygon",
      "txid": "0x7a1b2c3d...",
      "srcAddress": "0xPayerWallet123..."
    },
    "status": "ENABLED",
    "createdAt": "2026-06-09T12:05:00.000Z",
    "updatedAt": "2026-06-09T12:05:00.000Z"
  }
]
```

### Error responses

| Status | Code                | Description                       |
| ------ | ------------------- | --------------------------------- |
| `401`  | `unauthorized`      | Missing or invalid authentication |
| `400`  | `validation_failed` | Invalid query parameters          |