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

# Batch peg signal for every active asset, keyed by mint



## OpenAPI

````yaml https://api.pegana.xyz/openapi.json get /v1/peg/feed
openapi: 3.1.0
info:
  title: Pegana API
  description: >-
    The peg-risk oracle for Solana. Read real-time peg state, history, alerts,
    and delivery health across 26 active mainnet assets spanning 6 classes —
    LSTs, fiat / CDP / delta-neutral / yield-bearing / FX stables, and a
    leveraged synthetic. Some assets are flagged `monitoring_only` (beta): their
    alerts are live but the calibration is provisional. Public read endpoints
    require no API key but ARE rate-limited per IP (300/min global, 10/min on
    /v1/audit.csv); exceeding the limit returns 429 with a Retry-After header.
    User-scoped /v1/me/* routes require a JWT obtained via Telegram Login. Every
    state transition emits a public receipt at /v1/audit/{id} with the
    methodology version, frozen inputs, and an on-chain SPL Memo commit (SAS
    deferred per ADR-0004 — SPL Memo gives 90% of the value). EVERY error
    response across the API is JSON — the envelope is `{error, message, asset?}`
    (the `ApiError` schema); branch on the stable `error` code, never on
    `message`. Malformed request bodies surface as `{error:"invalid_body"}`. Any
    endpoint may also return 500 `{error:"internal"}` on an unexpected server
    error.
  contact:
    name: Rafael Souza
    email: raffxweb3@gmail.com
  license:
    name: MIT
    identifier: MIT
  version: 0.1.0
servers:
  - url: https://api.pegana.xyz
    description: Production
security: []
tags:
  - name: Health
    description: Liveness and readiness probes
  - name: Assets
    description: Public read access to asset state, history, and metadata
  - name: Alerts
    description: Global feed of state transitions
  - name: Stats
    description: Aggregate counters and delivery health
  - name: Auth
    description: Telegram Login Widget → JWT
  - name: Me
    description: Authenticated user profile and preferences
  - name: Subscriptions
    description: User alert subscriptions
  - name: Webhooks
    description: User-managed Ed25519-signed webhooks
  - name: WebSocket
    description: Live state stream
  - name: audit
    description: >-
      Public receipts for alerts — methodology version, inputs frozen, replay
      bundles. All endpoints public, no auth, cacheable. ADR-0006 four-state
      response on /v1/audit/:id (200/202/404/410); ADR-0014 bounds (90-day max,
      100-row max, 50k-row cap).
  - name: methodology
    description: >-
      Public lifecycle status of the active methodology — version + status
      (active/deprecated/broken) + optional fix_url when broken. Consumed by
      web/app/api/methodology to power the home-page trust strip.
  - name: peg
    description: >-
      Mint-keyed peg-signal feed for tokens.xyz / aggregator consumption.
      Public, no auth, cacheable. Honest beta status via `calibration` +
      `monitoring_only`; freshness via `as_of` + `stale`.
paths:
  /v1/peg/feed:
    get:
      tags:
        - peg
      summary: Batch peg signal for every active asset, keyed by mint
      operationId: peg_feed
      responses:
        '200':
          description: Peg signal for all active assets, keyed by Solana mint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PegFeedResponse'
        '304':
          description: Not modified (If-None-Match matched the current ETag)
components:
  schemas:
    PegFeedResponse:
      type: object
      description: >-
        Batch envelope, keyed by mint. tokens.xyz merges `data[<mint>]` into its
        own

        per-currency buckets.
      required:
        - ok
        - methodology
        - generated_at
        - count
        - data
      properties:
        count:
          type: integer
          minimum: 0
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PegSignal'
          propertyNames:
            type: string
        generated_at:
          type: string
          description: >-
            RFC3339 build time — an explicit staleness read independent of HTTP
            headers.
        methodology:
          type: string
        ok:
          type: boolean
    PegSignal:
      type: object
      description: >-
        One asset's peg signal. A superset of the tokens.xyz contract subset;
        every

        `Option` field is omitted (not null) when absent so a thin consumer can
        model

        only what it needs.
      required:
        - mint
        - symbol
        - name
        - class
        - anchor
        - peg_target
        - decimals
        - calibration
        - monitoring_only
        - stale
        - methodology
        - receipt_url
      properties:
        anchor:
          $ref: '#/components/schemas/Anchor'
          description: USD | FX | NAV — how to read fair value without Pegana's taxonomy.
        as_of:
          type:
            - string
            - 'null'
          description: RFC3339 of the latest snapshot (= `updated_at`). Omitted when none.
        calibration:
          $ref: '#/components/schemas/Calibration'
          description: provisional | calibrated. Always present.
        class:
          type: string
        confidence:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Confidence'
              description: >-
                Pyth confidence bucket: high | medium | low | unknown. Omitted
                when no snapshot.
        decimals:
          type: integer
          format: int32
        discount:
          type:
            - string
            - 'null'
          description: Signed discount fraction (serialized as a string).
        discount_bps:
          type:
            - number
            - 'null'
          format: double
          description: Convenience `discount × 10000` as a number (consumer rounds). Raw.
        intrinsic_usd:
          type:
            - string
            - 'null'
        jitter_bps_24h:
          type:
            - string
            - 'null'
        market_usd:
          type:
            - string
            - 'null'
        methodology:
          type: string
          description: Active methodology version (global), e.g. `0.4.0`.
        mint:
          type: string
          description: >-
            Canonical Solana mint — also the `data` map key in the batch
            response.
        monitoring_only:
          type: boolean
        name:
          type: string
        peg_target:
          type: string
        receipt_url:
          type: string
          description: Human/agent verify pointer for this asset.
        stale:
          type: boolean
          description: >-
            True when `as_of` is older than the 15-min freshness bound, or
            absent.
        state:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PegState'
              description: >-
                PEGGED..BLACK_SWAN | UNKNOWN. Omitted when there is no current
                snapshot.
        symbol:
          type: string
        worst_abs_24h:
          type:
            - string
            - 'null'
    Anchor:
      type: string
      description: >-
        Peg anchor tells a consumer how to interpret the asset's fair value
        WITHOUT

        knowing Pegana's internal taxonomy:


        - `"USD"` — the asset targets exactly $1 (fiat-backed, RWA,
        delta-neutral,
          and CDP stablecoins). A discount from $1 IS the risk signal.

        - `"FX"` — the asset targets a fixed non-USD fiat exchange rate (e.g.
          EURC→EUR, BRZ→BRL). Read `peg_target` for the specific currency. A
          discount from the FX rate IS the risk signal.

        - `"NAV"` — the asset's fair value is its intrinsic redemption/net-asset
          value, which is NOT a fixed fiat rate (LSTs, yield-bearing stables,
          synthetic leverage). The discount is relative to NAV, and NAV itself
          moves.

        IMPORTANT: derived from `class`, NOT from `peg_target`. A yield-bearing

        stable can have `peg_target = "USD"` yet `anchor = "NAV"` because its

        price legitimately accrues above $1 over time.
      enum:
        - USD
        - FX
        - NAV
    Calibration:
      type: string
      description: >-
        Calibration status of an asset (and of an alert that asset emitted).


        - `provisional` — a "beta" asset: released and alerting publicly, but
        its
          thresholds are not yet validated over a full post-launch calibration
          window. Equivalent to `monitoring_only=true`. Read its alerts as
          experimental.
        - `calibrated` — a fully calibrated asset that counts in the launch
          denominator.

        This is the SAME vocabulary the dispatcher emits on the webhook
        canonical

        event (`"calibration":"provisional"|"calibrated"`), so a machine
        consumer

        reading both the webhook fan-out and the REST read surfaces sees one
        word

        for the concept instead of `calibration` there and `monitoring_only`
        here.
      enum:
        - provisional
        - calibrated
    Confidence:
      type: string
      description: >-
        Pyth oracle confidence bucket. Mirrors `pyth_confidence_label`. Scopes
        the

        PRICE-ORACLE confidence interval only (conf/price ratio) — NOT
        market-quote

        or route-depth reliability.
      enum:
        - high
        - medium
        - low
        - unknown
    PegState:
      type: string
      description: >-
        Class-aware peg state. Mirrors the engine `PegState` enum and the

        `peg_state` Postgres enum. Used for `state`, `from_state`, and
        `to_state`

        fields across the API.


        The state is CLASS-AWARE: an LST reading a −1.4% discount (normal
        unstaking

        spread) is `PEGGED`, while a fiat stable at far less would be `DRIFT`.
        Trust

        this value directly rather than imposing a naive discount cut.
      enum:
        - PEGGED
        - DRIFT
        - DEPEG
        - CRITICAL
        - BLACK_SWAN
        - UNKNOWN

````