📡 API Reference

Complete reference for all SourceNet backend API endpoints, including authentication, marketplace, seller, buyer, and review endpoints.

Authentication Endpoints

POST /api/auth/salt

Get or create user salt for zkLogin authentication.

// Request
POST /api/auth/salt
Content-Type: application/json

{
  "sub": "105628270296738955803"
}

// Response
{
  "success": true,
  "salt": "129390938109283091283091283091"
}

POST /api/auth/zklogin

Authenticate user with Google JWT and zkLogin.

// Request
POST /api/auth/zklogin
Content-Type: application/json

{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "sui_address": "0x7b8a9c3d4e5f6a1b2c3d4e5f6a7b8c9d0e1f2a3b..."
}

// Response
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@gmail.com",
    "name": "John Doe",
    "suiAddress": "0x7b8a...",
    "createdAt": "2024-11-27T10:00:00Z"
  }
}

GET /api/auth/me

Get current authenticated user information.

// Request
GET /api/auth/me
Authorization: Bearer <token>

// Response
{
  "success": true,
  "user": {
    "id": "uuid",
    "email": "user@gmail.com",
    "name": "John Doe",
    "suiAddress": "0x7b8a...",
    "averageRating": 4.5,
    "totalPurchases": 10,
    "totalSales": 5
  }
}

Marketplace Endpoints

GET /api/marketplace/datapods

List all published DataPods with filtering and pagination.

// Request
GET /api/marketplace/datapods?category=finance&minPrice=1&maxPrice=10&page=1&limit=20

// Response
{
  "success": true,
  "datapods": [
    {
      "id": "uuid",
      "title": "Stock Market Data 2024",
      "description": "Daily stock prices for S&P 500...",
      "category": "finance",
      "priceSui": 5.0,
      "fileSize": 52428800,
      "averageRating": 4.8,
      "totalSales": 156,
      "seller": {
        "id": "uuid",
        "name": "Data Corp",
        "averageRating": 4.7
      },
      "createdAt": "2024-11-20T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "pages": 3
  }
}

GET /api/marketplace/datapods/:id

Get detailed information about a specific DataPod.

// Request
GET /api/marketplace/datapods/550e8400-e29b-41d4-a716-446655440000

// Response
{
  "success": true,
  "datapod": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Stock Market Data 2024",
    "description": "Daily stock prices for S&P 500 companies...",
    "category": "finance",
    "priceSui": 5.0,
    "fileSize": 52428800,
    "fileType": "text/csv",
    "schema": {
      "columns": ["date", "symbol", "open", "high", "low", "close", "volume"],
      "rowCount": 125000
    },
    "sampleData": [
      {
        "date": "2024-01-01",
        "symbol": "AAPL",
        "open": 182.15,
        "high": 185.33,
        "low": 181.50,
        "close": 184.40,
        "volume": 45678900
      }
    ],
    "averageRating": 4.8,
    "totalSales": 156,
    "seller": {
      "id": "uuid",
      "name": "Data Corp",
      "email": "contact@datacorp.com",
      "suiAddress": "0x...",
      "averageRating": 4.7
    },
    "createdAt": "2024-11-20T10:00:00Z",
    "updatedAt": "2024-11-25T15:30:00Z"
  }
}

Seller Endpoints

POST /api/seller/upload

Upload a new dataset file with metadata.

// Request
POST /api/seller/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <binary data>
metadata: {
  "title": "Stock Market Data 2024",
  "description": "Daily stock prices...",
  "category": "finance",
  "price": 5.0
}

// Response
{
  "success": true,
  "uploadId": "uuid",
  "preview": {
    "schema": {
      "columns": ["date", "symbol", "open", "high", "low", "close", "volume"],
      "rowCount": 125000
    },
    "sample": [...]
  }
}

POST /api/seller/publish

Publish an uploaded DataPod to the marketplace.

// Request
POST /api/seller/publish
Authorization: Bearer <token>
Content-Type: application/json

{
  "datapodId": "uuid"
}

// Response
{
  "success": true,
  "datapod": {
    "id": "uuid",
    "published": true,
    "publishedAt": "2024-11-27T12:00:00Z"
  }
}

GET /api/seller/datapods

List seller's own DataPods.

// Request
GET /api/seller/datapods?status=published&page=1&limit=10
Authorization: Bearer <token>

