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, and trading data 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
• Real-time Streaming: Stream live updates for new markets, resolved predictions, and position splits
• TypeScript Ready: Full TypeScript support with comprehensive JSDoc documentation

📦 Installation

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
2. Get your access token

📚 Documentation

For comprehensive documentation on Polymarket APIs and data structures:

• Polymarket API Documentation - Complete guide to querying Polymarket data
• Get Data for a Specific Polymarket Market - Step-by-step guide for market data
• Main Polymarket Contract API - Core contract events and data
• Polymarket CTF Exchange API - Trading and exchange data
• UMA Adapter Contract API - Oracle resolution data

🎯 Quick Start

import { 
    getNewQuestions, 
    getResolvedQuestions, 
    getPositionSplits,
    getPayoutRecieved 
} 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);

📖 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:

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:

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:

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:

const payouts = await getPayoutRecieved(
    token, 
    '0x4d97dcd97ec945f40cf65f87097ace5ea0476045', 
    20
);

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:

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:

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:

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:

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

🔄 Use Cases

Prediction Market Discovery

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

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:

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:

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
• Bitquery Documentation
• Polygon Blockchain Explorer

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📝 License

ISC

⚠️ Error Handling

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

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
• Review Get Data for a Specific Polymarket Market for query examples
• Join the Bitquery community for support