Skip to main content

​
Dr Green API Documentation

For external developers building forward-facing storefronts on behalf of Dr Green Digital Key (NFT) holders. All content verified against production at api.drgreennft.com as of 10 May 2026.

​
What is this?

Dr Green is a tokenised cannabis distribution platform. Holders of “Digital Key” NFTs operate small businesses that sell Dr Green’s catalogue to end customers, earning commission on each sale. This documentation is the contract between the Dr Green API and third-party developers building stores on behalf of those holders. If you’re building a holder-facing dashboard, a customer-facing storefront, or a backend integration into Dr Green’s order pipeline — start here.

​
Start here

If you’re…Read…
New to the platform01-quickstart.md — zero to first order in 30 minutes
Designing your store architectureguides/store-architecture.md
Implementing customer onboardingguides/kyc-flow.md
Implementing order trackingguides/order-lifecycle.md
Looking up a specific endpointreference/index.md
Debugging a 40102-authentication.md § Common 401 causes

​
Repository layout

drgreen-api-docs/
├── README.md                          ← you are here
├── docs/
│   ├── 01-quickstart.md               ← end-to-end walkthrough
│   ├── 02-authentication.md           ← request signing (READ THIS FIRST)
│   ├── 03-environment.md              ← URLs, headers, rate limits
│   ├── 04-errors.md                   ← envelope, status codes, retry guidance
│   ├── 06-webhooks.md                 ← inbound webhooks; why your store polls
│   ├── reference/                     ← endpoint-by-endpoint detail
│   │   ├── index.md                   ← master endpoint table
│   │   ├── strains.md
│   │   ├── clients.md
│   │   ├── carts.md
│   │   ├── orders.md
│   │   ├── sales.md
│   │   ├── commissions.md
│   │   ├── dashboard.md
│   │   ├── revenue.md
│   │   ├── nfts.md
│   │   ├── auth.md
│   │   └── keys.md
│   └── guides/
│       ├── store-architecture.md
│       ├── kyc-flow.md
│       └── order-lifecycle.md
├── openapi/
│   ├── drgreen-api.live.json          ← live spec mirror (OpenAPI 3.0.0)
│   └── drgreen-api.yaml               ← enriched spec (OpenAPI 3.1)
├── examples/
│   ├── nodejs/                        ← TypeScript signing helper + worked example
│   ├── python/                        ← Python signing helper + worked example
│   ├── curl/                          ← bash signing script + worked one-liners
│   └── php/                           ← PHP signing helper + worked example
└── pdf/                               ← branded PDF build artifacts

​
The platform in one diagram

[Customer] ─UI─▶ [Your store] ─signed REST─▶ [Dr Green API] ─Postgres─▶ [data]
                                                    │
                                                    ├──▶ [FirstAML]    (KYC/AML)
                                                    ├──▶ [CoinRemitter] (crypto pay)
                                                    ├──▶ [Payinn]       (fiat pay)
                                                    └──▶ [Ethereum]     (NFT, commissions)
Your store talks only to Dr Green. Dr Green talks to FirstAML, payment processors, and the blockchain on your behalf. This is by design — Dr Green carries the compliance, processor, and on-chain integration burden so you don’t have to.

​
Things you should know upfront

​
Authentication is per-request signed

Every request to /dapp/* includes:
  • x-auth-apikey — the holder’s Base64 PEM SPKI public key
  • x-auth-signature — Base64 ECDSA-SHA256 signature over a canonical payload string
The canonical payload depends on HTTP method. Get this wrong and you get 401 "User is not authorized" on every call. Read 02-authentication.md carefully.
⚠️ Note: earlier drafts of these docs (and the older Postman collection) had the wrong canonical-payload rule for empty-query GETs. The correct rule is to sign "{}", not "". The helpers in examples/ all have the correct logic.

​
There are no outbound webhooks (yet)

Dr Green does not currently call your store on order/KYC events. You poll. See 06-webhooks.md § The polling pattern for the recommended pattern.

​
Idempotency-Key header is not supported

Be careful with retries on POST /dapp/orders and POST /dapp/clients — naive retries produce duplicate records. See 04-errors.md § Idempotency.

​
Some endpoints are JWT-only

GET /user/me and GET /dapp/users/nfts cannot be reached with API-key authentication. The holder must use the DAPP UI for those operations and set their primary NFT before generating store API keys. See reference/nfts.md.

​
KYC is handled by Dr Green, not you

The KYC provider is FirstAML. Your store does not integrate with FirstAML directly — Dr Green handles the email + outbound webhook + verification callback. Your job is to POST /dapp/clients and poll until isKYCVerified=true and adminApproval=VERIFIED. See guides/kyc-flow.md.

​
The OpenAPI spec is incomplete in places

The live spec at https://api.drgreennft.com/api-json is OpenAPI 3.0.0 with 147 paths and 38 schemas. It’s the source of truth for endpoint shapes and request DTOs, but response shapes are mostly empty in the spec — they’re documented in this repo’s reference pages from live verification, not from the spec. The enriched OpenAPI 3.1 spec in openapi/drgreen-api.yaml adds these.

​
Code samples

Every reference page includes worked examples in:
  • Node.js / TypeScript — modern, async, with full types
  • Python — cryptography + httpx, no other deps
  • cURL + bash — for testing and ops scripts
  • PHP — openssl + curl, PHP 7.4+
The full helpers are in examples/{nodejs,python,curl,php}/ — drop-in ready, with a DrGreenClient wrapper that handles signing and the response envelope. The Python helper has been tested live against production as part of this docs build (read-only sweep, ~28 endpoints). The other three are structurally identical in logic; they handle all three canonical-payload code paths (write body, read with query, read with no query).

​
Environment

URLStatus
Productionhttps://api.drgreennft.com/api/v1✅ Healthy
Staginghttps://stage-api.drgreennft.com/api/v1❌ HTTP 503 (as of 10 May 2026)
Live OpenAPI spechttps://api.drgreennft.com/api-json✅ Available
Swagger UIhttps://api.drgreennft.com/api✅ Available
DAPP UI (where holders log in)https://dapp.drgreennft.com✅ Available
See 03-environment.md for full details on headers, rate limits, and CORS.

​
Versioning and stability

  • The current version is v1, baked into URLs (/api/v1/...).
  • The info.version in the live OpenAPI spec is the deploy version (changes on every backend deploy), not the API contract version.
  • Backend warts and inconsistencies are documented inline in each reference page (look for the 🪲 marker). Many will be addressed in v2; until then, write defensive code.

​
Reporting issues

Issue typeWhere to report
Documentation errorOpen an issue / PR against this repo
API endpoint behaviour bugContact Dr Green backend team
FirstAML / KYC issueEscalate to Dr Green support (you don’t talk to FirstAML directly)
Payment processor issueSame — Dr Green support escalates to the processor
Compromised API keyHave the holder revoke the key in the DAPP UI immediately, then generate a new pair

​
Acknowledgements

This documentation replaces an older Postman collection at documenter.getpostman.com/view/23551988/2sAXqp8isH (Sept 2024), which contained a critical incorrect detail about the canonical-payload rule. Discard that older documentation. Everything in this repo is verified against the production API.

​
What’s still pending

ItemStatus
Phase A reference pages✅ Complete
Phase C narrative guides✅ Complete
Enriched OpenAPI 3.1 spec (servers + security schemes + 401/403/500 responses)⏳ In progress
Branded PDF build⏳ In progress
This README and the docs are versioned together with the OpenAPI spec; check the change log at the bottom of each page for last-updated timestamps.