@onchaindb/sdk 0.4.0 → 0.4.2

package/skills.md

@@ -0,0 +1,1096 @@
+# OnChainDB Agent Skills - Pure cURL Commands
+
+Complete reference for working with OnChainDB using pure HTTP requests. No SDK required.
+
+## Environment Variables
+
+```bash
+export ONCHAINDB_ENDPOINT="https://api.onchaindb.com"
+export ONCHAINDB_APP_ID="your_app_id"
+export ONCHAINDB_APP_KEY="your_app_key"
+```
+
+---
+
+## 1. Collection Management
+
+### Create Collection
+
+Create a new collection with schema definition.
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "orderbook_snapshots",
+    "namespace": "hyperliquid",
+    "primary_column": "id",
+    "sort_column": "timestamp",
+    "schema_definition": {
+      "fields": {
+        "id": { "type": "string", "index": true, "unique": true },
+        "market": { "type": "string", "index": true },
+        "timestamp": { "type": "number", "index": true },
+        "mid_price": { "type": "number" },
+        "spread_bps": { "type": "number" },
+        "bids": { "type": "array" },
+        "asks": { "type": "array" },
+        "total_bid_liquidity_usd": { "type": "number" },
+        "total_ask_liquidity_usd": { "type": "number" },
+        "order_book_imbalance": { "type": "number" },
+        "data_source": { "type": "string" }
+      }
+    }
+  }'
+```
+
+### List Collections
+
+```bash
+curl -X GET "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+### Get Collection Details
+
+```bash
+curl -X GET "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+### Delete Collection
+
+```bash
+curl -X DELETE "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{ "force": true, "cascade": true }'
+```
+
+---
+
+## 2. Sharding Configuration
+
+### Update Collection Sharding
+
+Configure time-series sharding for high-volume collections.
+
+```bash
+curl -X PATCH "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots/sharding" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "keys": [
+      {
+        "field": "market",
+        "type": "hashed"
+      },
+      {
+        "field": "timestamp",
+        "type": "time_series",
+        "granularity": "hour"
+      }
+    ],
+    "enforce_in_queries": true,
+    "max_shard_size": 100000000
+  }'
+```
+
+**Sharding Strategies:**
+
+- **Time-series sharding**: Shard by timestamp (hour/day)
+- **Hashed sharding**: Distribute by market/symbol
+- **Combined**: Time + market for optimal distribution
+
+---
+
+## 3. Index Management
+
+### Create Index
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/indexes" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "orderbook_market_idx",
+    "collection": "orderbook_snapshots",
+    "field_name": "market",
+    "index_type": "btree",
+    "options": {
+      "unique": false
+    }
+  }'
+```
+
+### Create Composite Index
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/indexes" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "orderbook_market_time_idx",
+    "collection": "orderbook_snapshots",
+    "field_name": "market",
+    "index_type": "composite",
+    "fields": ["market", "timestamp"],
+    "options": {
+      "unique": false
+    }
+  }'
+```
+
+### List Indexes
+
+```bash
+# All indexes for an app
+curl -X GET "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/indexes" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+
+# Indexes for specific collection
+curl -X GET "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots/indexes" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+### Drop Index
+
+```bash
+curl -X DELETE "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots/indexes/orderbook_market_idx" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+---
+
+## 4. Data Ingestion (Store)
+
+### Store Single Record
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "data": [{
+      "id": "BTC_1735862400000",
+      "market": "BTC",
+      "timestamp": 1735862400000,
+      "mid_price": 98500.50,
+      "spread_bps": 2.5,
+      "bids": [
+        { "px": "98500.00", "sz": "1.5", "n": 3 },
+        { "px": "98499.00", "sz": "2.0", "n": 5 }
+      ],
+      "asks": [
+        { "px": "98501.00", "sz": "1.2", "n": 2 },
+        { "px": "98502.00", "sz": "1.8", "n": 4 }
+      ],
+      "total_bid_liquidity_usd": 295000.00,
+      "total_ask_liquidity_usd": 280000.00,
+      "order_book_imbalance": 0.026,
+      "data_source": "websocket"
+    }]
+  }'
+```
+
+### Store Batch Records
+
+Store multiple records in a single request (up to 1000 records recommended per batch).
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "data": [
+      {
+        "id": "BTC_1735862400000",
+        "market": "BTC",
+        "timestamp": 1735862400000,
+        "mid_price": 98500.50,
+        "spread_bps": 2.5,
+        "total_bid_liquidity_usd": 295000.00,
+        "total_ask_liquidity_usd": 280000.00,
+        "order_book_imbalance": 0.026
+      },
+      {
+        "id": "ETH_1735862400000",
+        "market": "ETH",
+        "timestamp": 1735862400000,
+        "mid_price": 3850.25,
+        "spread_bps": 3.0,
+        "total_bid_liquidity_usd": 180000.00,
+        "total_ask_liquidity_usd": 175000.00,
+        "order_book_imbalance": 0.014
+      }
+    ]
+  }'
+```
+
+**Response:**
+```json
+{
+  "ticket_id": "task_abc123",
+  "status": "queued",
+  "message": "Data queued for processing"
+}
+```
+
+### Check Store Task Status
+
+```bash
+curl -X GET "${ONCHAINDB_ENDPOINT}/tasks/task_abc123" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+---
+
+## 5. Data Querying
+
+### Simple Query - All Records
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {},
+    "select": {},
+    "limit": 100,
+    "offset": 0
+  }'
+```
+
+### Query with Filter - Single Field
+
+Query records for a specific market.
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "market": { "eq": "BTC" }
+    },
+    "select": {},
+    "limit": 100,
+    "offset": 0
+  }'
+```
+
+### Query with Time Range
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "market": { "eq": "BTC" } },
+        { "timestamp": { "gte": 1735862400000 } },
+        { "timestamp": { "lte": 1735948800000 } }
+      ]
+    },
+    "select": {
+      "market": true,
+      "timestamp": true,
+      "mid_price": true,
+      "spread_bps": true
+    },
+    "limit": 1000,
+    "offset": 0,
+    "sortBy": "timestamp"
+  }'
+```
+
+### Query with Pagination
+
+```bash
+# Page 1
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": { "market": { "eq": "BTC" } },
+    "select": {},
+    "limit": 9000,
+    "offset": 0,
+    "sortBy": "timestamp"
+  }'
+
+# Page 2
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": { "market": { "eq": "BTC" } },
+    "select": {},
+    "limit": 9000,
+    "offset": 9000,
+    "sortBy": "timestamp"
+  }'
+```
+
+### Query with Multiple Markets (IN operator)
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "market": { "in": ["BTC", "ETH", "SOL"] }
+    },
+    "select": {},
+    "limit": 1000,
+    "offset": 0
+  }'
+```
+
+### Query with Complex Conditions
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "market": { "in": ["BTC", "ETH"] } },
+        { "timestamp": { "gte": 1735862400000 } },
+        { "spread_bps": { "lt": 5.0 } },
+        { "order_book_imbalance": { "between": [-0.1, 0.1] } }
+      ]
+    },
+    "select": {
+      "market": true,
+      "timestamp": true,
+      "mid_price": true,
+      "spread_bps": true,
+      "order_book_imbalance": true
+    },
+    "limit": 500,
+    "sortBy": "timestamp"
+  }'
+```
+
+---
+
+## 6. Materialized Views
+
+### Create Materialized View
+
+Create aggregated view for market summary statistics.
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/views" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "market_summary",
+    "source_collections": ["orderbook_snapshots"],
+    "query": {
+      "select": [
+        "market",
+        "mid_price",
+        "spread_bps",
+        "total_bid_liquidity_usd",
+        "total_ask_liquidity_usd",
+        "timestamp"
+      ],
+      "group_by": ["market"],
+      "aggregate": {
+        "avg_mid_price": { "$avg": "mid_price" },
+        "avg_spread_bps": { "$avg": "spread_bps" },
+        "avg_bid_liquidity": { "$avg": "total_bid_liquidity_usd" },
+        "avg_ask_liquidity": { "$avg": "total_ask_liquidity_usd" },
+        "max_timestamp": { "$max": "timestamp" },
+        "total_snapshots": { "$count": "*" }
+      }
+    }
+  }'
+```
+
+### Create OHLC View (1-minute candles)
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/views" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "ohlc_1min_candles",
+    "source_collections": ["orderbook_snapshots"],
+    "query": {
+      "select": [],
+      "find": {},
+      "group_by": ["market", "timestamp"],
+      "aggregate": {
+        "open_price": { "$avg": "mid_price" },
+        "high_price": { "$max": "mid_price" },
+        "low_price": { "$min": "mid_price" },
+        "close_price": { "$avg": "mid_price" },
+        "avg_spread": { "$avg": "spread_bps" },
+        "total_bid_liquidity": { "$sum": "total_bid_liquidity_usd" },
+        "total_ask_liquidity": { "$sum": "total_ask_liquidity_usd" },
+        "snapshot_count": { "$count": "*" }
+      },
+      "sort_by": ["market", "timestamp"]
+    }
+  }'
+```
+
+### List All Views
+
+```bash
+curl -X GET "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/views" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+### Delete View
+
+```bash
+curl -X DELETE "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/views/market_summary" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}"
+```
+
+### Query Materialized View
+
+Query a view the same way as a regular collection.
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::market_summary",
+    "find": {},
+    "select": {},
+    "limit": 100
+  }'
+```
+
+---
+
+## 7. Data Aggregation Patterns
+
+### Pattern 1: OHLC Aggregation
+
+Aggregate orderbook snapshots into 1-minute OHLC candles.
+
+**Step 1: Fetch snapshots for a time range**
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "market": { "eq": "BTC" } },
+        { "timestamp": { "gte": 1735862400000 } },
+        { "timestamp": { "lte": 1735866000000 } }
+      ]
+    },
+    "select": {
+      "id": true,
+      "market": true,
+      "timestamp": true,
+      "mid_price": true,
+      "spread_bps": true,
+      "total_bid_liquidity_usd": true,
+      "total_ask_liquidity_usd": true
+    },
+    "sortBy": "timestamp",
+    "limit": 9000,
+    "offset": 0
+  }'
+```
+
+**Step 2: Aggregate client-side and store**
+
+```bash
+# After aggregating data into 1-minute candles client-side:
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::ohlc_1min",
+    "data": [{
+      "id": "BTC_1735862400000",
+      "timestamp_1min": 1735862400000,
+      "market": "BTC",
+      "open_mid": 98500.50,
+      "high_mid": 98550.00,
+      "low_mid": 98480.00,
+      "close_mid": 98520.25,
+      "avg_spread_bps": 2.8,
+      "avg_total_liquidity_usd": 575000.00,
+      "snapshot_count": 60
+    }]
+  }'
+```
+
+### Pattern 2: Liquidity Scoring
+
+Calculate liquidity metrics from orderbook data.
+
+**Fetch and aggregate:**
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "market": { "eq": "ETH" } },
+        { "timestamp": { "gte": 1735862400000 } },
+        { "timestamp": { "lt": 1735862700000 } }
+      ]
+    },
+    "select": {
+      "market": true,
+      "timestamp": true,
+      "mid_price": true,
+      "bids": true,
+      "asks": true,
+      "total_bid_liquidity_usd": true,
+      "total_ask_liquidity_usd": true
+    },
+    "sortBy": "timestamp",
+    "limit": 9000
+  }'
+```
+
+**Store liquidity scores:**
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::liquidity_scores",
+    "data": [{
+      "id": "ETH_1735862400000",
+      "market": "ETH",
+      "timestamp": 1735862400000,
+      "total_liquidity_usd": 355000.00,
+      "bid_liquidity_usd": 180000.00,
+      "ask_liquidity_usd": 175000.00,
+      "liquidity_imbalance": 0.014,
+      "depth_score": 85.5,
+      "support_levels": [3848.50, 3847.00, 3845.00],
+      "resistance_levels": [3851.00, 3852.50, 3855.00]
+    }]
+  }'
+```
+
+### Pattern 3: Market Correlation Analysis
+
+Calculate correlations between market pairs.
+
+```bash
+# Store correlation results
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::market_correlations",
+    "data": [{
+      "id": "BTC_ETH_1735862400000",
+      "timestamp": 1735862400000,
+      "market_pair": "BTC_ETH",
+      "correlation_1h": 0.85,
+      "correlation_24h": 0.78,
+      "correlation_7d": 0.82,
+      "covariance": 15.5,
+      "beta": 0.92
+    }]
+  }'
+```
+
+### Pattern 4: Volatility Metrics
+
+Calculate and store volatility across time windows.
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::volatility_metrics",
+    "data": [{
+      "id": "SOL_1735862400000",
+      "market": "SOL",
+      "timestamp": 1735862400000,
+      "volatility_5min": 0.012,
+      "volatility_15min": 0.018,
+      "volatility_1h": 0.025,
+      "price_range_5min": 2.50,
+      "avg_price_5min": 125.75
+    }]
+  }'
+```
+
+---
+
+## 8. Advanced Query Operators
+
+### Comparison Operators
+
+```bash
+# Greater than / Less than
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "mid_price": { "gt": 90000 } },
+        { "spread_bps": { "lt": 3.0 } }
+      ]
+    },
+    "select": {},
+    "limit": 100
+  }'
+```
+
+### Between Operator
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "mid_price": { "between": [95000, 100000] }
+    },
+    "select": {},
+    "limit": 100
+  }'
+```
+
+### String Operators
+
+```bash
+# Contains, starts with, ends with
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "or": [
+        { "market": { "contains": "BTC" } },
+        { "market": { "startsWith": "ETH" } },
+        { "data_source": { "endsWith": "socket" } }
+      ]
+    },
+    "select": {},
+    "limit": 100
+  }'
+```
+
+### Null Checks
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {
+      "and": [
+        { "order_book_imbalance": { "isNotNull": true } },
+        { "deletedAt": { "isNull": true } }
+      ]
+    },
+    "select": {},
+    "limit": 100
+  }'
+```
+
+---
+
+## 9. Historical Data Onboarding
+
+### Pattern: Bulk Historical Import
+
+For onboarding large historical datasets:
+
+**Step 1: Download and decompress data** (external to OnChainDB)
+**Step 2: Transform to JSON**
+**Step 3: Batch insert in chunks**
+
+```bash
+# Insert batch of 1000 records
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "data": [
+      { "id": "BTC_1735862400000", "market": "BTC", "timestamp": 1735862400000, ... },
+      { "id": "BTC_1735862460000", "market": "BTC", "timestamp": 1735862460000, ... },
+      ...
+      { "id": "BTC_1735922340000", "market": "BTC", "timestamp": 1735922340000, ... }
+    ]
+  }'
+```
+
+**Best Practices:**
+- Batch size: 500-1000 records per request
+- Use waitForConfirmation=true to ensure data is committed
+- Process hour-by-hour to manage memory
+- Use parallel requests for different markets
+
+---
+
+## 10. Query Result Operators
+
+### Available Operators in `find` Clause
+
+| Operator | Usage | Example |
+|----------|-------|---------|
+| `eq` | Equals | `{ "market": { "eq": "BTC" } }` |
+| `ne` | Not equals | `{ "market": { "ne": "BTC" } }` |
+| `gt` | Greater than | `{ "price": { "gt": 100000 } }` |
+| `gte` | Greater than or equal | `{ "price": { "gte": 100000 } }` |
+| `lt` | Less than | `{ "spread": { "lt": 5.0 } }` |
+| `lte` | Less than or equal | `{ "spread": { "lte": 5.0 } }` |
+| `in` | In array | `{ "market": { "in": ["BTC", "ETH"] } }` |
+| `notIn` | Not in array | `{ "status": { "notIn": ["deleted"] } }` |
+| `between` | Between range | `{ "price": { "between": [90000, 100000] } }` |
+| `contains` | String contains | `{ "market": { "contains": "BTC" } }` |
+| `startsWith` | String starts with | `{ "market": { "startsWith": "BTC" } }` |
+| `endsWith` | String ends with | `{ "source": { "endsWith": "socket" } }` |
+| `isNull` | Is null | `{ "deletedAt": { "isNull": true } }` |
+| `isNotNull` | Is not null | `{ "price": { "isNotNull": true } }` |
+
+### Logical Operators
+
+```bash
+# AND - all conditions must match
+{
+  "and": [
+    { "market": { "eq": "BTC" } },
+    { "timestamp": { "gte": 1735862400000 } }
+  ]
+}
+
+# OR - any condition must match
+{
+  "or": [
+    { "market": { "eq": "BTC" } },
+    { "market": { "eq": "ETH" } }
+  ]
+}
+
+# Nested conditions
+{
+  "and": [
+    {
+      "or": [
+        { "market": { "eq": "BTC" } },
+        { "market": { "eq": "ETH" } }
+      ]
+    },
+    { "timestamp": { "gte": 1735862400000 } }
+  ]
+}
+```
+
+---
+
+## 11. Complete Examples by Use Case
+
+### Use Case 1: Real-time Market Data Platform
+
+```bash
+# 1. Setup collection
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "orderbook_snapshots",
+    "namespace": "markets",
+    "primary_column": "id",
+    "sort_column": "timestamp"
+  }'
+
+# 2. Configure sharding
+curl -X PATCH "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/collections/orderbook_snapshots/sharding" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "keys": [
+      { "field": "market", "type": "hashed" },
+      { "field": "timestamp", "type": "time_series", "granularity": "hour" }
+    ],
+    "enforce_in_queries": true
+  }'
+
+# 3. Create indexes
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/indexes" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "orderbook_market_time_idx",
+    "collection": "orderbook_snapshots",
+    "field_name": "market",
+    "index_type": "composite",
+    "fields": ["market", "timestamp"]
+  }'
+
+# 4. Ingest real-time data
+curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "data": [...]
+  }'
+
+# 5. Query latest prices
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": { "market": { "eq": "BTC" } },
+    "sortBy": "timestamp",
+    "limit": 1
+  }'
+```
+
+### Use Case 2: Analytics Platform
+
+```bash
+# 1. Create OHLC view
+curl -X POST "${ONCHAINDB_ENDPOINT}/api/apps/${ONCHAINDB_APP_ID}/views" \
+  -H "Content-Type: application/json" \
+  -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+  -d '{
+    "name": "ohlc_1min",
+    "source_collections": ["orderbook_snapshots"],
+    "query": {
+      "group_by": ["market", "timestamp"],
+      "aggregate": {
+        "open": { "$first": "mid_price" },
+        "high": { "$max": "mid_price" },
+        "low": { "$min": "mid_price" },
+        "close": { "$last": "mid_price" }
+      }
+    }
+  }'
+
+# 2. Query aggregated data
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::ohlc_1min",
+    "find": {
+      "and": [
+        { "market": { "eq": "BTC" } },
+        { "timestamp": { "gte": 1735862400000 } }
+      ]
+    },
+    "limit": 1440
+  }'
+```
+
+---
+
+## 12. Error Handling
+
+### Common HTTP Status Codes
+
+- `200` - Success
+- `400` - Bad Request (invalid JSON or parameters)
+- `401` - Unauthorized (missing or invalid API key)
+- `402` - Payment Required (x402 protocol - payment needed)
+- `404` - Not Found (collection or view doesn't exist)
+- `429` - Too Many Requests (rate limited)
+- `500` - Internal Server Error
+
+### Sample Error Response
+
+```json
+{
+  "error": "Collection not found",
+  "code": "COLLECTION_NOT_FOUND",
+  "details": {
+    "collection": "orderbook_snapshots",
+    "app_id": "app_12345"
+  }
+}
+```
+
+---
+
+## 13. Best Practices
+
+### Performance Optimization
+
+1. **Use pagination for large datasets** (limit ≤ 9000 per request)
+2. **Create indexes on frequently queried fields**
+3. **Use composite indexes for multi-field queries**
+4. **Configure sharding for time-series data**
+5. **Use materialized views for expensive aggregations**
+6. **Batch inserts (500-1000 records per request)**
+
+### Query Optimization
+
+```bash
+# GOOD: Use indexed fields in filters
+{
+  "find": {
+    "and": [
+      { "market": { "eq": "BTC" } },        # indexed
+      { "timestamp": { "gte": 1735862400000 } }  # indexed
+    ]
+  }
+}
+
+# GOOD: Select only needed fields
+{
+  "select": {
+    "market": true,
+    "timestamp": true,
+    "mid_price": true
+  }
+}
+
+# BAD: Don't query without filters on large collections
+{
+  "find": {},  # This fetches everything!
+  "limit": 1000000
+}
+```
+
+### Data Modeling
+
+1. **Use unique IDs**: Combine fields like `${market}_${timestamp}`
+2. **Normalize timestamps**: Use Unix milliseconds
+3. **Denormalize for reads**: Duplicate data to avoid JOINs
+4. **Shard high-volume collections**: Time-series + hashed keys
+5. **Create aggregation collections**: Store pre-computed metrics
+
+---
+
+## 14. x402 Payment Protocol (Optional)
+
+OnChainDB supports x402 payment protocol for paid queries. If a request requires payment, you'll receive a 402 response:
+
+### Sample 402 Response
+
+```json
+{
+  "accepts": [{
+    "quoteId": "quote_abc123",
+    "network": "mocha-4",
+    "payTo": "celestia1abc...",
+    "maxAmountRequired": "1000000",
+    "token": { "symbol": "TIA", "decimals": 6 }
+  }]
+}
+```
+
+### Retry with Payment
+
+After paying via Celestia wallet:
+
+```bash
+curl -X POST "${ONCHAINDB_ENDPOINT}/list" \
+  -H "Content-Type: application/json" \
+  -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoibW9jaGEtNCIsInF1b3RlSWQiOiJxdW90ZV9hYmMxMjMiLCJwYXlsb2FkIjp7InR4SGFzaCI6IjB4Li4uIiwic2VuZGVyIjoiY2VsZXN0aWExeHl6In19" \
+  -d '{
+    "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+    "find": {},
+    "limit": 100
+  }'
+```
+
+---
+
+## 15. Shell Script Helpers
+
+### Batch Insert Loop
+
+```bash
+#!/bin/bash
+# Insert 1000 records per batch
+
+for i in {0..9}; do
+  start=$((i * 1000))
+  end=$(((i + 1) * 1000))
+
+  echo "Inserting batch $i (records $start-$end)..."
+
+  curl -X POST "${ONCHAINDB_ENDPOINT}/store" \
+    -H "Content-Type: application/json" \
+    -H "X-App-Key: ${ONCHAINDB_APP_KEY}" \
+    -d @batch_${i}.json
+
+  sleep 1  # Rate limiting
+done
+```
+
+### Paginated Query Loop
+
+```bash
+#!/bin/bash
+# Fetch all records with pagination
+
+offset=0
+limit=9000
+total_fetched=0
+
+while true; do
+  echo "Fetching offset=$offset..."
+
+  response=$(curl -s -X POST "${ONCHAINDB_ENDPOINT}/list" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "root": "'"${ONCHAINDB_APP_ID}"'::orderbook_snapshots",
+      "find": { "market": { "eq": "BTC" } },
+      "limit": '"$limit"',
+      "offset": '"$offset"'
+    }')
+
+  count=$(echo "$response" | jq '.records | length')
+  total_fetched=$((total_fetched + count))
+
+  echo "Fetched $count records (total: $total_fetched)"
+
+  # Save to file
+  echo "$response" | jq '.records[]' >> output.jsonl
+
+  # Check if we got less than limit (last page)
+  if [ "$count" -lt "$limit" ]; then
+    echo "Done! Total records: $total_fetched"
+    break
+  fi
+
+  offset=$((offset + limit))
+done
+```
+
+---
+
+## Summary
+
+This guide covers all OnChainDB operations using pure curl commands:
+
+1. **Collection Management** - Create, list, update, delete collections
+2. **Sharding** - Configure time-series and hashed sharding
+3. **Indexing** - Create BTree, composite, and price indexes
+4. **Data Ingestion** - Store single and batch records
+5. **Querying** - Simple, filtered, paginated queries
+6. **Views** - Create materialized views for aggregations
+7. **Aggregation Patterns** - OHLC, liquidity, correlation, volatility
+8. **Advanced Operators** - All comparison and logical operators
+9. **Use Cases** - Complete examples for real-world scenarios
+10. **Best Practices** - Performance and data modeling tips
+
+For more information, visit: https://docs.onchaindb.com