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

# Standard Events

> Shared Event Bridge contracts every miniapp and host app can implement

Standard events are [Event Bridge](https://boxo.mintlify.site/host-apps/CES.md) event types with a fixed payload and fixed behaviour. A host app implements a standard flow once, and it works with every miniapp that supports it, with no per-miniapp integration work.

> **[Refunds](https://boxo.mintlify.site/events/refunds.md)**
>
> Refund a host app payment from a miniapp and track it until it is final.

## How standard events work

**1. The sender sends the event**

The sender posts the event to the Event Bridge API: `POST /api/v1/events/miniapp/` from a miniapp, or `POST /api/v1/events/hostapp/` from a host app.

**2. The receiver acknowledges it**

The Boxo Platform forwards the event to the receiver's Event Receiver endpoint. The receiver stores the event and responds `200` with an empty body `{}` straight away.

**3. The receiver processes it**

Processing happens asynchronously and can take as long as the underlying operation needs.

**4. The result comes back as its own event**

When the result is known, the receiver sends it back as a separate standard event to the original sender's Event Receiver. Results never come back in the HTTP response.

## Conventions

Every standard event follows the same rules.

| Rule | Example |
| - | - |
| Event types are lowercase `snake_case` | `refund_request` |
| Enum values, such as states, are lowercase `snake_case` and case-sensitive, like the platform payment statuses | `completed` |
| Ids are generated by the sender and act as idempotency keys | `refund_id` |
| Amounts are strings with 2 decimals, together with an ISO 4217 `currency` | `"25.00"`, `"USD"` |
| Timestamps are ISO 8601 in UTC | `"2026-08-21T14:31:05Z"` |
| Receivers always respond `200` with `{}` | `{}` |
| Final states are terminal and never change | `completed` |

> [!WARNING]
>
> Process every standard event idempotently. The Boxo Platform may deliver an event more than once, and a sender may resend an event after a timeout. Use the id in the payload, for example `refund_id`, to detect repeats.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.