Collections

Qwery's MongoDB schema is designed for efficiency, with denormalization where appropriate to reduce joins and improve query speed. users This collection stores user profiles, including wallet details and role-specific data.

{
  _id: ObjectId,
  wallet_address: "9xQeWvG816bUx...",  // Primary identifier, indexed for fast lookups
  wallet_provider: "phantom",  // e.g., "phantom", "solflare", "backpack"
  username: "dev_alex",  // Optional display name
  account_type: "provider",  // Enum: "provider", "consumer", "both" to define access levels
  subscription_tier: "pro",  // Enum: "free", "pro", "enterprise" for feature gating
  created_at: ISODate,  // Timestamp for account creation
  provider_data: {  // Nested object for provider-specific metrics
    total_revenue_usdc: 1250.50,  // Cumulative earnings in USDC
    total_api_calls: 25420  // Total monetized calls processed
  },
  consumer_data: {  // Nested object for consumer-specific tracking
    total_spent_usdc: 87.25,  // Cumulative spending in USDC
    spending_limits: { daily: 100.0, monthly: 1000.0 }  // Configurable caps to prevent overspending
  }
}

projects Represents API monetization configurations, linking to users and defining operational parameters.

{
  _id: ObjectId,
  project_id: "qwery_proj_abc123",  // Unique string ID for external references
  owner_id: ObjectId,  // Reference to users._id
  name: "Sentiment Analyzer Pro",  // Human-readable project name
  slug: "sentiment-analyzer-pro",  // URL-friendly identifier, unique index
  api_config: {  // Detailed API setup
    base_url: "https://sentiment-api.com",  // Backend URL for proxying
    endpoints: [  // Array of monetized routes
      { path: "/analyze", method: "POST", price_usdc: 0.05, free_tier: { calls_per_month: 100 } }
    ]
  },
  qwery_endpoints: {  // Generated proxy URLs
    proxy: "https://api.qwery.xyz/v1/sentiment-analyzer-pro"
  },
  keys: {  // Authentication credentials
    public_key: "QWERY_pk_live_...",  // For client-side use
    secret_key_hash: "$2b$10$..."  // Bcrypt hash of secret key for secure storage
  },
  solana: {  // Blockchain-specific configs
    revenue_wallet: "9xQeWvG816bUx...",  // Payout destination
    auto_withdraw: true  // Flag for automatic transfers
  },
  stats: {  // Aggregated performance data
    total_calls: 5420,  // Lifetime call count
    total_revenue_usdc: 271.00,  // Lifetime earnings
    success_rate: 0.998  // Ratio of successful to total calls
  },
  status: "active"  // Enum: "active", "paused", "archived"
}

transactions Logs individual API calls and payments for auditing and analytics.

{
  _id: ObjectId,
  transaction_id: "qwery_tx_abc123",  // Unique internal ID
  solana: {  // On-chain details
    signature: "5Kn9QpJvYnR3mHxW...",  // Solana tx sig, unique index
    block: 245678901,  // Block number for reference
    timestamp: ISODate  // On-chain confirmation time
  },
  consumer_id: ObjectId,  // Link to users._id
  provider_id: ObjectId,  // Link to users._id
  api_project_id: ObjectId,  // Link to projects._id
  payment: {  // Financial breakdown
    amount_usdc: 0.05,  // Total paid by consumer
    platform_fee_usdc: 0.005,  // Qwery's share
    provider_revenue_usdc: 0.045  // Provider's share
  },
  api_call: {  // Request/response metadata
    endpoint: "/analyze",  // Proxied path
    method: "POST",  // HTTP method
    request_body: { /* redacted / optionally stored based on privacy settings */ },
    response_body: { /* optional, truncated for storage efficiency */ },
    response_time_ms: 245,  // End-to-end latency
    status_code: 200  // HTTP response code
  },
  status: "completed",  // Enum: "pending", "completed", "failed", "refunded"
  created_at: ISODate  // Insertion timestamp
}

solana_tx_cache A TTL-based collection for quick replay checks.

{
  signature: "5Kn9QpJvYnR3mHxW...",  // Solana tx sig, primary key
  used_at: ISODate,  // When it was first seen
  used_in_transaction: "qwery_tx_abc123",  // Link to transactions.transaction_id
  expires_at: ISODate  // Auto-expire after e.g., 24 hours
}

Payment Records (Your DB):

{
  "payment_id": "pay_abc123",
  "user_id": "usr_xyz",
  "amount": 0.01,
  "token": "SOL",
  "recipient": "merchant_wallet",
  "network": "solana",
  "tx_signature": "2ZE7s...",
  "status": "completed",
  "created_at": "2024-01-01T00:00:00Z",
  "settled_at": "2024-01-01T00:00:03Z"
}

User Access Records (Your DB):

{
  "user_id": "usr_xyz",
  "resource_id": "premium_content_1",
  "payment_id": "pay_abc123",
  "granted_at": "2024-01-01T00:00:03Z",
  "expires_at": "2024-02-01T00:00:00Z"
}

Token Gateway Tiers (Your Config):

{
  "tier_id": "gold",
  "name": "Gold Membership",
  "token_address": "token_mint_address",
  "min_balance": 1000,
  "features": ["api_access", "premium_content"]
}