Headless Locker API

Roadmap Feature

The Headless Locker API is a planned feature currently in development. The following documentation outlines the proposed functionality and is subject to change. Please contact our team at sales@feature.io for the latest updates on its availability.

Overview

The Headless Locker API allows for flexible integration of digital assets into your existing applications. It provides the data you need to create native experiences that feel like a natural part of your product, without forcing a specific UI implementation.

[!TIP] Coming Soon: We are currently building a library of pre-built UI Widgets and React Components. These will allow you to drop in a fully functional "Locker" view with a single line of code, while still retaining the option to customize as needed.

Key Use Cases

• Native In-App Galleries: Display a user's collected digital assets directly within their profile page.
• Content Gating: Verify a user's ownership of a specific asset to grant them access to exclusive content, features, or communities.
• Custom UI/UX: Build unique visualizations or interactions around the assets a user has collected.
• Engagement Drivers: Display "unclaimed" or "locked" assets to show users what they can earn next, driving them to complete specific activities.

Proposed API Reference

Fetch User Assets

Retrieves a list of all digital assets associated with a specific user, including both owned and unclaimed assets.

GET /api/v1/users/{userId}/assets

Path Parameters

Parameter	Type	Description
userId	string	Required. The unique identifier for the end-user.

Query Parameters

Parameter	Type	Description
campaignId	string	Optional. Filters the assets to those belonging to a specific campaign.
status	string	Optional. Filters assets by their status. Can be owned or unclaimed.

Authentication

This endpoint is authenticated automatically when using our SDKs. Ensure you have initialized the SDK with the correct API Key. See our Authentication Guide for more details.

Proposed Response Payload

The API will return a JSON object containing a list of assets. Each asset object provides all the necessary metadata to render it in your UI.

Example Response:

{
  "assets": [
    {
      "tokenId": "101",
      "contractAddress": "0x123abc...",
      "name": "Episode 1 Completion Badge",
      "description": "Awarded for watching the premiere episode of 'Lollipop'.",
      "imageUrl": "https://cdn.feature.io/images/asset_101.png",
      "animationUrl": "https://cdn.feature.io/videos/asset_101.mp4",
      "status": "owned", // The user has earned this asset.
      "blockchain": "avalanche-fuji",
      "attributes": [
        {
          "trait_type": "Series",
          "value": "Lollipop"
        },
        {
          "trait_type": "Episode",
          "value": "1"
        },
        {
          "trait_type": "Rarity",
          "value": "Common"
        }
      ]
    },
    {
      "tokenId": null, // No tokenId as it hasn't been minted for the user yet.
      "contractAddress": "0x123abc...",
      "name": "Verified Profile Badge",
      "description": "Verify your profile to claim this exclusive badge.",
      "imageUrl": "https://cdn.feature.io/images/asset_locked.png", // Could be a greyed-out or locked image.
      "animationUrl": null,
      "status": "unclaimed", // The user can earn this asset but does not yet own it.
      "blockchain": "avalanche-fuji",
      "attributes": [
        {
          "trait_type": "Type",
          "value": "Achievement"
        }
      ]
    }
  ]
}