{"_id":"@codifydoo/polymarket-apidata-client","_rev":"2-960346ae045da349076aeda06fc9aebe","name":"@codifydoo/polymarket-apidata-client","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@codifydoo/polymarket-apidata-client","version":"1.0.1","keywords":["polymarket","data-api","api","client","typescript","prediction-markets","trading","positions","trades"],"author":{"name":"CodifyDoo"},"license":"MIT","_id":"@codifydoo/polymarket-apidata-client@1.0.1","maintainers":[{"name":"codifydoo","email":"dsantic@codify.hr"}],"homepage":"https://github.com/codifydoo/polymarket-apidata-client#readme","bugs":{"url":"https://github.com/codifydoo/polymarket-apidata-client/issues"},"dist":{"shasum":"ba1db2b838719ea7c6ce7d21b4b3f409819d56c1","tarball":"https://registry.npmjs.org/@codifydoo/polymarket-apidata-client/-/polymarket-apidata-client-1.0.1.tgz","fileCount":9,"integrity":"sha512-ybaLN6rtfU5IxgV3ZayK9pEvWAWu/LDFRpWDf2n7C0uogzPbzl5VGdEKTMzx/xUCBzzL9hxJvGYk5Kn5ef+jTQ==","signatures":[{"sig":"MEYCIQDMmQe1AENsGTeJYJX+wQTfutabD0ui70GzohmQDTz91QIhANwx4S70rCWq9a6MsR07UrrRy+YxiqSszH9x5nOwkk+k","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":218233},"main":"./dist/index.js","type":"module","_from":"file:codifydoo-polymarket-apidata-client-1.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"funding":{"url":"https://paypal.me/DavorSantic","type":"paypal"},"scripts":{"lint":"eslint src/**/*.ts","test":"vitest run","build":"tsup","format":"prettier --write src/**/*.ts","release":"pnpm run prepublishOnly && pnpm publish --access public","test:ui":"vitest --ui","lint:fix":"eslint src/**/*.ts --fix","typecheck":"tsc --noEmit","verify-api":"tsx scripts/verify-api.ts","build:watch":"tsup --watch","format:check":"prettier --check src/**/*.ts","verify-build":"tsx scripts/verify-build.ts","verify-types":"tsx scripts/verify-types.ts","release:major":"./scripts/release.sh major","release:minor":"./scripts/release.sh minor","release:patch":"./scripts/release.sh patch","test:coverage":"vitest --coverage","analyze-bundle":"tsx scripts/analyze-bundle.ts","release:dry-run":"npm run prepublishOnly && npm publish --dry-run","validate-release":"tsx scripts/validate-release.ts"},"_npmUser":{"name":"codifydoo","email":"dsantic@codify.hr"},"_resolved":"/tmp/dd3a16c5ea96d9bd52f8d0f6cc1cbd58/codifydoo-polymarket-apidata-client-1.0.1.tgz","_integrity":"sha512-ybaLN6rtfU5IxgV3ZayK9pEvWAWu/LDFRpWDf2n7C0uogzPbzl5VGdEKTMzx/xUCBzzL9hxJvGYk5Kn5ef+jTQ==","repository":{"url":"git+https://github.com/codifydoo/polymarket-apidata-client.git","type":"git"},"_npmVersion":"10.8.2","description":"TypeScript client library for Polymarket Data API (positions, trades, user activity, market statistics)","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.22.0","axios":"^1.6.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.1","eslint":"^9.39.1","vitest":"^4.0.15","prettier":"^3.7.4","@eslint/js":"^9.39.1","typescript":"^5.9.3","@types/node":"^20.19.26","@vitest/coverage-v8":"^4.0.15","@typescript-eslint/parser":"^8.49.0","@typescript-eslint/eslint-plugin":"^8.49.0"},"_npmOperationalInternal":{"tmp":"tmp/polymarket-apidata-client_1.0.1_1765552827690_0.2525827443272035","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@codifydoo/polymarket-apidata-client","version":"1.0.2","description":"TypeScript client library for Polymarket Data API (positions, trades, user activity, market statistics)","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"keywords":["polymarket","data-api","api","client","typescript","prediction-markets","trading","positions","trades"],"author":{"name":"CodifyDoo"},"license":"MIT","homepage":"https://github.com/codifydoo/polymarket-apidata-client#readme","repository":{"type":"git","url":"git+https://github.com/codifydoo/polymarket-apidata-client.git"},"bugs":{"url":"https://github.com/codifydoo/polymarket-apidata-client/issues"},"funding":{"type":"paypal","url":"https://paypal.me/DavorSantic"},"dependencies":{"axios":"^1.6.0","zod":"^3.22.0"},"engines":{"node":">=18.0.0"},"devDependencies":{"@eslint/js":"^9.39.1","@types/node":"^20.19.26","@typescript-eslint/eslint-plugin":"^8.49.0","@typescript-eslint/parser":"^8.49.0","@vitest/coverage-v8":"^4.0.15","eslint":"^9.39.1","prettier":"^3.7.4","tsup":"^8.5.1","tsx":"^4.21.0","typescript":"^5.9.3","vitest":"^4.0.15"},"scripts":{"build":"tsup","build:watch":"tsup --watch","test":"vitest run","test:coverage":"vitest --coverage","test:ui":"vitest --ui","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","typecheck":"tsc --noEmit","format":"prettier --write src/**/*.ts","format:check":"prettier --check src/**/*.ts","verify-build":"tsx scripts/verify-build.ts","analyze-bundle":"tsx scripts/analyze-bundle.ts","verify-types":"tsx scripts/verify-types.ts","verify-api":"tsx scripts/verify-api.ts","validate-release":"tsx scripts/validate-release.ts","release:dry-run":"npm run prepublishOnly && npm publish --dry-run","release":"pnpm run prepublishOnly && pnpm publish --access public","release:patch":"./scripts/release.sh patch","release:minor":"./scripts/release.sh minor","release:major":"./scripts/release.sh major"},"_id":"@codifydoo/polymarket-apidata-client@1.0.2","_integrity":"sha512-hCBxpbTAxU7U/m1TCzl5zfAWBN+yta//ZETnOCJ3v4/OeBHyjpFwsw07qRx+SvaqgA4s/r2MeRXC9XT0d0wx3w==","_resolved":"/tmp/54db6c7d1ae96af817c5cf2bae052899/codifydoo-polymarket-apidata-client-1.0.2.tgz","_from":"file:codifydoo-polymarket-apidata-client-1.0.2.tgz","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-hCBxpbTAxU7U/m1TCzl5zfAWBN+yta//ZETnOCJ3v4/OeBHyjpFwsw07qRx+SvaqgA4s/r2MeRXC9XT0d0wx3w==","shasum":"51ce74d5af48d5a0f80682540fedec053735b039","tarball":"https://registry.npmjs.org/@codifydoo/polymarket-apidata-client/-/polymarket-apidata-client-1.0.2.tgz","fileCount":9,"unpackedSize":218245,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDX3vpgQ2SPQQVuP77bqK2sehrn02C9n70vzJTa7WBhXAIgf2ZA9B89sXZ88UFJvMP8kwkJEkpv17AOki1aSIbki/4="}]},"_npmUser":{"name":"codifydoo","email":"dsantic@codify.hr"},"directories":{},"maintainers":[{"name":"codifydoo","email":"dsantic@codify.hr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/polymarket-apidata-client_1.0.2_1765554556401_0.08089437873011507"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-12T15:20:27.588Z","modified":"2025-12-12T15:49:16.737Z","1.0.1":"2025-12-12T15:20:27.881Z","1.0.2":"2025-12-12T15:49:16.540Z"},"bugs":{"url":"https://github.com/codifydoo/polymarket-apidata-client/issues"},"author":{"name":"CodifyDoo"},"license":"MIT","homepage":"https://github.com/codifydoo/polymarket-apidata-client#readme","keywords":["polymarket","data-api","api","client","typescript","prediction-markets","trading","positions","trades"],"repository":{"type":"git","url":"git+https://github.com/codifydoo/polymarket-apidata-client.git"},"description":"TypeScript client library for Polymarket Data API (positions, trades, user activity, market statistics)","maintainers":[{"name":"codifydoo","email":"dsantic@codify.hr"}],"readme":"# Polymarket Data API Client\n\nA production-ready TypeScript client library for the Polymarket Data API (positions, trades, user activity, market statistics, and builder metrics).\n\n## Features\n\n- 🚀 **Full API Coverage** - All endpoints across Health, Core, Misc, and Builders domains\n- 🔒 **Type Safety** - Strict TypeScript types with no `any`\n- ✅ **Runtime Validation** - Zod schemas for request/response validation\n- 🔄 **Retry Logic** - Exponential backoff with jitter for resilience\n- ⚡ **Rate Limiting** - Token bucket implementation for polite API usage\n- 📖 **Comprehensive Docs** - JSDoc comments and runnable examples\n\n## Installation\n\n```bash\nnpm install @codifydoo/polymarket-apidata-client\n```\n\nOr with pnpm:\n\n```bash\npnpm add @codifydoo/polymarket-apidata-client\n```\n\n## Quick Start\n\n```typescript\nimport { PolymarketDataClient } from '@codifydoo/polymarket-apidata-client';\n\nconst client = new PolymarketDataClient({\n  baseURL: 'https://data-api.polymarket.com',\n  timeoutMs: 10_000,\n  retries: 2,\n  rateLimit: { burst: 30, ratePerSec: 18 },\n  userAgent: 'my-app/1.0.0',\n});\n\n// Health check\nconst health = await client.health.check();\nconsole.log('API Status:', health.data);\n\n// Get positions for a user\nconst positions = await client.core.getPositions({\n  user: '0x56687bf447db6ffa42ffe2204a05edaa20f55839',\n  limit: 10,\n});\n\n// Get trades\nconst trades = await client.core.getTrades({\n  user: '0x56687bf447db6ffa42ffe2204a05edaa20f55839',\n});\n\n// Get open interest\nconst openInterest = await client.misc.getOpenInterest({\n  market: ['0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917'],\n});\n```\n\n## Configuration\n\n### Client Options\n\n```typescript\ninterface PolymarketDataClientConfig {\n  baseURL?: string; // Default: 'https://data-api.polymarket.com'\n  timeoutMs?: number; // Default: 10_000\n  retries?: number; // Default: 2\n  rateLimit?: {\n    // Default: { burst: 30, ratePerSec: 18 }\n    // Based on Data API limits: 200 requests / 10s = 20 req/s\n    // Using conservative 18 req/s (180/10s) with burst allowance\n    burst: number;\n    ratePerSec: number;\n  };\n  userAgent?: string; // Default: 'polymarket-apidata-client/1.0.0'\n}\n```\n\n### Examples\n\n#### Basic Usage\n\n```typescript\nconst client = new PolymarketDataClient();\n```\n\n#### Custom Configuration\n\n```typescript\nconst client = new PolymarketDataClient({\n  baseURL: 'https://data-api.polymarket.com',\n  timeoutMs: 15_000,\n  retries: 3,\n  rateLimit: { burst: 40, ratePerSec: 20 }, // Maximum: 200 requests / 10s\n  userAgent: 'my-trading-bot/1.0.0',\n});\n```\n\n## API Reference\n\n### Health\n\n#### `client.health.check()`\n\nCheck the health status of the Data API.\n\n**Returns:** `Promise<HealthCheckResponse>`\n\n```typescript\nconst health = await client.health.check();\n// { data: 'OK' }\n```\n\n### Core\n\n#### `client.core.getPositions(params)`\n\nGet current positions for a user.\n\n**Parameters:**\n- `params.user` - User address (required, 0x-prefixed, 40 hex chars)\n- `params.market?` - Comma-separated list of condition IDs\n- `params.eventId?` - Comma-separated list of event IDs\n- `params.limit?` - Number of positions to return (default: 100, max: 500)\n- `params.offset?` - Number of positions to skip (default: 0)\n- `params.sortBy?` - Sort field (default: 'TOKENS')\n- `params.sortDirection?` - Sort direction (default: 'DESC')\n\n**Returns:** `Promise<Position[]>`\n\n```typescript\nconst positions = await client.core.getPositions({\n  user: '0x56687bf447db6ffa42ffe2204a05edaa20f55839',\n  limit: 10,\n});\n```\n\n#### `client.core.getTrades(params)`\n\nGet trades for a user or markets.\n\n**Parameters:**\n- `params.user?` - User address\n- `params.market?` - Comma-separated list of condition IDs\n- `params.limit?` - Number of trades to return\n- `params.offset?` - Number of trades to skip\n\n**Returns:** `Promise<Trade[]>`\n\n```typescript\nconst trades = await client.core.getTrades({\n  user: '0x56687bf447db6ffa42ffe2204a05edaa20f55839',\n});\n```\n\n#### `client.core.getUserActivity(params)`\n\nGet user activity.\n\n**Parameters:**\n- `params.user` - User address (required)\n- `params.limit?` - Number of activities to return\n- `params.offset?` - Number of activities to skip\n\n**Returns:** `Promise<UserActivity[]>`\n\n#### `client.core.getTopHolders(params)`\n\nGet top holders for markets.\n\n**Parameters:**\n- `params.market` - Array of condition IDs (required)\n- `params.limit?` - Number of holders to return\n\n**Returns:** `Promise<TopHolder[]>`\n\n#### `client.core.getTotalValue(params)`\n\nGet total value of a user's positions.\n\n**Parameters:**\n- `params.user` - User address (required)\n\n**Returns:** `Promise<TotalValue>`\n\n#### `client.core.getClosedPositions(params)`\n\nGet closed positions for a user.\n\n**Parameters:**\n- `params.user` - User address (required)\n- `params.market?` - Array of condition IDs\n- `params.eventId?` - Array of event IDs\n- `params.limit?` - Number of positions to return\n- `params.offset?` - Number of positions to skip\n\n**Returns:** `Promise<ClosedPosition[]>`\n\n### Misc\n\n#### `client.misc.getTotalMarketsTraded(params)`\n\nGet total markets a user has traded.\n\n**Parameters:**\n- `params.user` - User address (required)\n\n**Returns:** `Promise<TotalMarketsTraded>`\n\n#### `client.misc.getOpenInterest(params)`\n\nGet open interest for markets.\n\n**Parameters:**\n- `params.market` - Array of condition IDs (required)\n\n**Returns:** `Promise<OpenInterest[]>`\n\n#### `client.misc.getLiveVolume(params)`\n\nGet live volume for an event.\n\n**Parameters:**\n- `params.eventId` - Event ID (required)\n\n**Returns:** `Promise<LiveVolume>`\n\n### Builders\n\n#### `client.builders.getAggregatedLeaderboard(params?)`\n\nGet aggregated builder leaderboard.\n\n**Parameters:**\n- `params.limit?` - Number of entries to return\n- `params.offset?` - Number of entries to skip\n- `params.period?` - Time period (e.g., 'daily', 'weekly', 'all-time')\n\n**Returns:** `Promise<BuilderLeaderboardEntry[]>`\n\n#### `client.builders.getDailyVolumeSeries(params?)`\n\nGet daily builder volume time series.\n\n**Parameters:**\n- `params.builder?` - Builder address\n- `params.startDate?` - Start date (ISO date string)\n- `params.endDate?` - End date (ISO date string)\n- `params.limit?` - Number of entries to return\n- `params.offset?` - Number of entries to skip\n\n**Returns:** `Promise<DailyVolumeSeries[]>`\n\n## Error Handling\n\nThe client provides comprehensive error handling:\n\n```typescript\ntry {\n  const positions = await client.core.getPositions({\n    user: '0x56687bf447db6ffa42ffe2204a05edaa20f55839',\n  });\n} catch (error) {\n  if (error instanceof Error) {\n    console.error('API Error:', error.message);\n  }\n}\n```\n\n### Common Error Scenarios\n\n#### Network Errors\n\n```typescript\ntry {\n  const result = await client.core.getPositions({ user: '0x...' });\n} catch (error) {\n  // Network errors are automatically retried with exponential backoff\n  console.error('Request failed after retries:', error.message);\n}\n```\n\n#### Validation Errors\n\n```typescript\ntry {\n  const result = await client.core.getPositions({ user: 'invalid-address' });\n} catch (error) {\n  // Zod validation error\n  console.error('Validation error:', error.message);\n}\n```\n\n#### Rate Limiting\n\n```typescript\n// The client automatically handles rate limiting\n// Requests are queued and executed at the configured rate\nconst promises = Array(100)\n  .fill(null)\n  .map(() => client.core.getPositions({ user: '0x...' }));\nawait Promise.all(promises); // Will be rate-limited automatically\n```\n\n## Rate Limiting\n\nThe client implements a token bucket rate limiter. Default limits are based on [Polymarket Data API rate limits](https://docs.polymarket.com/quickstart/introduction/rate-limits#data-api-rate-limits):\n\n- **General endpoints**: 200 requests / 10s (default: 18 req/s = 180/10s, conservative)\n- **/trades endpoint**: 75 requests / 10s (7.5 req/s)\n- **Health check**: 10 requests / 10s (1 req/s)\n\n```typescript\nconst client = new PolymarketDataClient({\n  rateLimit: {\n    burst: 30, // Allow up to 30 requests immediately\n    ratePerSec: 18, // Then limit to 18 requests per second (180/10s, under 200/10s limit)\n  },\n});\n\n// These requests will be rate-limited automatically\nconst promises = Array(200)\n  .fill(null)\n  .map(() => client.core.getPositions({ user: '0x...' }));\nawait Promise.all(promises);\n```\n\n## Best Practices\n\n### 1. Error Handling\n\nAlways wrap API calls in try-catch blocks:\n\n```typescript\ntry {\n  const result = await client.core.getPositions({ user: '0x...' });\n  // Process result\n} catch (error) {\n  // Handle error appropriately\n  console.error('Failed to fetch positions:', error.message);\n}\n```\n\n### 2. Pagination\n\nUse pagination to avoid loading too much data at once:\n\n```typescript\nasync function getAllPositions(user: string) {\n  const allPositions = [];\n  let offset = 0;\n  const limit = 100;\n\n  while (true) {\n    const positions = await client.core.getPositions({\n      user,\n      limit,\n      offset,\n    });\n    \n    allPositions.push(...positions);\n    \n    if (positions.length < limit) break;\n    offset += limit;\n  }\n\n  return allPositions;\n}\n```\n\n### 3. Rate Limiting\n\nConfigure appropriate rate limits for your use case:\n\n```typescript\nconst client = new PolymarketDataClient({\n  rateLimit: {\n    burst: 10, // Conservative burst\n    ratePerSec: 10, // Conservative rate (100/10s, well under 200/10s limit)\n  },\n});\n```\n\n### 4. Type Safety\n\nUse TypeScript strict mode and leverage the provided types:\n\n```typescript\nimport { Position, GetPositionsParams } from '@codifydoo/polymarket-apidata-client';\n\nasync function processPositions(params: GetPositionsParams): Promise<Position[]> {\n  const positions = await client.core.getPositions(params);\n  return positions;\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. Network Timeouts\n\n```typescript\nconst client = new PolymarketDataClient({\n  timeoutMs: 30_000, // Increase timeout for slow connections\n});\n```\n\n#### 2. Rate Limiting\n\n```typescript\nconst client = new PolymarketDataClient({\n  rateLimit: {\n    burst: 1, // Reduce burst\n    ratePerSec: 1, // Reduce rate\n  },\n});\n```\n\n#### 3. Validation Errors\n\nCheck the error message for specific validation issues:\n\n```typescript\ntry {\n  await client.core.getPositions({ user: 'invalid-address' });\n} catch (error) {\n  console.error('Validation error:', error.message);\n  // Look for specific field validation errors\n}\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 📖 [Documentation](https://github.com/codifydoo/polymarket-apidata-client#readme)\n- 🐛 [Issue Tracker](https://github.com/codifydoo/polymarket-apidata-client/issues)\n- 💬 [Discussions](https://github.com/codifydoo/polymarket-apidata-client/discussions)\n\n","readmeFilename":"README.md"}