Response models

Types below come from packages/normalizer and API route serializers. Do not assume fields are always non-null unless noted.

Envelope

Successful responses wrap payloads:

{ "data": { /* ... */ } }

Paginated list responses:

{ "data": [ /* ... */ ], "pagination": { "nextCursor": "...", "limit": 50 } }

NormalizedAsset

Full object returned by GET /v1/assets/:mint.

Ownership (`ownership`)

SNS names use the .sns TLD (formerly .sol). The dashboard also links owners to Magic Eden profile pages using the owner address; those links are UI-only and not part of this object.

Collection identity (`collection`)

Embedded collection reference on a resolved asset. This is **not** marketplace scraping and **not** scam analysis.

**nameSource values** (provider-independent source class):

**Resolution order** when address is known and name is missing:

1. Existing grouping / DAS collection metadata on the asset

2. Persisted / cached collection identity (when available)

3. Nested resolution of the collection mint through the normal resolver stack (bounded depth)

4. Off-chain JSON for the collection mint

Nested collection resolution is **non-fatal** and depth-bounded (default depth 1). If enrichment fails, the asset still returns successfully with collection.address preserved and collection.name left null.

Media (`media`)

Metadata (`metadata`)

Diagnostics (`diagnostics`)

Diagnostics describe structural completeness — **not** a scam or safety score.

Health (`health`)

Health measures metadata reliability, completeness, and accessibility — **not** fraud detection.

Issue codes include: NAME_MISSING, IMAGE_MISSING, OFFCHAIN_METADATA_FAILED, COLLECTION_UNVERIFIED, METADATA_MUTABLE, IMAGE_RECOVERED, and others defined in HEALTH_ISSUE_CODES.

Inspection

#### tokenProgram

mpl_core uses program ID CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d. Classic SPL mint/freeze authorities do **not** apply to MPL Core assets — those permission fields remain null (UI may show “Not applicable”).

#### core (optional, MPL Core)

Additive control facts when the asset is Metaplex Core:

MPL Core is classified (never unknown for program ID CoREENx…) via DAS interfaces (MplCoreAsset / MplCoreCollection / MplCoreGroup), account-owner detection, and available DAS plugin payloads. Helius getAsset requests showCollectionMetadata: true by default so collection names can arrive in grouping[].collection_metadata without a nested fetch; when the name is still missing, collection-identity enrichment may resolve the collection address non-fatally. This is **classification and control-fact awareness**, not a claim of complete on-chain Core plugin decoding beyond DAS.

#### permissions (Authority Intelligence / Control & Permission Metadata)

Technical on-chain control facts. Presence of an authority does **not** by itself mean an asset is unsafe.

**Null vs absent:** Fields are always present on NormalizedAsset. null means the authority is absent, revoked, or not determinable for this asset class (for example classic mint authorities on compressed NFTs). Empty strings are not used.

Compressed NFTs: classic mint/freeze authorities often do not apply the same way; values remain null when not determinable. Update authority may still be available from Metaplex/DAS metadata.

#### extensions

Array of { type: string, data?: object } for Token-2022 extensions (transfer hook, transfer fee, non-transferable, default account state, mint close authority, permanent delegate, token metadata, and others already decoded).

#### risk.flags

Array of { code, severity, message, field? }.

Flag codes (technical capabilities, not malicious/safe assertions):

• MINT_AUTHORITY_ACTIVE
• FREEZE_AUTHORITY_ACTIVE
• PERMANENT_DELEGATE_ACTIVE
• TRANSFER_HOOK_ACTIVE
• TRANSFER_FEE_CONFIGURED
• NON_TRANSFERABLE
• DEFAULT_ACCOUNT_STATE_FROZEN
• MINT_CLOSE_AUTHORITY_ACTIVE
• UPDATE_AUTHORITY_PRESENT (informational only — normal for many NFTs)

AssetHealthResponse

GET /v1/assets/:mint/health:

{ "assetId": "...", "health": { /* MetadataHealth */ } }

AssetInspectionResponse

GET /v1/assets/:mint/inspection:

{
  "assetId": "...",
  "tokenProgram": { /* TokenProgram */ },
  "permissions": { /* Permissions */ },
  "extensions": [ /* TokenExtension */ ],
  "risk": { "flags": [ /* RiskFlag */ ] }
}

MediaReliabilityResponse

GET /v1/assets/:mint/media — see [media.md](./media.md).

Snapshot models

**Latest** — { mint, snapshotHash, schemaVersion, createdAt, asset }

**History item** — { snapshotHash, healthScore, healthStatus, createdAt }

CollectionEntity

See [collections.md](./collections.md).

CollectionHealthSummary

Aggregated health with separate standards (metadata) and tokenPrograms (on-chain) distributions.

Monitor & event models

See [monitoring.md](./monitoring.md).

HEALTH vs DIAGNOSTICS vs RISK

These layers are intentionally separate. Good metadata can coexist with active freeze authority or transfer hooks.