// Response
{
  "success": true,
  "datapods": [
    {
      "id": "uuid",
      "title": "Stock Market Data 2024",
      "published": true,
      "priceSui": 5.0,
      "totalSales": 156,
      "totalRevenue": 780.0,
      "averageRating": 4.8,
      "createdAt": "2024-11-20T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "pages": 1
  }
}

GET /api/seller/stats

Get seller analytics and statistics.

// Request
GET /api/seller/stats
Authorization: Bearer <token>

// Response
{
  "success": true,
  "stats": {
    "totalDatapods": 5,
    "publishedDatapods": 4,
    "totalSales": 234,
    "totalRevenue": 1170.0,
    "averageRating": 4.7,
    "recentSales": [
      {
        "datapodTitle": "Stock Market Data 2024",
        "amount": 5.0,
        "buyer": "buyer@example.com",
        "purchasedAt": "2024-11-27T11:30:00Z"
      }
    ]
  }
}

Buyer Endpoints

POST /api/buyer/purchase

Record a purchase after on-chain transaction.

// Request
POST /api/buyer/purchase
Authorization: Bearer <token>
Content-Type: application/json

{
  "datapod_id": "uuid",
  "payment_tx_digest": "0xabcd1234..."
}

// Response
{
  "success": true,
  "purchase": {
    "id": "uuid",
    "datapodId": "uuid",
    "buyerId": "uuid",
    "amountSui": 5.0,
    "paymentTxDigest": "0xabcd1234...",
    "status": "processing",
    "createdAt": "2024-11-27T12:00:00Z"
  }
}

GET /api/buyer/purchases

List buyer's purchases.

// Request
GET /api/buyer/purchases?page=1&limit=10
Authorization: Bearer <token>

// Response
{
  "success": true,
  "purchases": [
    {
      "id": "uuid",
      "datapod": {
        "id": "uuid",
        "title": "Stock Market Data 2024",
        "seller": {
          "name": "Data Corp"
        }
      },
      "amountSui": 5.0,
      "status": "completed",
      "purchasedAt": "2024-11-27T12:00:00Z",
      "completedAt": "2024-11-27T12:05:00Z"
    }
  ],
  "pagination": {
    "total": 10,
    "page": 1,
    "pages": 1
  }
}

GET /api/buyer/download/:purchaseId

Get download URL for a completed purchase.

// Request
GET /api/buyer/download/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

// Response
{
  "success": true,
  "downloadUrl": "https://api.sourcenet.example.com/download/eyJhbG...",
  "filename": "Stock Market Data 2024.csv",
  "size": 52428800,
  "expiresIn": 3600
}

Review Endpoints

POST /api/buyer/purchase/:purchaseId/review

Submit a review for a purchase.

// Request
POST /api/buyer/purchase/550e8400-e29b-41d4-a716-446655440000/review
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "comment": "Excellent dataset! Very comprehensive and well-structured."
}

// Response
{
  "success": true,
  "review": {
    "id": "uuid",
    "purchaseId": "uuid",
    "datapodId": "uuid",
    "buyerId": "uuid",
    "rating": 5,
    "comment": "Excellent dataset!...",
    "createdAt": "2024-11-27T13:00:00Z"
  }
}

GET /api/review/datapod/:datapodId

Get reviews for a specific DataPod.

// Request
GET /api/review/datapod/550e8400-e29b-41d4-a716-446655440000?page=1&limit=10

// Response
{
  "success": true,
  "reviews": [
    {
      "id": "uuid",
      "rating": 5,
      "comment": "Excellent dataset!...",
      "buyer": {
        "name": "John Doe"
      },
      "createdAt": "2024-11-27T13:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "pages": 3
  },
  "averageRating": 4.8
}

AI Endpoints

POST /api/ai/chat

Send a message to the AI assistant.

// Request
POST /api/ai/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "How do I create a DataPod?",
  "conversationId": "uuid", // optional
  "context": {
    "dataPodId": "uuid", // optional
    "page": "seller-dashboard"
  }
}

// Response
{
  "success": true,
  "data": {
    "conversationId": "uuid",
    "message": "To create a DataPod, navigate to the Seller Dashboard...",
    "timestamp": "2024-11-27T14:00:00Z",
    "tokens": {
      "prompt": 50,
      "completion": 100,
      "total": 150
    }
  }
}

Error Responses

All error responses follow this format:

{
  "success": false,
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": {} // optional
}

Common Error Codes

Rate Limiting