API Reference

Complete reference for integrating ProjectZero Prompt Mining into your LLM platform using the boilerplate API.

Integration Overview

The Prompt Mining Boilerplate is a ready-to-deploy service that abstracts all blockchain complexity from your LLM platform. Deploy it to your infrastructure, and your application can reward users for prompts through simple HTTP API calls.

1. Deploy Boilerplate

Run the boilerplate on your infrastructure (Docker, AWS, GCP, etc.)

2. Integrate Your LLM

Call boilerplate APIs from your LLM service when users submit prompts

3. Users Get Rewarded

Users receive blockchain tokens automatically, no wallet required

All blockchain transactions, gas management, and PZERO Gateway communication are handled by the boilerplate. Your application only needs to make simple API calls.

Authentication

The boilerplate authenticates with the PZERO Gateway using your API key. Your backend handles all blockchain operations—users never need to authenticate on-chain.

PZERO API Key

Your backend uses the API key to authorize mint operations with the PZERO Gateway. Users interact with your service without any blockchain knowledge.

bash

# In your .env file
PZERO_API_KEY=pzero_live_your_api_key_here

Security: Your API key and private key must be kept server-side only. Never expose them in client-side code or commit them to version control.

OAuth Sessions

Dashboard access is OAuth-only. After Google/GitHub/email link authentication, exchange the code with /auth/oauth/complete to establish a session (httponly cookie). Email links are issued via /auth/oauth/email.

POST/auth/oauth/complete

Exchange the OAuth authorization code + state for a ProjectZero session.

Authentication: Requires x-api-key header

Parameters

codestringRequired

Authorization code returned by the provider

statestringRequired

CSRF state you originally generated

Request Example

json

{
  "code": "4/0Ad...xyz",
  "state": "f4ce8e2dbdfc4a4284"
}

Response Example

json

{
  "success": true,
  "customer": {
    "id": "cust_abc123",
    "email": "team@company.com",
    "tier": "pro"
  },
  "session": {
    "expiresAt": "2025-01-16T10:30:00Z"
  }
}

POST/auth/oauth/email

Request a passwordless magic link. The link redirects back to /oauth/callback with the same code/state exchange.

Authentication: Requires x-api-key header

Parameters

emailstringRequired

Work email to receive the link

redirectUristringRequired

Callback URL registered for your dashboard

Request Example

json

{
  "email": "founder@company.com",
  "redirectUri": "https://pm.company.com/oauth/callback"
}

Response Example

json

{
  "success": true,
  "message": "Magic link sent. It expires in 15 minutes."
}

Base URL

The boilerplate runs on your infrastructure. The default development URL is:

bash

http://localhost:3001

For production, deploy to your chosen hosting provider and update the base URL accordingly.

Boilerplate API Endpoints

These are the core API endpoints provided by the Prompt Mining Boilerplate. Deploy the boilerplate to your infrastructure and call these endpoints from your LLM application.

Quick Integration Example

Here's how to integrate prompt mining into your LLM service:

typescript

// In your LLM backend (Express example)
app.post('/chat', async (req, res) => {
  const { prompt, userId } = req.body

  // 1. Process with your LLM
  const llmResponse = await callYourLLM(prompt)

  // 2. Mint the prompt (reward user)
  try {
    const mintResult = await fetch('http://your-boilerplate:3001/api/prompts/mint-for-user', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        prompt,           // Boilerplate hashes this locally
        userId,           // Your internal user ID
        activityPoints: 25  // Reward amount
      })
    })

    const { txHash, promptHash } = await mintResult.json()

    // 3. Return LLM response + mint confirmation
    res.json({
      llmResponse,
      rewardInfo: {
        txHash,
        activityPoints: 25,
        message: 'You earned 25 Activity Points for this prompt!'
      }
    })
  } catch (error) {
    // Handle mint failure gracefully (don't block LLM response)
    console.error('Mint failed:', error)
    res.json({ llmResponse })
  }
})

POST/api/prompts/mint-for-user

Mint a prompt with backend signature only. Your backend hashes the prompt, requests authorization from PZERO Gateway, and submits the blockchain transaction. Users don't need wallets.

Authentication: Requires x-api-key header

Parameters

promptstringRequired

The full text of the prompt (hashed locally before sending to PZERO)

userIdstringRequired

Your internal user ID (for database tracking and reward distribution)

activityPointsnumber

Number of Activity Points to reward the user (defaults to 25)

Request Example

json

