Skip to main content

Creating a Client

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

const client = createClient({
  endpoint: 'https://api.onchaindb.io',
  appId: 'your-app-id',
  appKey: 'your-app-key',      // For writes
  userKey: 'your-user-key',    // Optional: For Auto-Pay
  timeout: 30000,              // Request timeout (ms)
  retryCount: 3,               // Retry attempts
  retryDelay: 1000,            // Retry delay (ms)
});

Core Operations

store

Store data on blockchain with x402 payment flow.
const result = await client.store(
  { collection: 'users', data: [{ name: 'Alice' }] },
  async (quote) => {
    const txHash = await wallet.pay(quote.brokerAddress, quote.totalCostTia);
    return { txHash, network: 'mocha-4' };
  },
  true // waitForConfirmation
);

query

Query data with filters.
const result = await client.query({
  collection: 'users',
  where: { active: true },
  limit: 10
});

getPricingQuote

Get cost estimate before operations.
const quote = await client.getPricingQuote({
  app_id: 'my_app',
  operation_type: 'write',
  size_kb: 10,
  collection: 'users'
});

console.log('Cost:', quote.total_cost, 'TIA');

health

Health check.
const health = await client.health();
console.log('Status:', health.status);

Prisma-Style CRUD

createDocument

Create document with auto ID/timestamps.
const doc = await client.createDocument(
  'users',
  { name: 'Alice', email: 'alice@example.com' },
  paymentProof
);

findUnique

Find single document.
const doc = await client.findUnique('users', { email: 'alice@example.com' });

findMany

Find multiple documents.
const docs = await client.findMany(
  'users',
  { active: true },
  { limit: 10, offset: 0, sort: { field: 'createdAt', order: 'desc' } }
);

updateDocument

Update document.
const doc = await client.updateDocument(
  'users',
  { email: 'alice@example.com' },
  { name: 'Alice Smith' },
  paymentProof
);

deleteDocument

Soft delete document.
const deleted = await client.deleteDocument(
  'users',
  { email: 'alice@example.com' },
  paymentProof
);

countDocuments

Count matching documents.
const count = await client.countDocuments('users', { active: true });

Query Builder

queryBuilder

Create fluent query builder.
const builder = client.queryBuilder();

const users = await builder
  .collection('users')
  .whereField('active').isTrue()
  .orderBy('createdAt', 'desc')
  .limit(10)
  .execute();

Task Management

getTaskStatus

Get task status.
const status = await client.getTaskStatus(ticketId);
console.log('Status:', status.status);

waitForTaskCompletion

Wait for task.
const task = await client.waitForTaskCompletion(
  ticketId,
  2000,    // Poll every 2 seconds
  300000   // Max wait 5 minutes
);

Events (TypeScript Only)

The TypeScript SDK supports event-based transaction tracking:
client.on('transaction:queued', (ticket) => { ... });
client.on('transaction:pending', (tx) => { ... });
client.on('transaction:confirmed', (tx) => { ... });
client.on('transaction:failed', (tx) => { ... });
client.on('error', (error) => { ... });

Next Steps