orderbook-analysis

name	orderbook-analysis
description	Analyze Polymarket orderbook depth, liquidity, spreads, and price impact. Use this skill when the user wants to analyze market microstructure, calculate spreads, check liquidity, or estimate price impact for trades. Triggers include phrases like "orderbook analysis", "market depth", "bid ask spread", "liquidity analysis", "price impact", or "slippage calculation".

Orderbook Analysis

Overview

Analyze market microstructure including orderbook snapshots, bid-ask spreads, liquidity depth, and price impact calculations for optimal trade execution.

Security

This skill implements defense-in-depth measures against indirect prompt injection (Snyk W011):

• Input Sanitization: Orderbook identifiers (market, assetId) are sanitized using security.ts
• Pattern Filtering: Known prompt injection patterns are removed (e.g., "ignore previous instructions", "system:")
• Content Validation: Suspicious content with excessive special characters is flagged
• Fail-Safe: Processing errors return original data rather than corrupting it

The skill fetches data from the trusted DOME API (api.domeapi.io) which provides structured orderbook data from the Polymarket protocol.

Setup

npm install
npm run build

Quick Start

import {
  fetchOrderbookHistory,
  fetchMarketPrice,
  calculateSpread,
  analyzeLiquidity,
  detectPriceImpact,
  getLiquidityProfile
} from "./scripts/orderbookAnalysis.js";

// Get current orderbook
const history = await fetchOrderbookHistory(apiKey, tokenId, { limit: 1 });
const snapshot = parseOrderbookSnapshot(history.snapshots[0]);

// Calculate spread
const spread = calculateSpread(snapshot.asks, snapshot.bids);
console.log(`Spread: ${spread.spread_percentage}%`);

// Analyze liquidity
const liquidity = analyzeLiquidity(snapshot.asks, snapshot.bids);

// Check price impact for 1000 share buy
const impact = detectPriceImpact(snapshot.asks, "buy", 1000);
console.log(`Price impact: ${impact.price_impact_percent}%`);

Core Functions

fetchOrderbookHistory()

Fetch historical orderbook snapshots.

const result = await fetchOrderbookHistory(apiKey, tokenId, {
  start_time: 1760470000000,  // Milliseconds
  end_time: 1760480000000,
  limit: 100
});

fetchMarketPrice()

Fetch current or historical market price.

// Current price
const price = await fetchMarketPrice(apiKey, tokenId);

// Historical price
const historical = await fetchMarketPrice(apiKey, tokenId, 1762164600);

parseOrderbookSnapshot()

Parse raw orderbook data with sorting.

const parsed = parseOrderbookSnapshot(snapshot);
// Returns: { asks, bids, midPrice, spread, timestamp, ... }

calculateSpread()

Calculate bid-ask spread metrics.

const spread = calculateSpread(asks, bids);
// Returns: { best_ask, best_bid, spread_absolute, spread_percentage }

analyzeLiquidity()

Analyze liquidity at different depth levels.

const liquidity = analyzeLiquidity(asks, bids);
// Returns: {
//   total_ask_liquidity,
//   total_bid_liquidity,
//   depth_2_percent,
//   depth_5_percent,
//   imbalance
// }

detectPriceImpact()

Calculate price impact for a trade.

const impact = detectPriceImpact(orders, "buy", 1000);
// Returns: {
//   executable,
//   average_price,
//   price_impact_percent,
//   filled_size,
//   missing_liquidity
// }

getLiquidityProfile()

Generate comprehensive liquidity profile.

const profile = getLiquidityProfile(asks, bids);
// Returns: {
//   spread,
//   ask_levels,
//   bid_levels,
//   optimal_trade_size,
//   recommended_max_trade,
//   liquidity_score
// }

analyzeOrderbookChanges()

Track orderbook changes over time.

const changes = analyzeOrderbookChanges(parsedSnapshots);
// Returns: Array of { timestamp, spread_change, liquidity_change, ... }

Data Limitations

• Orderbook history available from October 14th, 2025
• Timestamps are in milliseconds (not seconds)
• Maximum 200 snapshots per request
• When fetching latest orderbook without time range, pagination is ignored