{
  "prompt": "How do I optimize React performance?",
  "userId": "user_12345",
  "activityPoints": 20
}

Response Example

json

{
  "success": true,
  "txHash": "0x7890abcdef1234567890abcdef1234567890abcdef1234567890abcdef123456",
  "promptHash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
  "activityPoints": 20
}

GET/api/activity-points/:address

Get Activity Points balance for a wallet address. Useful for displaying rewards in your user dashboard.

Parameters

addressstring (path parameter)Required

Ethereum wallet address (typically your backend wallet)

Response Example

json

{
  "success": true,
  "data": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "balance": 1250,
    "decimals": 18,
    "symbol": "AP"
  }
}

GET/api/prompts/:hash

Check if a prompt hash has been minted on-chain and get metadata. Use this to prevent duplicate mints.

Parameters

hashstring (path parameter)Required

Keccak256 hash of the prompt

Response Example

json

{
  "success": true,
  "data": {
    "promptHash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
    "exists": true,
    "author": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "activityPoints": 25,
    "mintedAt": "2024-12-20T10:30:00Z",
    "txHash": "0x7890abcdef1234567890abcdef1234567890abcdef1234567890abcdef123456",
    "blockNumber": 12345680
  }
}

GET/api/health

Health check endpoint to verify service status and connectivity to PZERO Gateway and blockchain.

Response Example

json

{
  "status": "ok",
  "timestamp": "2024-12-25T10:30:00Z",
  "version": "1.0.0",
  "services": {
    "pzeroGateway": "connected",
    "blockchain": "connected",
    "database": "connected"
  }
}

Error Handling

All endpoints return errors in a consistent format:

json

{
  "success": false,
  "error": {
    "code": "AUTHORIZATION_FAILED",
    "message": "Failed to get authorization from PZERO Gateway",
    "details": {
      "reason": "Quota exceeded for tier: free"
    }
  }
}

Common Error Codes

INVALID_API_KEY

Your API key is missing, invalid, or expired. Check your .env file.

QUOTA_EXCEEDED

You've reached your monthly quota limit. Upgrade your tier at pm.projectzero.io/dashboard.

INVALID_ADDRESS

The provided Ethereum address is malformed. Ensure it's a valid 0x-prefixed address.

PROMPT_ALREADY_MINTED

This prompt hash has already been minted. Each prompt can only be minted once on-chain.

SIGNATURE_EXPIRED

The PZERO authorization signature has expired. Signatures are time-limited for security.

BLOCKCHAIN_ERROR

Blockchain transaction failed. Common causes: insufficient gas, network congestion, or incorrect contract addresses.

INSUFFICIENT_BALANCE

Your backend wallet doesn't have enough ETH to pay for gas. Fund your wallet to continue minting.

Rate Limits

Rate limits are enforced by the PZERO Gateway based on your tier:

Tier	Requests/Month	Rate Limit
Free	1,000	10 req/min
Pro	100,000	100 req/min
Enterprise	Unlimited	Custom

Rate limit headers are included in all PZERO Gateway responses:

http

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640000000

Gateway Public Endpoints (Optional)

While the boilerplate abstracts all Gateway communication, you can optionally call these PZERO Gateway endpoints directly to access usage statistics, account information, and prompt history. These are useful for building custom dashboards or analytics.

Base URL: https://pm-gateway.projectzero.io
Authentication: Include your PZERO API key in the x-api-key header.

GET/v1/account/usage

Get your current API usage statistics including quota limits, remaining calls, and period information.

Authentication: Requires x-api-key header

Parameters

x-api-keystring (header)Required

Your PZERO API key

Response Example

json

{
  "success": true,
  "data": {
    "tier": "pro",
    "period": {
      "start": "2024-12-01T00:00:00Z",
      "end": "2024-12-31T23:59:59Z"
    },
    "quota": {
      "limit": 100000,
      "used": 45230,
      "remaining": 54770,
      "percentage": 45.23
    },
    "rateLimit": {
      "requestsPerMinute": 100,
      "requestsThisMinute": 12
    }
  }
}

GET/v1/prompts/history

Retrieve your prompt mining history including hashes, timestamps, rewards, and transaction details.

Authentication: Requires x-api-key header

Parameters

x-api-keystring (header)Required

Your PZERO API key

pagenumber (query)

Page number for pagination (default: 1)

limitnumber (query)

Results per page (default: 50, max: 100)

startDatestring (query)

Filter prompts after this date (ISO 8601)

endDatestring (query)

