Tokenized Digital Products

Start here

Use the API origin configured for your deployment. Browser clients should use the shared API client; scripts and agents can use a bearer API key. JSON control-plane calls use POST /rpc/<procedure>. Native protocol and data routes use versioned /v1 paths.

GET  /health
GET  /v1/discovery/resources?limit=20
GET  /v1/digital-products/{productId}/sales
GET  /v1/auth/wallet-status
POST /v1/auth/wallet-link
POST /rpc/digitalStats.summary

Authentication & boundaries

Public discovery, public product metadata, previews, and unguessable receipt metadata do not require a seller session.
Seller actions require a session cookie or a bearer API key and are scoped to the authenticated seller.
Agent integrations can bootstrap a credential through the documented agent session flow.
Human sessions must have a confirmed real email and a linked EVM wallet before using protected app or marketplace routes outside localhost. Wallet-first sign-in creates a temporary wallet-derived email that must be replaced and confirmed from Account Settings.
Never submit a seed phrase, private key, raw facilitator credential, or full payment signature to an API endpoint.

Transaction sales endpoint

GET /v1/digital-products/<productId>/sales returns the seller's safe transaction projection. It contains one item for each facilitator-settled paid transaction; a 402 challenge, rejected payment, or delivery retry is not a second sale.

{
  "productId": "prd_…",
  "items": [
    {
      "id": "pay_…",
      "transactionRef": "0x…",
      "settlementRef": "0x…",
      "payerWallet": "0x…",
      "amountAtomic": "1200",
      "network": "eip155:31337",
      "asset": "0x…",
      "settledAt": "2026-08-24T00:00:00.000Z",
      "receiptId": "rcp_…",
      "deliveryOutcome": "delivered"
    }
  ]
}

The response is currently backed by the local persisted projection. Its stable shape is designed so a future on-chain event/indexer projection can replace the source without changing the dashboard contract.

Useful routes

GET /v1/discovery/resources — public, paginated product discovery.
GET /v1/digital-products/<productId>/previews — public preview metadata.
GET /v1/digital-products/<productId>/content — free delivery or x402-protected paid delivery.
GET /v1/licenses/<licenseId> — machine-readable receipt and terms/content hashes.
POST /rpc/digitalStats.summary — seller aggregate stats plus the sales array.
POST /v1/reports — authenticated users can report a product or creator for copyright/DMCA, NSFW, illegal content, malware, spam, impersonation, fraud, or another concern.
GET /v1/admin/access — returns the current human session's moderation role and permissions.
GET /v1/admin/reports?status=open|resolved|all and PATCH /v1/admin/reports/<reportId> — manager, moderator, and admin review, ban, and resolve actions.
GET /v1/admin/staff, POST /v1/admin/staff, and PATCH /v1/admin/staff/<staffId> — admin-only staff role management.
GET /v1/auth/wallet-status — returns the current session's email verification, linked EVM wallets, and account-access requirement status.
POST /v1/auth/wallet-link — consumes a Better Auth SIWE nonce and links the signed wallet to the current email session.

Reporting and moderation

Reports are written to Postgres with the reporter, target snapshot, reason, details, status, and review decision. Staff principals are configured in the admin_principals table by email or by an EVM wallet linked to the user's Better Auth session. Roles are admin, manager, and moderator. Product bans pause new delivery and hide the product from public discovery; reports and issued receipts remain auditable.

POST /v1/reports
{
  "targetType": "product",
  "productId": "prd_…",
  "reportType": "copyright_dmca",
  "details": "Describe the rights concern and public evidence."
}

PATCH /v1/admin/reports/rpt_…
{ "action": "ban_product", "note": "Verified rights complaint" }

POST /v1/admin/staff
{ "email": "moderator@example.com", "role": "moderator" }

Admin sessions are blocked from buying, trading, and publishing through server-side checks. The report form is an intake mechanism, not a legal determination or a substitute for required jurisdiction-specific notice procedures.

Errors & caching

Errors use a stable JSON envelope with error.code and a safe message. Seller sales and stats are private projections and return Cache-Control: private, no-store. Treat analytics as eventually consistent and never as a custodial balance.