# Events

## Overview

The Events API provides endpoints for interacting with blockchain events related to Ethos network activities. Currently, it allows for the specific processing of events associated with a given transaction hash.

## Endpoints

### Process Specific Transaction Events

```
GET /api/v1/events/process
```

**Description**: Processes the blockchain events associated with a specific transaction hash and returns the processing status and related data.

**Authentication Required**: Yes (Needs confirmation of exact requirements)

#### Parameters

**Query Parameters**

| Name     | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| `txHash` | string | Yes      | The transaction hash to process. |

**Path Parameters**

None

**Request Body**

None

#### Responses

**Success Response**

**Code**: 200 OK

```json
{
  "ok": true,
  "data": {
    "success": boolean,
    "transaction": { /* Viem TransactionReceipt object */ },
    "event": { /* Prisma BlockchainEvent object */ }
  }
}
```

| Property           | Type    | Description                                                                                   |
| ------------------ | ------- | --------------------------------------------------------------------------------------------- |
| `ok`               | boolean | Indicates if the API call itself was successful.                                              |
| `data`             | object  | Container for the response data.                                                              |
| `data.success`     | boolean | Indicates if the event processing for the given `txHash` was successful.                      |
| `data.transaction` | object  | The transaction receipt object (from Viem's `getTransactionReceipt`). Null if not found.      |
| `data.event`       | object  | The corresponding record from the `BlockchainEvent` table in the database. Null if not found. |

**Error Responses**

**Code**: 400 Bad Request

```json
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid transaction hash format"
    // ... potentially other validation fields
  }
}
```

**Code**: 401 Unauthorized

```json
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

**Code**: 500 Internal Server Error

```json
{
  "ok": false,
  "error": {
    "code": "PROCESSING_ERROR", // Or other specific error codes
    "message": "Failed to process events for transaction"
  }
}
```

#### Example

**Request**

```bash
# Needs authentication token and a valid txHash
# Example txHash (replace with a real one for testing)
TX_HASH="0x1234...abcd"
AUTH_TOKEN="your_auth_token"

http GET https://api.ethos.network/api/v1/events/process txHash==$TX_HASH "Authorization: Bearer $AUTH_TOKEN"
```

**Response**

```json
{
  "ok": true,
  "data": {
    "success": true,
    "transaction": {
      "blockHash": "0x76b595d5a5c0e7025c3c858c1fc1ef4f031eb9d1afd300d64f808b1fa9f99d96",
      "blockNumber": "28257388n",
      "contractAddress": null,
      "cumulativeGasUsed": "6482911n",
      "from": "0x532b2e0752Ec5c145509Ab586Da102a114C79Ac0",
      "gasUsed": "158304n",
      "logs": [/* array of log objects */],
      "logsBloom": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
      "status": "success",
      "to": "0x21b7db78940bd8e562e0d01f3ce847cd65e0e8e2",
      "transactionHash": "0x2fd09c99521be6ba1fc4b68d6003fe9c6e5c5981ce333690091bde7d2928b43c",
      "transactionIndex": 29
    },
    "event": {
      "id": 873453,
      "txHash": "0x2fd09c99521be6ba1fc4b68d6003fe9c6e5c5981ce333690091bde7d2928b43c",
      "blockNumber": 28257388,
      "blockIndex": 29,
      "contract": "attestation",
      "logData": "{\"eventName\":\"AttestationCreated\",\"args\":{\"profileId\":6179,\"account\":\"1395154870932541446\",\"service\":\"x.com\"}}",
      "processed": true,
      "jobCreated": true,
      "createdAt": "2023-03-30T10:42:05.000Z",
      "updatedAt": "2023-03-30T10:42:06.000Z"
    }
  }
}
```

#### Notes

* This endpoint allows forcing the processing of events for a specific transaction, bypassing the normal queue.
* Requires authentication (likely internal/admin).
* The `transaction` and `event` fields can be `null` if the transaction or corresponding event record are not found.
* The exact structure of the `transaction` (Viem Receipt) and `event` (Prisma Model) objects should be referenced for full details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.ethos.network/api-documentation/api-v1-deprecated/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.