@varla/polymarket 1.0.0 → 1.0.1

package/README.md

@@ -2,7 +2,6 @@
 
 [![npm version](https://img.shields.io/npm/v/@varla/polymarket.svg)](https://www.npmjs.com/package/@varla/polymarket)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![CI](https://github.com/Varla-xyz/varla-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Varla-xyz/varla-api/actions/workflows/ci.yml)
 
 **High-performance Polymarket SDK** — 139% faster than the official SDK.
 
@@ -63,7 +62,7 @@ import { GammaClient, ClobClient } from "@varla/polymarket";
 
 // Fetch markets from Gamma API
 const gamma = new GammaClient();
-const markets = await gamma.getMarkets({ limit: 10 });
+const markets = await gamma.listMarkets({ active: true, limit: 10 });
 
 // Get orderbook from CLOB
 const clob = new ClobClient();
@@ -73,7 +72,6 @@ console.log("Best ask:", book.asks[0]);
 
 // Get prices
 const midpoint = await clob.getMidpoint(markets[0].clobTokenIds[0]);
-const spread = await clob.getSpread(markets[0].clobTokenIds[0]);
 ```
 
 ### Authenticated Trading
@@ -142,85 +140,295 @@ ws.subscribeMarket("0x5f65177b394277fd294cd75650044e32ba009a95...");
 ws.close();
 ```
 
-### Order Persistence (SQLite)
+---
 
-Track orders locally for fast queries and restart recovery:
+## Complete API Reference
+
+### GammaClient (28 methods)
+
+Market discovery, metadata, and content API.
 
 ```typescript
-import { 
-  ClobTradingClient, 
-  createSqliteOrderPersistence,
-  createTrackedOrder,
-} from "@varla/polymarket";
-
-const persistence = createSqliteOrderPersistence("./orders.db");
-
-// Track placed orders
-const order = createTrackedOrder({
-  orderId: response.orderID,
-  market: "0x...",
-  tokenId: "123456...",
-  side: "BUY",
-  price: 0.5,
-  size: 100,
-  orderType: "GTC",
-  status: "OPEN",
-});
-await persistence.save(order);
+import { GammaClient } from "@varla/polymarket";
+const gamma = new GammaClient(opts?: GammaClientOpts);
+```
+
+#### Markets
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `listMarkets` | `{ active?, closed?, limit?, offset?, tag_id? }` | `Promise<GammaMarket[]>` |
+| `getMarketsByConditionIds` | `conditionIds: string[]` | `Promise<GammaMarket[]>` |
+| `getMarketById` | `id: string` | `Promise<GammaMarket>` |
+| `getMarketBySlug` | `slug: string` | `Promise<GammaMarket>` |
+| `getMarketTags` | `marketId: string` | `Promise<GammaTag[]>` |
+
+#### Events
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `listEvents` | `{ active?, closed?, limit?, offset?, tag_id?, series_id?, order?, ascending? }` | `Promise<GammaEvent[]>` |
+| `getEventById` | `id: string` | `Promise<GammaEvent>` |
+| `getEventBySlug` | `slug: string` | `Promise<GammaEvent>` |
+| `getEventTags` | `eventId: string` | `Promise<GammaTag[]>` |
+
+#### Tags
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `listTags` | `{ limit?, offset? }` | `Promise<GammaTag[]>` |
+| `getTagById` | `id: string` | `Promise<GammaTag>` |
+| `getTagBySlug` | `slug: string` | `Promise<GammaTag>` |
+| `getRelatedTagsById` | `id: string` | `Promise<GammaTag[]>` |
+| `getRelatedTagsBySlug` | `slug: string` | `Promise<GammaTag[]>` |
+| `getTagRelationshipsById` | `id: string` | `Promise<GammaTagRelationship[]>` |
+| `getTagRelationshipsBySlug` | `slug: string` | `Promise<GammaTagRelationship[]>` |
+
+#### Sports
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getSports` | — | `Promise<GammaSport[]>` |
+| `listTeams` | `{ sport?, limit?, offset? }` | `Promise<GammaTeam[]>` |
+| `getValidSportsMarketTypes` | — | `Promise<GammaSportsMarketType[]>` |
+
+#### Series
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `listSeries` | `{ limit?, offset? }` | `Promise<GammaSeries[]>` |
+| `getSeriesById` | `id: string` | `Promise<GammaSeries>` |
+
+#### Search
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `search` | `query: string, { limit?, offset? }` | `Promise<GammaSearchResult>` |
+
+#### Profiles
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getPublicProfile` | `address: string` | `Promise<GammaPublicProfile>` |
+
+#### Comments
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `listComments` | `{ eventId?, marketId?, limit?, offset? }` | `Promise<GammaComment[]>` |
+| `getCommentById` | `id: string` | `Promise<GammaComment>` |
+| `getCommentsByUser` | `address: string, { limit?, offset? }` | `Promise<GammaComment[]>` |
+
+#### Builders
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getBuilderLeaderboard` | `{ period?, limit?, offset? }` | `Promise<GammaBuilderLeaderboardEntry[]>` |
+| `getBuilderVolume` | `{ address?, startDate?, endDate? }` | `Promise<GammaBuilderVolumePoint[]>` |
+
+#### Health
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `healthCheck` | — | `Promise<{ status: string }>` |
+
+---
+
+### ClobClient (5 methods)
+
+Public orderbook, prices, and trades (read-only with resilience).
+
+```typescript
+import { ClobClient } from "@varla/polymarket";
+const clob = new ClobClient(config?: Partial<ClobClientConfig>);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getMidpoint` | `tokenId: string` | `Promise<ClobMidpointResponse>` |
+| `getBook` | `tokenId: string` | `Promise<ClobBookResponse>` |
+| `getPricesHistory` | `{ tokenId, startTs, endTs, interval, fidelity? }` | `Promise<ClobPricesHistoryResponse>` |
+| `getMetrics` | — | `ClobClientMetrics` |
+| `getCircuitState` | — | `CircuitState` |
+| `resetCircuitBreaker` | — | `void` |
+
+---
+
+### ClobTradingClient (30 methods)
+
+Authenticated trading operations.
+
+```typescript
+import { ClobTradingClient } from "@varla/polymarket";
+const client = new ClobTradingClient(walletClient, config?: ClobTradingClientConfig);
+```
+
+#### Initialization
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `init` | — | `Promise<void>` |
+| `isInitialized` | — | `boolean` |
+| `getCredentials` | — | `ApiKeyCreds` |
+| `setCredentials` | `creds: ApiKeyCreds` | `void` |
+
+#### Orders
 
-// Query orders
-const openOrders = await persistence.getOpen();
-const marketOrders = await persistence.getByMarket("0x...");
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `createOrder` | `params: OrderParams, options: MarketOptions` | `Promise<SignedOrder>` |
+| `postOrder` | `signedOrder: SignedOrder, orderType?: OrderType` | `Promise<OrderResponse>` |
+| `createAndPostOrder` | `params: OrderParams, options: MarketOptions, orderType?: OrderType` | `Promise<OrderResponse>` |
+| `postOrders` | `signedOrders: SignedOrder[], orderType?: OrderType` | `Promise<BatchOrderResponse>` |
+| `createAndPostOrders` | `ordersParams: Array<{params, options}>, orderType?: OrderType` | `Promise<BatchOrderResponse>` |
+| `getOrder` | `orderId: string` | `Promise<Order>` |
+| `getOpenOrders` | `filter?: OpenOrdersFilter` | `Promise<Order[]>` |
 
-// Cleanup old orders
-await persistence.prune(24 * 60 * 60 * 1000); // 24h
+#### Market Orders
 
-persistence.close();
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `marketBuy` | `params: MarketBuyParams, options: MarketOptions, timeInForce?: TimeInForce` | `Promise<OrderResponse>` |
+| `marketSell` | `params: MarketSellParams, options: MarketOptions, timeInForce?: TimeInForce` | `Promise<OrderResponse>` |
+| `getOrderBook` | `tokenId: string` | `Promise<OrderBook>` |
+
+#### Cancellation
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `cancelOrder` | `orderId: string` | `Promise<CancelResponse>` |
+| `cancelOrders` | `orderIds: string[]` | `Promise<CancelResponse>` |
+| `cancelMarketOrders` | `{ market?, asset_id? }` | `Promise<CancelResponse>` |
+| `cancelAll` | — | `Promise<CancelResponse>` |
+
+#### Account
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getClosedOnlyMode` | — | `Promise<{ closedOnly: boolean; reason?: string }>` |
+| `getApiKeys` | — | `Promise<{ apiKeys: Array<{apiKey, createdAt}> }>` |
+| `deleteApiKey` | — | `Promise<void>` |
+
+#### Trades & History
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getTrades` | `filter?: TradeHistoryFilter` | `Promise<Trade[]>` |
+| `heartbeat` | — | `Promise<HeartbeatResponse>` |
+
+#### Rewards
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getEarningsForDay` | `date: string` | `Promise<UserEarnings>` |
+| `getTotalEarningsForDay` | `date: string` | `Promise<UserEarnings>` |
+| `getLiquidityRewardPercentages` | — | `Promise<LiquidityRewardPercentages>` |
+| `getRewardsMarkets` | — | `Promise<RewardsMarket[]>` |
+
+#### Builder API
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `createBuilderApiKey` | — | `Promise<BuilderApiKey>` |
+| `getBuilderApiKeys` | — | `Promise<BuilderApiKeyInfo[]>` |
+| `revokeBuilderApiKey` | — | `Promise<void>` |
+| `getBuilderTrades` | `filter?: BuilderTradesFilter, cursor?: string` | `Promise<BuilderTradesResponse>` |
+
+---
+
+### DataApiClient (16 methods)
+
+Positions, trades, leaderboards, and analytics.
+
+```typescript
+import { DataApiClient } from "@varla/polymarket";
+const data = new DataApiClient(opts?: DataApiClientOpts);
 ```
 
-## API Reference
+#### Positions
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getCurrentPositions` | `{ address, conditionId?, limit?, offset? }` | `Promise<DataPosition[]>` |
+| `getClosedPositions` | `{ address, limit?, offset? }` | `Promise<DataClosedPosition[]>` |
+| `getTotalPositionValue` | `address: string` | `Promise<DataPositionValue>` |
+
+#### Trades & Activity
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getTrades` | `{ address?, conditionId?, limit?, offset? }` | `Promise<DataTrade[]>` |
+| `getUserActivity` | `{ address, limit?, offset? }` | `Promise<DataActivity[]>` |
+
+#### Analytics
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getTopHolders` | `{ conditionId, outcomeIndex?, limit? }` | `Promise<DataTopHolder[]>` |
+| `getTraderLeaderboard` | `{ period?, category?, order?, limit?, offset? }` | `Promise<DataLeaderboardEntry[]>` |
+| `getOpenInterest` | `{ conditionId?, asset? }` | `Promise<DataOpenInterest>` |
+| `getLiveVolume` | `{ eventId?, conditionId? }` | `Promise<DataVolume>` |
+
+#### Pricing & Orderbook
 
-### Clients
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getPriceHistory` | `{ tokenId, interval?, startTs?, endTs?, fidelity? }` | `Promise<DataPriceHistory>` |
+| `getOrderBookSummary` | `tokenId: string` | `Promise<DataOrderBookSummary>` |
+| `getOrderBookSummaries` | `tokenIds: string[]` | `Promise<DataOrderBookSummary[]>` |
+| `getSpreads` | `tokenIds: string[]` | `Promise<DataSpread[]>` |
 
-| Client | Purpose |
-|--------|---------|
-| `GammaClient` | Market discovery, metadata, token IDs |
-| `ClobClient` | Public orderbook, prices, trades (read-only) |
-| `ClobTradingClient` | Authenticated trading operations |
-| `ClobWsClient` | Real-time WebSocket updates |
+#### Misc
 
-### ClobTradingClient Methods
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getTotalMarketsTraded` | `address: string` | `Promise<DataMarketsTraded>` |
+| `getAccountingSnapshot` | `address: string` | `Promise<Response>` |
+| `healthCheck` | — | `Promise<{ status: string }>` |
+
+---
+
+### BridgeClient (5 methods)
+
+Deposit/withdrawal functionality through the Relay bridge.
 
 ```typescript
-// Initialization
-client.init()                           // Derive/create API key
-client.setCredentials(creds)            // Set API key manually
-
-// Orders
-client.createOrder(params, options)     // Create signed order
-client.postOrder(order, type)           // Post to CLOB
-client.createAndPostOrder(params, options, type)  // Combined
-client.getOrder(orderId)                // Get order details
-client.getOpenOrders(filter?)           // List open orders
-
-// Cancellation
-client.cancelOrder(orderId)             // Cancel one order
-client.cancelOrders(orderIds)           // Cancel multiple
-client.cancelMarketOrders({ market })   // Cancel by market
-client.cancelAll()                      // Cancel all orders
-
-// Account
-client.getClosedOnlyMode()              // Check if account is restricted
+import { BridgeClient } from "@varla/polymarket";
+const bridge = new BridgeClient(opts?: BridgeClientOpts);
 ```
 
-### Order Types
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `createDepositAddresses` | `{ userAddress, chain, asset? }` | `Promise<BridgeDepositAddress>` |
+| `createWithdrawalAddresses` | `{ userAddress, destinationAddress, chain, asset, amount }` | `Promise<BridgeWithdrawalAddress>` |
+| `getQuote` | `{ fromChain, toChain, fromAsset, toAsset, amount }` | `Promise<BridgeQuote>` |
+| `getSupportedAssets` | — | `Promise<BridgeSupportedAsset[]>` |
+| `getTransactionStatus` | `transactionId: string` | `Promise<BridgeTransactionStatus>` |
+
+---
+
+### ClobWsClient (7 methods)
+
+Real-time WebSocket updates.
 
 ```typescript
-type Side = "BUY" | "SELL";
-type OrderType = "GTC" | "GTD" | "FOK";  // Good-Til-Cancel, Good-Til-Date, Fill-Or-Kill
-type OrderStatus = "OPEN" | "MATCHED" | "FILLED" | "CANCELLED" | "EXPIRED";
+import { ClobWsClient } from "@varla/polymarket";
+const ws = new ClobWsClient(events?: ClobWsEvents, config?: ClobWsConfig);
 ```
 
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `connect` | — | `void` |
+| `close` | — | `void` |
+| `subscribeMarket` | `market: string` | `void` |
+| `unsubscribeMarket` | `market: string` | `void` |
+| `subscribeMarkets` | `markets: string[]` | `void` |
+| `getState` | — | `ClobWsState` |
+| `isConnected` | — | `boolean` |
+| `getSubscribedMarkets` | — | `string[]` |
+
+---
+
 ## Configuration
 
 ### Environment Variables
@@ -279,29 +487,6 @@ try {
 }
 ```
 
-## Validation Utilities
-
-```typescript
-import { 
-  validateOrderParams, 
-  roundToTickSize,
-  isValidPrice,
-  getMinimumOrderSize,
-} from "@varla/polymarket";
-
-// Validate before creating
-validateOrderParams(params, options); // throws OrderValidationError
-
-// Round to valid tick
-const price = roundToTickSize(0.505, "0.01"); // 0.51
-
-// Check price validity
-isValidPrice(0.505, "0.01"); // false
-
-// Get minimum shares for $1 order
-getMinimumOrderSize(0.5); // 2 shares
-```
-
 ## Testing
 
 ```bash
@@ -337,17 +522,19 @@ POLYMARKET_LIVE_TESTS=1 bun test packages/polymarket/test/live
 └─────────────────────────────────────────────────────────────┘
 
 ┌──────────────────┐  ┌─────────────────┐  ┌────────────────┐
-│ OrderPersistence │  │  ClobWsClient   │  │  GammaClient   │
-│ - SQLite/Memory  │  │  - WebSocket    │  │  - Markets     │
-│ - Order tracking │  │  - Book updates │  │  - Metadata    │
+│   GammaClient    │  │  DataApiClient  │  │  BridgeClient  │
+│ - 28 methods     │  │  - 16 methods   │  │  - 5 methods   │
+│ - Markets, Tags  │  │  - Positions    │  │  - Deposits    │
+│ - Events, Sports │  │  - Analytics    │  │  - Withdrawals │
 └──────────────────┘  └─────────────────┘  └────────────────┘
-```
 
-## Related Packages
-
-- [`@varla/db`](../db) - SQLite persistence layer
-- [`@varla/rpc`](../rpc) - Resilient RPC client
-- [`@varla/runtime`](../runtime) - Service runtime utilities
+┌──────────────────┐  ┌─────────────────┐
+│   ClobClient     │  │  ClobWsClient   │
+│ - 5 methods      │  │  - 7 methods    │
+│ - Circuit break  │  │  - Real-time    │
+│ - Rate limiting  │  │  - Auto-reconnect│
+└──────────────────┘  └─────────────────┘
+```
 
 ## License