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

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
• Polymarket Trade APIs - Real-time and historical trade data
• UMA Adapter Contract API - Oracle resolution data

🎯 Quick Start

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:

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
);

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:

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:

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:

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:

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);
        }
    }
);

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:

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:

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:

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:

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