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

# Snippet Custom Metrics Integrations

> How to push metrics and power iOS widgets with Snippet.

Snippet lets developers push their own metrics and display them on iOS native widgets. This document explains the concepts, constraints, and high-level flow to integrate your service with Snippet.

#### Audience

* Engineers building services that publish custom metrics to Snippet
* Product teams planning how widgets map to their protocol data

#### High-level flow

1. Create an API key in the Snippet mobile app. This API key authenticates your backend-to-backend calls. (The app flow is not part of this public API; just ensure you have a valid key.)
2. Register a protocol using the API. One protocol maps to one widget. The protocol ID must be unique and becomes the widget identifier.
3. From your service, push metrics for that protocol at your desired cadence. If you provide a timestamp, it will be used as-is; otherwise the server snaps it to the top of the hour for consistency.
4. Users add your widget in the iOS app. The widget reads the latest metrics for your protocol ID.

#### Key concepts

* **Protocol**: A unique integration identified by an ID (slug). One protocol equals one widget.
* **Metric**: A numeric data point identified by an `id` with pattern `{protocolId}___{Label}`. Example: `awesome-dex___TVL` or `awesome-dex___REVENUE`.
* **Timestamp alignment**: If you provide a timestamp, it must be a valid ISO 8601 string and not more than 5 minutes in the future; when omitted, the server snaps it to the top of the hour (minutes/seconds/millis set to 0).
* **Ownership and visibility**:
  * Protocols registered via API keys are owned by that key. Widgets tied to private protocols will only expose data when the same API key is used in read requests.
  * Public protocols can be read without authentication.
* **Units**: Free-form. You can send any unit label (e.g., `USD`, `BTC`, `%`, `TPS`, or even `football_fields`). For best UX, keep units consistent across updates.
* **Labels**: For best widget display, keep the part after `___` to 16 characters or fewer.

#### Constraints you must follow

* Max 100 metrics per POST batch.
* `id` must follow `{protocolId}___{Label}`.
* Timestamps must be ISO 8601 strings in UTC (e.g., `2025-01-15T12:00:00Z`) and cannot be more than 5 minutes in the future.

#### Authentication

Use the API key from the mobile app in the `Authorization` header:

```http theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

Always use HTTPS and treat the key as a secret. If your protocol is private, include this header when reading metrics; otherwise, requests without a key will only see public protocols.