Datasets
API Schema

API Schema

The Mflo x402 marketplace provides access to various datasets through a standardized API. Each dataset includes schema definitions, pricing information, and sample data.

API Endpoints

Base URL

http://localhost:4000/api  # Local development

Authentication

All paid endpoints use x402 payment authentication. Free endpoints require no authentication.

Dataset API Routes

GET /datasets

Free Access - List all available datasets

{
  "data": {
    "datasets": [
      {
        "id": "binance-crypto-prices",
        "name": "Cryptocurrency Price Data",
        "description": "Real-time cryptocurrency prices from Binance exchange",
        "price": 50,
        "provider": "Binance",
        "type": "CSV",
        "size": 1228,
        "tags": ["cryptocurrency", "prices", "real-time", "binance"],
        "lastUpdated": "2024-05-22T10:00:00Z"
      }
    ]
  }
}

GET /datasets/providers

Free Access - Get all data providers

{
  "data": {
    "providers": ["Binance", "CoinGecko", "Weather API", "Sample Data"]
  }
}

GET /datasets/:id

Payment Required - Get detailed dataset information

  • Cost: 0.5 mUSDC (0.50 USD equivalent)
{
  "data": {
    "dataset": {
      "id": "binance-crypto-prices",
      "name": "Cryptocurrency Price Data", 
      "description": "Real-time cryptocurrency prices from Binance exchange",
      "price": 50,
      "provider": "Binance",
      "type": "CSV",
      "size": 1228,
      "tags": ["cryptocurrency", "prices", "real-time", "binance"],
      "lastUpdated": "2024-05-22T10:00:00Z",
      "schema": {
        "type": "text/csv",
        "columns": [
          { "name": "symbol", "type": "string" },
          { "name": "price", "type": "number" },
          { "name": "volume_24h", "type": "number" },
          { "name": "timestamp", "type": "string" }
        ]
      }
    }
  }
}

GET /datasets/:id/preview

Free Access - Get dataset preview/sample

{
  "data": {
    "preview": "symbol,price,volume_24h,timestamp\nBTCUSDT,68123.45,34567.89,2024-05-22T10:00:00Z"
  }
}

POST /datasets/:id

Payment Required - Request dataset access

  • Cost: 50 mUSDC per dataset

Returns authorization token for subsequent downloads.

GET /datasets/:id/download

Payment Required - Download full dataset

  • Cost: 50 mUSDC per download
  • Authorization: Requires payment or valid auth token

Payment Flow

1. Request Protected Resource

curl http://localhost:4000/api/datasets/binance-crypto-prices \
  -H "Content-Type: application/json"

Response (402 Payment Required):

{
  "error": "Payment required",
  "paymentRequired": {
    "paymentRequirements": [
      {
        "scheme": "exact",
        "network": "localhost", 
        "payTo": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
        "maxAmountRequired": "50000000"
      }
    ]
  }
}

2. Submit Payment

curl http://localhost:4000/api/datasets/binance-crypto-prices \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Payment: eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJsb2NhbGhvc3QiLCJwYXlsb2FkIjp7ImZyb20iOiIweDcwOTk3OTcwQzUxODEyZGMzQTAxMEM3ZDAxYjUwZTBkMTdkYzc5QzgiLCJ0byI6IjB4NzA5OTc5NzBDNTE4MTJkYzNBMDEwQzdkMDFiNTBlMGQxN2RjNzlDOCIsInZhbHVlIjoiNTAwMDAwMDAiLCJ2YWxpZEFmdGVyIjoiMCIsInZhbGlkQmVmb3JlIjoiMTcxNjM4NzYwMCIsIm5vbmNlIjoiMHgxMjM0NTY3ODkwYWJjZGVmIn0sInNpZ25hdHVyZSI6IjB4YWJjZGVmIn0="

Response (200 Success):

{
  "data": {
    "dataset": { /* dataset details */ },
    "authorizationToken": "auth_token_for_downloads"
  }
}

Error Codes

CodeMessageDescription
200OKRequest successful
402Payment RequiredPayment needed for resource access
404Not FoundDataset ID not found
400Bad RequestInvalid request format
500Internal Server ErrorServer processing error

Data Formats

CSV Format

  • Content-Type: text/csv
  • Encoding: UTF-8
  • Delimiter: Comma (,)
  • Headers: First row contains column names

JSON Format

  • Content-Type: application/json
  • Encoding: UTF-8
  • Structure: Well-formed JSON objects or arrays

Rate Limiting

  • Free endpoints: No rate limiting
  • Paid endpoints: Rate limited by payment (pay-per-request)
  • Download endpoints: One download per payment authorization
Available DatasetsHyperliquid