polymarket-api/README.md

Node.js SDK for querying Polymarket prediction market data. Get new prediction markets, resolved predictions, position tokens, and trading data from Polymarket using Bitquery APIs.

# Polymarket API - Node.js SDK

A powerful npm package for querying **Polymarket** prediction market data using Bitquery's GraphQL APIs. This SDK provides easy access to **new prediction markets**, **resolved predictions**, **position tokens**, **trading data**, and **real-time trade streams** from the Polymarket protocol on Polygon blockchain.

## 🚀 Features

- **Query New Markets**: Get the latest **new prediction markets** and questions created on Polymarket
- **Resolved Predictions**: Track **resolved predictions and outcome** data for completed markets
- **Position Tokens**: Monitor **polymarket positions** and position splits across markets
- **Payout Tracking**: Query payout received events for specific wallet addresses
- **Trade Data**: Query all Polymarket trades, trades by market/position token, and trades by user
- **Real-time Streaming**: Stream live updates for new markets, resolved predictions, position splits, and trades
- **TypeScript Ready**: Full TypeScript support with comprehensive JSDoc documentation

## 📦 Installation

```bash
npm install polymarket-api
```

## 🔑 Prerequisites

To use this **Polymarket API** package, you'll need a Bitquery OAuth token. 

1. [Sign up for a free Bitquery account](https://ide.bitquery.io/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm)
2. [Get your access token](https://account.bitquery.io/user/api_v2/access_tokens?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm)

## 📚 Documentation

For comprehensive documentation on Polymarket APIs and data structures:

- [Polymarket API Documentation](https://docs.bitquery.io/docs/examples/polymarket-api/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Complete guide to querying Polymarket data
- [Get Data for a Specific Polymarket Market](https://docs.bitquery.io/docs/examples/polymarket-api/get-market-data/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Step-by-step guide for market data
- [Main Polymarket Contract API](https://docs.bitquery.io/docs/examples/polymarket-api/main-polymarket-contract/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Core contract events and data
- [Polymarket CTF Exchange API](https://docs.bitquery.io/docs/examples/polymarket-api/polymarket-ctf-exchange/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Trading and exchange data
- [Polymarket Trade APIs](https://docs.bitquery.io/docs/examples/polymarket-api/polymarket-trade-apis/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Real-time and historical trade data
- [UMA Adapter Contract API](https://docs.bitquery.io/docs/examples/polymarket-api/uma-adapter-contract/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) - Oracle resolution data

## 🎯 Quick Start

```javascript
import { 
    getNewQuestions, 
    getResolvedQuestions, 
    getPositionSplits,
    getPayoutRecieved,
    getAllTrades,
    getTradesByAddress,
    getTradesByUser
} from 'polymarket-api';

const token = 'your-bitquery-oauth-token';

// Get new prediction markets
const newMarkets = await getNewQuestions(token, 10);
console.log('New markets:', newMarkets);

// Get resolved predictions and outcome
const resolved = await getResolvedQuestions(token, 10);
console.log('Resolved predictions:', resolved);

// Get polymarket positions
const positions = await getPositionSplits(token, 10);
console.log('Position tokens:', positions);

// Get payout received for an address
const payouts = await getPayoutRecieved(token, '0x...', 10);
console.log('Payouts:', payouts);

// Get all Polymarket trades
const allTrades = await getAllTrades(token, 20);
console.log('All trades:', allTrades);

// Get trades for a specific position token/market
const marketTrades = await getTradesByAddress(
    token, 
    '56913537276977443440562201098597093132803911231987825986901262729097468643752', 
    20
);
console.log('Market trades:', marketTrades);

// Get trades by a specific user
const userTrades = await getTradesByUser(token, '0x...', 20);
console.log('User trades:', userTrades);
```

## 📖 API Reference

### Query Functions

#### `getNewQuestions(token, count)`

Get new questions data from Polymarket. Returns the latest **new prediction markets** created on the platform.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of new question events

**Example:**
```javascript
const newMarkets = await getNewQuestions(token, 20);
```

#### `getResolvedQuestions(token, count)`

Get resolved questions data from Polymarket. Track **resolved predictions and outcome** for completed markets.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of resolved question events

**Example:**
```javascript
const resolved = await getResolvedQuestions(token, 50);
```

#### `getPositionSplits(token, count)`

Get position splits data from Polymarket. Monitor **polymarket positions** and position token creation.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of position split events

**Example:**
```javascript
const positions = await getPositionSplits(token, 30);
```

#### `getPayoutRecieved(token, address, count)`

Get payout received events for a specific address on Polymarket.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `address` (string): Wallet address to query
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of payout received events

**Example:**
```javascript
const payouts = await getPayoutRecieved(
    token, 
    '0x4d97dcd97ec945f40cf65f87097ace5ea0476045', 
    20
);
```

#### `getAllTrades(token, count)`

Get all Polymarket trades data. Returns all USDC-based trades from the Polymarket CTF exchange.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of trade data with USD pricing, amounts, and position token IDs

**Example:**
```javascript
const trades = await getAllTrades(token, 50);
// Returns trades with: Block, Transaction, Trade (AmountInUSD, PriceInUSD, Side, Ids, etc.)
```

#### `getTradesByAddress(token, address, count)`

Get trades for a specific position token ID/market on Polymarket. Use this to track trading activity for a particular prediction market.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `address` (string): Position token ID to query (represents a specific market outcome)
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of trade data for the specific position token

**Example:**
```javascript
const marketTrades = await getTradesByAddress(
    token, 
    '56913537276977443440562201098597093132803911231987825986901262729097468643752', 
    30
);
```

#### `getTradesByUser(token, userAddress, count)`

Get trades by a specific user on Polymarket. Returns all trades where the user's wallet address initiated the transaction.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `userAddress` (string): Wallet address of the user
- `count` (number, optional): Number of results to return (default: 20)

**Returns:** `Promise<Array>` - Array of trade data for the specific user

**Example:**
```javascript
const userTrades = await getTradesByUser(
    token, 
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0', 
    50
);
```

### Streaming Functions

#### `streamNewQuestions(token, options)`

Stream live new questions data from Polymarket. Get real-time updates for **new prediction markets**.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `options` (object, optional): Streaming options
  - `autoCloseMs` (number): Auto-close connection after milliseconds
  - `onData` (function): Callback for new data
  - `onError` (function): Callback for errors

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamNewQuestions(token, {
    onData: (data) => {
        console.log('New market:', data);
    },
    onError: (error) => {
        console.error('Stream error:', error);
    }
});
```

#### `streamResolvedQuestions(token, options)`

Stream live resolved questions data from Polymarket. Monitor **resolved predictions and outcome** in real-time.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `options` (object, optional): Streaming options

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamResolvedQuestions(token, {
    onData: (data) => {
        console.log('Resolved prediction:', data);
    }
});
```

#### `streamPositionSplits(token, options)`

Stream live position splits data from Polymarket. Track **polymarket positions** and **position tokens** in real-time.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `options` (object, optional): Streaming options

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamPositionSplits(token, {
    onData: (data) => {
        console.log('Position split:', data);
    }
});
```

#### `streamPayoutRecieved(token, address, options)`

Stream live payout received events for a specific address on Polymarket.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `address` (string): Wallet address to stream
- `options` (object, optional): Streaming options

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamPayoutRecieved(
    token, 
    '0x...', 
    {
        onData: (data) => {
            console.log('Payout received:', data);
        }
    }
);
```

#### `streamAllTrades(token, options)`

Stream live all Polymarket trades data. Get real-time updates for all USDC-based trades on Polymarket.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `options` (object, optional): Streaming options
  - `autoCloseMs` (number): Auto-close connection after milliseconds
  - `onData` (function): Callback for new data
  - `onError` (function): Callback for errors

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamAllTrades(token, {
    onData: (trade) => {
        console.log('New trade:', trade);
        console.log('Trade amount:', trade.Trade.AmountInUSD);
        console.log('Price:', trade.Trade.PriceInUSD);
    },
    onError: (error) => {
        console.error('Stream error:', error);
    }
});
```

#### `streamTradesByAddress(token, address, options)`

Stream live trades for a specific position token ID/market on Polymarket. Monitor trading activity for a particular prediction market in real-time.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `address` (string): Position token ID to stream
- `options` (object, optional): Streaming options

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamTradesByAddress(
    token, 
    '56913537276977443440562201098597093132803911231987825986901262729097468643752',
    {
        onData: (trade) => {
            console.log('Market trade update:', trade);
        }
    }
);
```

#### `streamTradesByUser(token, userAddress, options)`

Stream live trades by a specific user on Polymarket. Monitor a user's trading activity in real-time.

**Parameters:**
- `token` (string): Your Bitquery OAuth token
- `userAddress` (string): Wallet address of the user
- `options` (object, optional): Streaming options

**Returns:** `Promise<WebSocket>` - Active WebSocket connection

**Example:**
```javascript
const stream = await streamTradesByUser(
    token, 
    '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
    {
        onData: (trade) => {
            console.log('User trade:', trade);
        }
    }
);
```

## 🔄 Use Cases

### Prediction Market Discovery

Discover and track **new prediction markets** as they're created:

```javascript
import { getNewQuestions, streamNewQuestions } from 'polymarket-api';

// Get latest new markets
const latestMarkets = await getNewQuestions(token, 50);

// Stream new markets in real-time
streamNewQuestions(token, {
    onData: (market) => {
        console.log('New market created:', market);
        // Add to your database, notify users, etc.
    }
});
```

### Resolved Predictions Tracking

Monitor **resolved predictions and outcome** for completed markets:

```javascript
import { getResolvedQuestions, streamResolvedQuestions } from 'polymarket-api';

// Get recent resolved predictions
const resolved = await getResolvedQuestions(token, 100);

// Stream new resolutions
streamResolvedQuestions(token, {
    onData: (resolution) => {
        console.log('Market resolved:', resolution);
        // Process payouts, update UI, etc.
    }
});
```

### Position Token Monitoring

Track **polymarket positions** and **position tokens**:

```javascript
import { getPositionSplits, streamPositionSplits } from 'polymarket-api';

// Get recent position splits
const positions = await getPositionSplits(token, 50);

// Stream position splits
streamPositionSplits(token, {
    onData: (split) => {
        console.log('Position split:', split);
        // Update position tracking, calculate balances, etc.
    }
});
```

## 🏗️ About Polymarket

Polymarket is a decentralized **prediction market** protocol built on Polygon that enables users to trade on real-world events. The platform uses:

- **Conditional Tokens Framework (CTF)**: ERC-1155 tokens representing market positions
- **UMA Optimistic Oracle**: For decentralized market resolution
- **CTF Exchange**: For trading position tokens

This SDK provides easy access to all Polymarket data through Bitquery's powerful blockchain APIs.

## 🔗 Related Resources

- [Polymarket Official Website](https://polymarket.com)
- [Bitquery Documentation](https://docs.bitquery.io/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm)
- [Polygon Blockchain Explorer](https://polygonscan.com)

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📝 License

ISC

## ⚠️ Error Handling

All functions include try-catch blocks and will throw errors that you can handle:

```javascript
try {
    const markets = await getNewQuestions(token, 20);
} catch (error) {
    console.error('Error fetching markets:', error);
    // Handle error appropriately
}
```

## 🐛 Troubleshooting

### Common Issues

1. **Invalid Token**: Make sure your Bitquery OAuth token is valid and has the necessary permissions
2. **Network Errors**: Check your internet connection and Bitquery API status
3. **Rate Limiting**: Bitquery has rate limits - implement retry logic for production use

### Getting Help

- Check the [Bitquery Polymarket API Documentation](https://docs.bitquery.io/docs/category/prediction-markets/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm)
- Review [Get Data for a Specific Polymarket Market](https://docs.bitquery.io/docs/examples/polymarket-api/get-market-data/?utm_source=github&utm_medium=refferal&utm_campaign=polymarket_sdk_npm) for query examples
- Join the [Bitquery community](https://t.me/Bloxy_info/) for support