Quickstart: From zero to iOS 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)

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.

{
  "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.

curl https://<your-api-host>/metrics/byProtocol/awesome-dex

curl -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://<your-api-host>/metrics/byProtocol/awesome-dex