Skip to main content

Tokenization

Overview​

The tokenization feature enables the creation of Digital Product Passports (DPPs), represented as NFTs on compatible blockchains (e.g., Starknet). These DPPs ensure product traceability, authenticity, and post-sale engagement.

This guide will walk you through the entire process, from setting up your first collection to minting individual DPPs and managing user claim permissions. The tokenization engine is built around three core concepts:

DPP Collections

A collection is a smart contract that groups and manages a series of Digital Product Passports. It defines the rules, metadata, and blockchain network for your DPPs.

Digital Product Passports (DPPs)

A DPP is a unique token (NFT) representing a single product. It holds all the product's information, such as its origin, materials, and ownership history.

Claim Permissions

A mechanism to control which user is allowed to claim ownership of a specific DPP after it has been minted, linking it to their digital wallet.

1. Managing DPP Collections​

Before you can mint a DPP, you must first create a collection. A collection is a smart contract that will own all the DPPs you mint within it.

Create a Collection​

POST /v1/dpp/collections

This endpoint creates a new DPP collection. You need to provide a name, a description, and specify the blockchain network where the smart contract will be deployed.

Example Request Body​

{
  "name": "My Awesome Product Line",
  "description": "A collection of DPPs for our awesome products.",
  "network": "starknet-sepolia"
}

The API will return a collection object, including a unique id that you will use in subsequent requests.

List Collections​

GET /v1/dpp/collections

This endpoint returns a list of all the DPP collections you have created.

Get Collection Details and Deployment Status​

You can retrieve detailed information about a specific collection, including its deployment status on the blockchain.

  • GET /v1/dpp/collections/{id}: Returns details for the specified collection.
  • GET /v1/dpp/collections/{id}/deploy-status: Get the real-time deployment status.
  • GET /v1/dpp/collections/{id}/deploy-status/sse: Use this SSE endpoint to get live updates on the deployment progress, perfect for a UI.

2. Creating DPPs (Minting)​

Once your collection is created and deployed, you can start minting DPPs. Minting is done in batches using a JSON Lines file.

API Endpoint​

POST /v1/dpp/collections/{id}/mint

This endpoint launches a minting job. The body of the request must be a JSON Lines file where each line is a DppMintData object.

Example JSONL payload​

{"dppId": "dpp-001", "metadata": {"name": "Product A", "description": "...", "image": "...", "attributes": []}}
{"dppId": "dpp-002", "metadata": {"name": "Product B", "description": "...", "image": "...", "attributes": []}}

⚠️ The dppId field must be a unique and stable identifier for each DPP. We recommend using a hash (e.g., SHA-256) of a unique product identifier.

Tracking Minting Jobs​

Minting is an asynchronous process. You can track the progress of a minting job using the jobId returned by the minting endpoint.

  • GET /v1/dpp/collections/{id}/mint/{jobId}/status: Returns the current status of the job (total, completed, errors).
  • GET /v1/dpp/collections/{id}/mint/{jobId}/status/sse: Returns a Server-Sent Events (SSE) stream for real-time progress updates.

3. Managing Claim Permissions​

After a DPP is minted, you need to grant permission to a user to "claim" it and associate it with their wallet.

Create a Claim Permission​

POST /v1/dpp/claim-permissions

This endpoint creates a permission for a user to claim a specific DPP.

Example Request Body​

{
  "dppId": "dpp-001",
  "userEmail": "customer@example.com"
}

Other Claim Permission Endpoints​

  • GET /v1/dpp/claim-permissions: Lists all existing claim permissions.
  • GET /v1/dpp/claim-permissions/{id}: Retrieves a specific permission.
  • PATCH /v1/dpp/claim-permissions/{id}: Updates a permission.
  • DELETE /v1/dpp/claim-permissions/{id}: Revokes a claim permission.

4. SDK Integration (Claiming a DPP)​

The final step is for the user to claim their DPP using the SDK in your frontend application.

Example using React​

The useKeybanAccount hook provides an account object with a dppClaim method.

import React from "react";
import { useKeybanAccount } from "@keyban/sdk-react";

function DppClaimButton({ dppIdToClaim }) {
  const [account, accountError] = useKeybanAccount();

  if (accountError) {
    return <div>Error: {accountError.message}</div>;
  }
  if (!account) {
    return <div>Loading account...</div>;
  }

  const handleClaim = async () => {
    try {
      // The user must have a claim permission for this dppId
      const { transactionHash } = await account.dppClaim(dppIdToClaim);
      console.log("Claim successful, tx hash:", transactionHash);
      alert("Product claimed successfully!");
    } catch (error) {
      console.error("Claim failed:", error);
      alert("Failed to claim product.");
    }
  };

  return <button onClick={handleClaim}>Claim Your Digital Passport</button>;
}

This action transfers the NFT to the user's wallet, making them the official owner on the blockchain.