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: 
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.
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: 
{
  "success": true,
  "processed": 2,
  "errors": [],
  "warnings": []
}

​
4) Verify what was stored (optional)

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: 
curl https://<your-api-host>/metrics/byProtocol/awesome-dex
Or for private: 
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.