Filter prompts before this date (ISO 8601)

Response Example

json

{
  "success": true,
  "data": {
    "prompts": [
      {
        "promptHash": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
        "author": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "activityPoints": 25,
        "mintedAt": "2024-12-20T10:30:00Z",
        "txHash": "0x7890abcdef1234567890abcdef1234567890abcdef1234567890abcdef123456",
        "blockNumber": 12345680,
        "status": "confirmed"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 45230,
      "pages": 905
    }
  }
}

GET/v1/account/info

Get your account information including tier, billing details, and API key metadata.

Authentication: Requires x-api-key header

Parameters

x-api-keystring (header)Required

Your PZERO API key

Response Example

json

{
  "success": true,
  "data": {
    "customerId": "cus_abcd1234",
    "email": "your-company@example.com",
    "companyName": "Your AI Company",
    "tier": "pro",
    "billing": {
      "status": "active",
      "currentPeriodStart": "2024-12-01T00:00:00Z",
      "currentPeriodEnd": "2024-12-31T23:59:59Z"
    },
    "apiKeys": [
      {
        "keyId": "key_abc123",
        "prefix": "pzero_live_sk_",
        "name": "Production API Key",
        "createdAt": "2024-11-01T00:00:00Z",
        "lastUsedAt": "2024-12-25T10:30:00Z",
        "status": "active"
      }
    ]
  }
}

GET/v1/stats/summary

Get aggregate statistics for your account including total prompts minted, total rewards distributed, and trends.

Authentication: Requires x-api-key header

Parameters

x-api-keystring (header)Required

Your PZERO API key

periodstring (query)

Time period: "day", "week", "month", "year" (default: "month")

Response Example

json

{
  "success": true,
  "data": {
    "period": "month",
    "totalPromptsMinted": 45230,
    "totalActivityPointsDistributed": 1130750,
    "uniqueUsers": 8234,
    "trends": {
      "promptsPerDay": [
        { "date": "2024-12-01", "count": 1523 },
        { "date": "2024-12-02", "count": 1678 },
        { "date": "2024-12-03", "count": 1450 }
      ],
      "averagePromptsPerDay": 1508
    },
    "topUsers": [
      {
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "promptCount": 342,
        "totalRewards": 8550
      }
    ]
  }
}

GET/v1/stats/users

Retrieve unique minted user counts and chain-level distribution for the selected period. Powers the dashboard 'Minted users' module.

Authentication: Requires x-api-key header

Parameters

periodstring (query)

"7d", "30d", or "90d" (default 30d)

startstring (query)

Override start timestamp (ISO 8601)

endstring (query)

Override end timestamp (ISO 8601)

Response Example

json

{
  "success": true,
  "data": {
    "period": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-30T23:59:59Z",
      "days": 30
    },
    "uniqueAuthors": 482,
    "previousUniqueAuthors": 420,
    "deltaPercentage": 14.76,
    "chainBreakdown": [
      { "chainId": "8453", "authors": 320 },
      { "chainId": "137", "authors": 110 },
      { "chainId": "1750", "authors": 52 }
    ]
  }
}

When to Use Gateway Endpoints Directly

•Custom Analytics Dashboard: Build detailed analytics for your internal teams
•Quota Monitoring: Track usage and set up alerts before hitting limits
•Audit & Compliance: Export prompt history for compliance or auditing purposes
•User Leaderboards: Display top contributors in your application

Note: For most integrations, the boilerplate handles everything automatically. Only use direct Gateway endpoints if you need advanced analytics or custom features.

PZERO Gateway Internal API (For Reference)

The boilerplate communicates with the PZERO Gateway to get mint authorizations. This is handled automatically by the boilerplate, but here's what happens under the hood:

POST /v1/authorize/mint

Internal endpoint used by the boilerplate to request authorization signatures from PZERO Gateway.

Request to PZERO Gateway

POST https://pm-gateway.projectzero.io/v1/authorize/mint
Headers:
  x-api-key: pzero_live_your_api_key_here
  Content-Type: application/json

Body:
{
  "promptHash": "0x1a2b3c4d5e6f7890...",
  "author": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "activityPoints": 25
}

Response from PZERO Gateway

{
  "success": true,
  "signature": "0xabcdef1234567890...",
  "nonce": 42,
  "expiresAt": "2024-12-25T12:00:00Z"
}

Privacy Note: The PZERO Gateway only receives the irreversible keccak256 hash—never the full prompt text. Even ProjectZero cannot determine the original prompt content.