User API

Manage user balances, consent preferences, reputation, and earnings with the PRIV Protocol User API.

Endpoints for managing user data including PRIV token balances, consent preferences, reputation scores, and earnings.

All user endpoints require authentication. Users can only access their own data unless using a service API key.

Get Balance

GET/api/v1/user/balance

Get the PRIV token balance and earnings summary for a user.

Query Parameters

Parameter	Type	Required	Description
`user_id`	`string`	No	User ID (defaults to authenticated user)
`wallet_address`	`string`	No	Query by wallet address
`anonymous_id`	`string`	No	Query by anonymous ID

Users can only query their own balance. Service API keys can query any user.

Response

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "anonymous_id": "anon_456",
    "priv_balance": 1250.50,
    "earned_total": 2500.00,
    "pending_rewards": 150.25,
    "data_sharing_enabled": true
  }
}

Response Fields

Field	Type	Description
`user_id`	`string`	User identifier
`wallet_address`	`string`	Connected wallet address (if any)
`anonymous_id`	`string`	Anonymous identifier
`priv_balance`	`number`	Current PRIV token balance
`earned_total`	`number`	Lifetime earnings
`pending_rewards`	`number`	Unclaimed rewards
`data_sharing_enabled`	`boolean`	Whether data sharing is enabled

Example

curl "https://api.priv.io/v1/user/balance" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

GET/api/v1/user/consent

Get the current consent preferences for a user.

Query Parameters

Parameter	Type	Required	Description
`user_id`	`string`	No	User ID (defaults to authenticated user)
`anonymous_id`	`string`	No	Anonymous identifier

Response

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "anonymous_id": "anon_456",
    "preferences": {
      "analytics": true,
      "marketing": false,
      "data_sharing": true,
      "personalization": true
    },
    "last_updated": "2024-01-15T10:30:00Z"
  }
}

Default Preferences

For users without saved preferences, defaults are returned:

{
  "analytics": false,
  "marketing": false,
  "data_sharing": false,
  "personalization": false
}

POST/api/v1/user/consent

Update consent preferences for a user. Creates a new user record if one does not exist.

Request Body

{
  "preferences": {
    "analytics": true,
    "marketing": false,
    "data_sharing": true,
    "personalization": true
  },
  "anonymous_id": "anon_456"
}

Request Fields

Field	Type	Required	Description
`preferences`	`object`	Yes	Consent preferences object
`preferences.analytics`	`boolean`	Yes	Consent for analytics tracking
`preferences.marketing`	`boolean`	Yes	Consent for marketing communications
`preferences.data_sharing`	`boolean`	Yes	Consent for data sharing/monetization
`preferences.personalization`	`boolean`	Yes	Consent for personalized experiences
`anonymous_id`	`string`	No	Anonymous identifier to associate

Response

{
  "success": true,
  "data": {
    "user_id": "usr_abc123",
    "anonymous_id": "anon_456",
    "preferences": {
      "analytics": true,
      "marketing": false,
      "data_sharing": true,
      "personalization": true
    },
    "last_updated": "2024-01-15T10:30:00Z",
    "action": "updated"
  }
}

The action field indicates whether preferences were updated (existing user) or created (new user).

Example

curl -X POST "https://api.priv.io/v1/user/consent" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "analytics": true,
      "marketing": false,
      "data_sharing": true,
      "personalization": true
    }
  }'

Get Reputation

GET/api/v1/user/reputation

Get the user's reputation details including level, accuracy scores, and progress toward the next level.

Response

{
  "success": true,
  "data": {
    "reputation_level": 3,
    "level_name": "Expert",
    "total_tasks_completed": 150,
    "accuracy_score": 0.94,
    "gold_standard_accuracy": 0.97,
    "consensus_rate": 0.91,
    "staked_priv": 500,
    "next_level_requirements": {
      "level": 4,
      "level_name": "Master",
      "tasks_needed": 50,
      "accuracy_needed": 0.95,
      "stake_needed": 1000
    }
  }
}

Response Fields

Field	Type	Description
`reputation_level`	`number`	Current reputation level (1-5)
`level_name`	`string`	Human-readable level name
`total_tasks_completed`	`number`	Total labeling tasks completed
`accuracy_score`	`number`	Overall accuracy (0-1)
`gold_standard_accuracy`	`number`	Accuracy on gold standard tests (0-1)
`consensus_rate`	`number`	Agreement rate with other labelers (0-1)
`staked_priv`	`number`	Amount of PRIV staked
`next_level_requirements`	`object`	Requirements to reach the next level (if applicable)

Reputation Levels

Level	Name	Description
1	Novice	New user, limited task access
2	Apprentice	Basic tasks, building track record
3	Expert	Full task access, good accuracy
4	Master	High-value tasks, excellent accuracy
5	Elite	Top tier, validator privileges

