Data Marketplace API

Endpoints for the PRIV data marketplace where users can buy and sell anonymized data.

All marketplace endpoints require authentication. Purchases require a user API key with linked wallet.

List Data Listings

GET/api/v1/data/listings

Browse available data listings in the marketplace.

Query Parameters

Parameter	Type	Required	Description
`data_type`	`string`	No	Filter by type: `browsing`, `defi`, `nft`, `social`, `location`
`min_price`	`number`	No	Minimum price in PRIV
`max_price`	`number`	No	Maximum price in PRIV
`limit`	`number`	No	Results per page (default: 20, max: 100)
`offset`	`number`	No	Pagination offset (default: 0)

Response

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "lst_abc123",
        "seller_id": "usr_xyz789",
        "title": "DeFi Trading Patterns - Q1 2024",
        "description": "Anonymized swap data from major DEXs",
        "data_type": "defi",
        "price_priv": 50,
        "sample_data": {
          "preview": true,
          "fields": ["timestamp", "event_type", "token_pair", "amount_range"]
        },
        "total_records": 10000,
        "is_active": true,
        "created_at": "2024-01-15T00:00:00.000Z",
        "updated_at": "2024-01-15T00:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

Data Types

Type	Description
`browsing`	Web browsing patterns and interests
`defi`	DeFi trading and swap data
`nft`	NFT collection and trading patterns
`social`	Social media engagement data
`location`	Anonymized location patterns

Example

curl "https://api.privlabs.io/v1/data/listings?data_type=defi&max_price=100&limit=10" \
  -H "Authorization: Bearer pk_live_xxx"

Purchase Data

POST/api/v1/data/purchase

Purchase access to a data listing using PRIV tokens.

Request Body

{
  "listing_id": "lst_abc123"
}

Request Fields

Field	Type	Required	Description
`listing_id`	`string`	Yes	UUID of the listing to purchase

Response

{
  "success": true,
  "data": {
    "purchase_id": "pur_xyz789",
    "listing_id": "lst_abc123",
    "listing_title": "DeFi Trading Patterns - Q1 2024",
    "price_paid": 50,
    "access_token": "dat_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "expires_at": "2024-02-15T00:00:00.000Z",
    "status": "completed",
    "message": "Purchase successful! Use the access token to retrieve data."
  }
}

Response Fields

Field	Type	Description
`purchase_id`	`string`	Unique purchase identifier
`listing_id`	`string`	Purchased listing ID
`price_paid`	`number`	Amount paid in PRIV
`access_token`	`string`	Token to access the purchased data
`expires_at`	`string`	Access expiration (30 days from purchase)
`status`	`string`	Purchase status: `completed`, `pending`, `failed`

Purchase Requirements

User must have sufficient PRIV balance
Cannot purchase own listings
Cannot purchase same listing twice while access is active

Purchases are atomic and cannot be reversed. Ensure you have reviewed the listing details before purchasing.

Error Responses

Code	Message	Description
400	`Insufficient PRIV balance`	User doesn't have enough PRIV
400	`Cannot purchase your own data listing`	Seller cannot buy own data
400	`You already have active access`	Already purchased and not expired
404	`Data listing not found`	Invalid listing ID

JavaScript Example

Complete Purchase Flow

// 1. Browse listings
const listingsRes = await fetch('/api/v1/data/listings?data_type=defi&limit=10', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});

const { data: { listings } } = await listingsRes.json();
console.log('Available listings:', listings.length);

// 2. Select and purchase a listing
const selectedListing = listings[0];

const purchaseRes = await fetch('/api/v1/data/purchase', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${userToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    listing_id: selectedListing.id,
  }),
});

const purchase = await purchaseRes.json();

if (purchase.success) {
  console.log('Purchase successful!');
  console.log('Access token:', purchase.data.access_token);
  console.log('Expires:', purchase.data.expires_at);
} else {
  console.error('Purchase failed:', purchase.error.message);
}

Security Features

The purchase endpoint implements multiple safeguards:

Feature	Description
Atomic Transactions	Balance deduction and purchase creation are atomic
Duplicate Prevention	Database constraints prevent double purchases
Race Condition Protection	Optimistic locking prevents concurrent purchase issues
Idempotency	Same request within 30s window returns same result

Data Access

After purchase, use the access_token to retrieve the data through the Data Wallet Marketplace endpoints:

Listings: /api/v1/marketplace/wallet/listings/{id}
Purchases: /api/v1/marketplace/wallet/purchases/{id}
Download: /api/v1/marketplace/wallet/purchases/{id}/download

See the Marketplace API for details on accessing purchased data.

Data Marketplace API

On this page