> For the complete documentation index, see [llms.txt](https://dipe.gitbook.io/dipe-protocol-on-dogecoin/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dipe.gitbook.io/dipe-protocol-on-dogecoin/api-endpoints/retrieve-address-events-utxos.md).

# Retrieve Address Events (UTXOs)

### Endpoint

`GET /api/events/address/{ADDRESS}`

### Description

This endpoint returns an array of objects, where each object represents a UTXO (Unspent Transaction Output) for the given address. Each UTXO corresponds to a token and its value. The 'action' field indicates the operation that created this UTXO.

### Parameters

* `{ADDRESS}`: The Dogecoin address to query (required)
* `page`: Page number for pagination (optional, default: 1)
* `limit`: Number of results per page (optional, default: 10)
* `isReceiverOnly`: Filter for receiving transactions only (optional, boolean)

### Example Request

```
GET https://dipe-chain-api-bf9e112f1ffc.herokuapp.com/api/events/address/DCAPHDbvxPQ5zsnKVg2wQteUNYFv1wiRqN?page=1&limit=10&isReceiverOnly=true
```

### Example Response

```json
[
    {
        "_id": "669dff583a2d0e10bb33c9c0",
        "action": "T",
        "time": 1721630515,
        "txId": "be8837b485f5ec749e4325f71393ad86144a37121ad43c1e605eaef1af148dc1",
        "sender": "D67BAkwuFva8M7ies2457Hh88wcsRfGD5v",
        "receiver": "DCAPHDbvxPQ5zsnKVg2wQteUNYFv1wiRqN",
        "total": 100,
        "token": "poge",
        "isValid": true,
        "index": 2,
        "__v": 0
    },
    // ... more UTXOs ...
]
```

### Response Fields

* `_id`: Unique identifier for the UTXO
* `action`: Type of action that created this UTXO. Possible values include:
  * `T`: Transfer (UTXO created from a transfer)
  * `M`: Mint (UTXO created from token minting)
  * `C`: Combine (UTXO created from merging multiple UTXOs of the same token, e.g., combining 10 and 5 poge into 15 poge)
  * `S`: Split (UTXO created from dividing a larger UTXO into smaller amounts, e.g., splitting 15 poge into 10 and 5 poge)
* `time`: Unix timestamp of the event
* `txId`: Transaction ID
* `sender`: Sending address
* `receiver`: Receiving address
* `total`: Value of this specific UTXO
* `token`: Token identifier for this UTXO
* `isValid`: Validity of the transaction
* `index`: Index of the transaction
* `__v`: Version key (internal use)

### UTXO Handling

* Each object in the response array represents a single UTXO.
* Multiple UTXOs can exist for the same token type.
* The `action` field provides context on how each UTXO was created, which can be useful for transaction history and auditing.
* 'Combine' actions merge multiple UTXOs of the same token into a single, larger UTXO.
* 'Split' actions divide a larger UTXO into multiple smaller UTXOs of the same token.
* To calculate the total balance for a specific token, sum the `total` values of all valid UTXOs with the same `token` identifier.

####