Get Earnings

GET/api/v1/user/earnings

Get unified earnings history across all sources (browsing, labeling, data sales, staking).

Query Parameters

Parameter	Type	Required	Description
`source`	`string`	No	Filter by source: `browsing`, `labeling`, `data_sales`, `staking`, `referral`
`status`	`string`	No	Filter by status: `pending`, `confirmed`, `claimed`
`limit`	`number`	No	Results per page (default: 20, max: 100)
`offset`	`number`	No	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "earnings": [
      {
        "id": "earn_abc123",
        "source": "labeling",
        "amount": 5.50,
        "status": "confirmed",
        "description": "Image classification task",
        "created_at": "2024-01-15T10:30:00Z",
        "confirmed_at": "2024-01-15T12:00:00Z",
        "claimed_at": null,
        "reference_id": "task_xyz789"
      },
      {
        "id": "earn_def456",
        "source": "browsing",
        "amount": 0.25,
        "status": "pending",
        "description": "Daily browsing reward",
        "created_at": "2024-01-15T00:00:00Z",
        "confirmed_at": null,
        "claimed_at": null,
        "reference_id": null
      }
    ],
    "summary": {
      "total_earned": 1250.50,
      "total_pending": 45.25,
      "total_confirmed": 205.00,
      "total_claimed": 1000.25,
      "by_source": {
        "browsing": 450.00,
        "labeling": 600.50,
        "data_sales": 150.00,
        "staking": 50.00
      }
    },
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0
    }
  }
}

Earnings Sources

Source	Description
`browsing`	Passive earnings from browser extension/mobile app
`labeling`	Rewards for completing labeling tasks
`data_sales`	Revenue from selling data in the marketplace
`staking`	Staking rewards
`referral`	Referral bonuses

Example: Filter by Source

curl "https://api.priv.io/v1/user/earnings?source=labeling&status=confirmed" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Claim Earnings

POST/api/v1/user/earnings/claim

Claim pending earnings and initiate transfer to your wallet.

Request Body

{
  "earning_ids": ["earn_abc123", "earn_def456"],
  "claim_all": false
}

Request Fields

Field	Type	Required	Description
`earning_ids`	`string[]`	No	Specific earning IDs to claim
`claim_all`	`boolean`	No	Claim all confirmed earnings (default: false)

Either earning_ids or claim_all: true must be provided.

Response

{
  "success": true,
  "data": {
    "claim_id": "claim_xyz789",
    "total_claimed": 55.75,
    "earnings_count": 3,
    "tx_hash": null,
    "status": "pending",
    "message": "Successfully initiated claim for 55.75 PRIV from 3 earning(s). Claim ID: claim_xyz789"
  }
}

Response Fields

Field	Type	Description
`claim_id`	`string`	Unique identifier for this claim
`total_claimed`	`number`	Total PRIV amount claimed
`earnings_count`	`number`	Number of earnings included
`tx_hash`	`string`	Blockchain transaction hash (populated when processed)
`status`	`string`	Claim status: `pending`, `processing`, `completed`, `failed`

Example: Claim All

curl -X POST "https://api.priv.io/v1/user/earnings/claim" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"claim_all": true}'

Example: Claim Specific Earnings

curl -X POST "https://api.priv.io/v1/user/earnings/claim" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "earning_ids": ["earn_abc123", "earn_def456"]
  }'

JavaScript Examples

Complete User Flow

// Get user balance and earnings
async function getUserDashboard() {
  const [balanceRes, earningsRes, reputationRes] = await Promise.all([
    fetch('https://api.priv.io/v1/user/balance', {
      headers: { 'Authorization': `Bearer ${token}` },
    }),
    fetch('https://api.priv.io/v1/user/earnings?limit=5', {
      headers: { 'Authorization': `Bearer ${token}` },
    }),
    fetch('https://api.priv.io/v1/user/reputation', {
      headers: { 'Authorization': `Bearer ${token}` },
    }),
  ]);

  const [balance, earnings, reputation] = await Promise.all([
    balanceRes.json(),
    earningsRes.json(),
    reputationRes.json(),
  ]);

  return {
    balance: balance.data.priv_balance,
    pendingRewards: balance.data.pending_rewards,
    recentEarnings: earnings.data.earnings,
    totalEarned: earnings.data.summary.total_earned,
    reputationLevel: reputation.data.reputation_level,
    levelName: reputation.data.level_name,
  };
}

// Claim all available earnings
async function claimAllEarnings() {
  const response = await fetch('https://api.priv.io/v1/user/earnings/claim', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ claim_all: true }),
  });

  const data = await response.json();

  if (data.success) {
    console.log(`Claimed ${data.data.total_claimed} PRIV`);
    return data.data.claim_id;
  }

  throw new Error(data.error.message);
}

User API

On this page