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