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

[
    {
        "_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.