@digital-card-twin/sdk

TypeScript client SDK for the digital-card-twin protocol — certificate lookup, NFT metadata fetch, and grading event submission. Works in Node.js and modern browsers.

Installation

npm install @digital-card-twin/sdk
# or
pnpm add @digital-card-twin/sdk

Quick start

import { DigitalCardTwinClient } from "@digital-card-twin/sdk";

const client = new DigitalCardTwinClient({
  apiUrl: "https://api.digital-card-twin.com",
  subgraphUrl: "https://api.studio.thegraph.com/query/<ID>/digital-card-twin-registry/version/latest",
  rpcUrl: "https://base-sepolia.g.alchemy.com/v2/<ALCHEMY_KEY>",
});

API

lookupCertificate(certNumber, company)

Look up a graded card by its certification number and grading company. Queries The Graph subgraph first, then falls back to direct on-chain RPC.

const result = await client.lookupCertificate("85237194", "PSA");

if (result.found) {
  console.log(result.tokenId);   // bigint
  console.log(result.cardName);  // "Charizard Holo 1st Edition"
  console.log(result.grade);     // "PSA 10"
  console.log(result.owner);     // "0x..."
  console.log(result.source);    // "subgraph" | "rpc"
}

The company parameter accepts either a plain name ("PSA", "BGS") or a pre-computed bytes32 hex companyId ("0x...").

getTokenMetadata(tokenId)

Fetch the ERC-721 metadata JSON for a minted token. Resolves ipfs:// URIs via the configured gateway.

const { metadata } = await client.getTokenMetadata(42n);

console.log(metadata.name);        // "PSA 10 — Charizard Holo"
console.log(metadata.image);       // IPFS or HTTP image URL
console.log(metadata.attributes);  // [{ trait_type: "Grade", value: "10" }, ...]

submitCertificate(payload, apiKey)

Submit a grading event to queue a new NFT mint. Requires a grading company API key.

const result = await client.submitCertificate(
  {
    certificationNumber: "85237194",
    companyId: "PSA",
    cardName: "Charizard Holo 1st Edition Base Set",
    grade: "10",
    gradedAt: "2024-01-15T10:00:00Z",
    // ... other fields
  },
  process.env.DCT_API_KEY
);

if (result.queued) {
  console.log("Job ID:", result.jobId);
}

if (result.alreadyMinted) {
  console.log("Certificate already on-chain");
}

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiUrl | string | — | Required. Base URL of the digital-card-twin API | | subgraphUrl | string | — | The Graph subgraph query URL. Enables fast lookups without RPC | | rpcUrl | string | — | JSON-RPC endpoint (Base Sepolia or Base mainnet). Required for RPC fallback and getTokenMetadata | | contractAddress | 0x${string} | Base Sepolia default | Override the registry contract address | | ipfsGateway | string | https://cloudflare-ipfs.com | Gateway used to resolve ipfs:// URIs | | requestTimeoutMs | number | 10000 | Timeout per HTTP request in milliseconds |

Network

The SDK targets Base Sepolia (chain ID 84532) by default. The deployed DigitalCardTwinRegistry contract address is 0xad3898d76af2024ee1ebd2f5ff10fdeefe64361b.

Requirements

• Node.js 18+ or a modern browser with native fetch and BigInt support
• viem (peer dependency, installed automatically)