> ## 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.

# Quickstart: From zero to iOS widget

> End-to-end setup to register a protocol and push metrics for your iOS widget.

This guide walks you through the end-to-end flow to ship a custom widget:

#### Prerequisites

* Snippet mobile app installed and you can access the API key screen
* A backend service capable of sending HTTPS requests

#### 1) Create an API key (in the mobile app)

* Open the Snippet app and generate an API key
* Store the key securely; you will use it in the `Authorization: Bearer <KEY>` header

#### 2) Register your protocol (one widget = one protocol)

Request:

```bash theme={null}
curl -X POST https://<your-api-host>/api/register-protocol \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "id": "awesome-dex",
        "name": "Awesome DEX",
        "logo": "https://example.com/logo.png",
        "chains": ["ethereum", "polygon"]
      }'
```

* `id` must be unique (lowercase slug recommended). The server sanitizes the ID.
* Response includes the created protocol.

#### 3) Push your metrics

* Send metrics at your cadence. If you provide `timestamp`, it will be used; if you omit it, the server snaps to the top of the hour.
* Units are free-form; keep them consistent for display.

```bash theme={null}
curl -X POST https://<your-api-host>/api/metrics \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "metrics": [
          {
            "id": "awesome-dex___TVL",
            "value": 12345678.9,
            "protocolId": "awesome-dex",
            "unit": "USD",
            "timestamp": "2025-08-05T17:00:00Z"
          },
          {
            "id": "awesome-dex___USERS_MOM",
            "value": 5.2,
            "protocolId": "awesome-dex",
            "unit": "%"
          }
        ]
      }'
```

* Max 100 metrics per call.
* `id` must be `{protocolId}___{Label}`.
* `timestamp` must be ISO 8601 and not more than 5 minutes in the future. If omitted, the server snaps to the hour.

Successful response:

```json theme={null}
{
  "success": true,
  "processed": 2,
  "errors": [],
  "warnings": []
}
```

#### 4) Verify what was stored (optional)

```bash theme={null}
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://<your-api-host>/api/metrics
```

#### 5) Add the widget on iOS

* In the Snippet app, add your widget and select your `protocolId`.
* The widget will display the latest values you posted.

#### 6) Reading metrics (what the widget does)

* Public protocol: `GET /metrics/byProtocol/:protocolId`
* Private protocol (owned by your API key): include the same `Authorization` header.

Example:

```bash theme={null}
curl https://<your-api-host>/metrics/byProtocol/awesome-dex
```

Or for private:

```bash theme={null}
curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://<your-api-host>/metrics/byProtocol/awesome-dex
```

The response contains current values with change fields and a `timestamp` per metric.