Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dr.green/llms.txt

Use this file to discover all available pages before exploring further.

​
NFTs (Digital Keys)

Endpoint reference: ⚠️ Limited surface for store builders. The Dr Green platform is built around NFTs (“Digital Keys”) that grant holder rights. Most NFT-related endpoints exist for the marketplace and the holder’s own DAPP UI — and those are JWT-only, not reachable via API key. As a store builder, your effective surface is:
  1. The holder’s nft field on every authenticated response (the primary NFT scope of the API key)
  2. Setting the primary NFT (which the holder typically does in the DAPP UI before issuing keys)

​
Key concept: API keys are scoped to a primary NFT

Every API key issued by a holder is tied to one primary NFT at the time of issuance. All /dapp/* calls operate within that NFT’s scope:
  • Clients you create are linked to that NFT
  • Orders are placed against that NFT’s product allocation
  • Commissions accrue to that NFT
  • Revenue and dashboard counts are per-NFT
The nft object embedded in many response shapes ({tokenId, ownerId}) tells you which NFT the API key is currently scoped to. If a holder owns multiple NFTs and wants to operate a separate store per NFT, they must:
  • Either generate one API key per NFT (recommended), or
  • Use the DAPP UI to switch primary NFT and re-test

​
Endpoints

MethodPathAuthDescriptionReachable from store?
GET/dapp/users/nftsJWT onlyList all NFTs the holder owns❌ No
PATCH/dapp/users/primary-nftJWT only (presumed)Set the primary NFT for the holder’s session❌ No
(read-only inspection)embedded in /dapp/* responsesAPI-key + sigRead the current primary NFT context✅ Implicit

​
❌ GET /dapp/users/nfts — JWT-only

This endpoint lists all NFTs the authenticated user owns. You cannot reach it with API-key authentication. Verified live: returns 401 "Unauthorized" (43-byte response, the short-form JWT-rejection message) regardless of signature correctness.

​
Why this matters for store builders

Your store does not know which NFTs the holder owns. The holder must pick their primary NFT in the DAPP UI before generating API keys for you. Once they do, every authenticated response from your /dapp/* calls will include the nft field showing the scope.

​
Workaround: read the embedded nft field

Every authenticated /dapp/* response that returns a client, order, or related entity includes an nft object showing the API key’s current scope: 
{
  "nft": {
    "tokenId": 56,
    "ownerId": "0x553374bd6e81f952821e37f4b8e208a81164fb2e"
  }
}
FieldTypeNotes
tokenIdintThe on-chain NFT token ID (1–5145)
ownerIdstringEthereum address of the holder, lowercase
Cache this on first authenticated call to know which NFT the holder is operating under. 
// Discover the API key's NFT scope
async function discoverNftScope(): Promise<{ tokenId: number; ownerId: string }> {
  const { data } = await listClients(1, 1);
  if (data.clients.length > 0) return data.clients[0].nft;
  const summary = await getDashboardSummary();
  // Dashboard summary doesn't expose nft directly; fall back to other reads
  throw new Error('No NFT context — holder may not have set a primary NFT');
}

​
⚠️ PATCH /dapp/users/primary-nft — JWT-only (presumed)

The DAPP UI calls this endpoint when a holder switches between their owned NFTs. The request body shape per UpdatePrimaryNftDto: 
{
  "tokenId": 56
}
🔒 Not verified live with API-key auth — likely also JWT-only. Even if reachable, store builders should not call this. Switching primary NFT mid-session would change the scope of every subsequent call and likely break the holder’s reporting. Treat as a DAPP-UI-only operation. If a holder wants to operate two NFTs from one store, generate two API key pairs (one per primary NFT) and route per-NFT in your store’s logic.

​
NFT cap and tier structure

Confirmed from backend research, useful context for stores:
TierCountNotes
Platinum50Premium tier
Gold55Mid tier
Standard5,040Mass tier
Total cap5,145All NFTs are minted; scarcity is fixed
The tokenId ranges and tier mapping are not exposed via the DAPP API. The marketplace/* endpoints (which sit outside the DAPP scope) handle this for the public marketplace.

​
Marketplace endpoints (out of scope for store builders)

The Dr Green API has a substantial /api/v1/marketplace/* surface (NFT trading, listings, transactions, planet metadata) but these are intended for the marketplace UI, not external store integrations. They use a mix of public and JWT auth and are not relevant to a holder-store integration. If your store needs to display NFT metadata (e.g. “powered by Dr Green Digital Key #56”), use the tokenId from the embedded nft field plus your own static mapping of tier → display string, or query Dr Green’s public CDN if available. Do not integrate the marketplace endpoints into a store backend.

​
Common patterns

​
Display the holder’s NFT badge

function nftBadge(nft: { tokenId: number; ownerId: string }): string {
  return `Dr Green Digital Key #${nft.tokenId}`;
}

​
Verify the API key is scoped to an expected NFT

If your store is built for a specific holder/NFT, verify on startup: 
async function verifyExpectedNft(expectedTokenId: number) {
  const scope = await discoverNftScope();
  if (scope.tokenId !== expectedTokenId) {
    throw new Error(`Wrong API key — expected NFT #${expectedTokenId}, got #${scope.tokenId}`);
  }
}

​
See also

  • Authentication — why API-key auth is scoped per primary NFT
  • Keys — how holders generate per-NFT API key pairs
  • Clients, Orders — embedded nft field on every entity