Skip to main content
PriceIndex is a special index type that changes how payments work, enabling revenue-sharing business models for applications built on OnchainDB.

Traditional vs PriceIndex Payment

AspectTraditional (BTree/Hash)PriceIndex
Cost basisData sizeField value
Formulacost = data_size_kb * ratecost = field_value
Revenue sharingNoneAutomatic
Example10 KB order costs ~0.001 TIA$100 order costs 100 TIA

How It Works

User Creates Order
  totalPrice: 100000000 utia (100 TIA)
           |
 Payment Required: 100 TIA
           |
 Automatic Revenue Split (Server-Side)
           |
      +----+----+
      |         |
   70 TIA    30 TIA
   App       Platform
  Wallet   (OnchainDB)

Creating a PriceIndex

const db = client.database('your-app-id');

// Create PriceIndex on totalPrice field
await db.createIndex({
  name: 'idx_orders_totalPrice',
  collection: 'orders',
  field_name: 'totalPrice',
  index_type: 'Price'
});

// Revenue split is configured server-side
// Typically: 70% to app wallet, 30% to platform

Using PriceIndex in Applications

// Calculate order total
const orderTotal = items.reduce((sum, item) =>
  sum + (item.price * item.quantity), 0
);

// Create order with PriceIndex payment
await client.createDocument(
  'orders',
  {
    customerAddress: userWallet,
    items: orderItems,
    totalPrice: orderTotal, // This field has PriceIndex!
    status: 'confirmed'
  },
  {
    payment_mode: 'pay_on_write',
    payment_tx_hash: userPaymentTx,
    user_address: userWallet,
    broker_address: brokerAddress,
    amount_utia: orderTotal  // User pays order total, not storage cost
  }
);

// Backend automatically:
// 1. Detects PriceIndex on totalPrice field
// 2. Uses totalPrice value as payment amount
// 3. Splits payment automatically (e.g., 70% app, 30% platform)
// 4. Credits app wallet balance

Use Cases

PriceIndex is perfect for:
Use CasePriceIndex Field
E-commerceorderTotal
TicketingticketPrice
MarketplacetransactionAmount
SubscriptionsplanPrice
Service feesfeeAmount
Not suitable for:
  • Product catalogs (use BTree for filtering by price range)
  • Free/public data storage
  • Internal analytics data
  • User-generated content without pricing

Complete E-commerce Example

import { createClient } from '@onchaindb/sdk';

const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'my-store',
  appKey: process.env.ONCHAINDB_APP_KEY
});

// Setup: Create collections with indexes
async function setupStore() {
  const db = client.database('my-store');

  // Products - use btree for price range queries
  await db.createIndex({
    name: 'idx_products_category',
    collection: 'products',
    field_name: 'category',
    index_type: 'hash'
  });

  await db.createIndex({
    name: 'idx_products_price',
    collection: 'products',
    field_name: 'price',
    index_type: 'btree'
  });

  // Orders - use PriceIndex for payment-based pricing!
  await db.createIndex({
    name: 'idx_orders_customerId',
    collection: 'orders',
    field_name: 'customerId',
    index_type: 'hash'
  });

  await db.createIndex({
    name: 'idx_orders_totalPrice',
    collection: 'orders',
    field_name: 'totalPrice',
    index_type: 'Price' // <-- PriceIndex!
  });
}

// Checkout: Create order with PriceIndex payment
async function checkout(cart, userWallet, paymentTxHash) {
  const orderTotal = cart.items.reduce(
    (sum, item) => sum + (item.price * item.quantity),
    0
  );

  const order = await client.createDocument(
    'orders',
    {
      customerId: userWallet,
      items: cart.items,
      totalPrice: orderTotal,
      status: 'confirmed',
      createdAt: new Date().toISOString()
    },
    {
      payment_tx_hash: paymentTxHash,
      user_address: userWallet,
      broker_address: process.env.BROKER_ADDRESS,
      amount_utia: orderTotal
    }
  );

  return order;
}

Checking App Wallet Balance

Your application’s revenue share is credited to the app wallet balance:
// Check app wallet balance
const response = await fetch(
  `${endpoint}/api/apps/${appId}/wallet/balance`
);
const balance = await response.json();

console.log('App balance:', balance.amount_utia, 'utia');
console.log('App balance:', balance.amount_utia / 1_000_000, 'TIA');

Revenue Split Configuration

The revenue split is configured server-side and is typically:
  • 70% to the application wallet
  • 30% to the platform (OnchainDB)
Revenue split percentages are not user-configurable. Contact OnchainDB support for custom arrangements.

Next Steps