Skip to content

danielgnh/polymarket-php

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Polymarket PHP SDK

Polymarket API PHP SDK for interacting with the prediction markets and managing orders.

You can search for the markets, events, create / delete orders and much more.

What is polymarket?

Latest Version on Packagist PHP Version Total Downloads License Tests PHPStan

Requirements

  • PHP 8.1 or higher
  • Composer

Installation

Install the package via Composer:

composer require danielgnh/polymarket-php

Configuration

Add your polymarket credentials to your .env file:

POLYMARKET_API_KEY=your-api-key
POLYMARKET_PRIVATE_KEY=0x...

Here is documentation how to export you private key

Quick Start

<?php

use Danielgnh\PolymarketPhp\Client;

/*
* Let's initialize the client.
* In case if you defined the POLYMARKET_API_KEY you don't need to pass any parameters in Client
*/
$client = new Client();

/*
* In case if you want to define any other API Key, you can do it as well.
*/
$client = new Client('api-key');

API Architecture

Polymarket uses two separate API systems:

  • Gamma API (https://gamma-api.polymarket.com) - Read-only market data
  • CLOB API (https://clob.polymarket.com) - Trading operations and order management

The SDK provides separate client interfaces for each:

/* Market data */
$client->gamma()->markets()->list();

/* Trading & Orders */
$client->clob()->orders()->create([...]);

API Reference

Client Initialization

use Danielgnh\PolymarketPhp\Client;

/* There is a way to initialize the client with custom configuration */
$client = new Client('your-api-key', [
    'gamma_base_url' => 'https://gamma-api.polymarket.com',
    'clob_base_url' => 'https://clob.polymarket.com',
    'timeout' => 30,
    'retries' => 3,
    'verify_ssl' => true,
]);

Configuration Options

The SDK supports the following configuration options:

Option Type Default Description
gamma_base_url string https://gamma-api.polymarket.com Gamma API base URL
clob_base_url string https://clob.polymarket.com CLOB API base URL
timeout int 30 Request timeout in seconds
retries int 3 Number of retry attempts for failed requests
verify_ssl bool true Whether to verify SSL certificates

Markets (Gamma API)

The Markets resource provides access to prediction market data via the Gamma API.

List Markets

$markets = $client->gamma()->markets()->list(
    filters: ['active' => true, 'category' => 'politics'],
    limit: 100,
    offset: 0
);

Parameters:

  • filters (array, optional): Filtering options for markets
  • limit (int, optional): Maximum number of results (default: 100)
  • offset (int, optional): Pagination offset (default: 0)

Returns: Array of market data

Get Market by ID

$market = $client->gamma()->markets()->get('market-id');

Parameters:

  • marketId (string): The unique identifier of the market

Returns: Market data array

Search Markets

$results = $client->gamma()->markets()->search(
    query: 'election',
    filters: ['active' => true],
    limit: 50
);

Parameters:

  • query (string): Search query string
  • filters (array, optional): Additional filtering options
  • limit (int, optional): Maximum number of results (default: 100)

Returns: Array of matching markets

Orders (CLOB API)

The Orders resource handles order management and execution via the CLOB API.

List Orders

$orders = $client->clob()->orders()->list(
    filters: ['status' => 'open'],
    limit: 100,
    offset: 0
);

Parameters:

  • filters (array, optional): Filtering options for orders
  • limit (int, optional): Maximum number of results (default: 100)
  • offset (int, optional): Pagination offset (default: 0)

Returns: Array of order data

Get Order by ID

$order = $client->clob()->orders()->get('order-id');

Parameters:

  • orderId (string): The unique identifier of the order

Returns: Order data array

Create Order

use Danielgnh\PolymarketPhp\Enums\OrderSide;
use Danielgnh\PolymarketPhp\Enums\OrderType;

$order = $client->clob()->orders()->create([
    'market_id' => 'market-id',
    'side' => OrderSide::BUY->value,
    'type' => OrderType::GTC->value,
    'price' => '0.52',
    'amount' => '10.00',
]);

Parameters:

  • orderData (array): Order details including:
    • market_id (string): Target market identifier
    • side (string): Order side - use OrderSide enum
    • type (string): Order type - use OrderType enum
    • price (string): Order price as decimal string
    • amount (string): Order amount as decimal string

Important: Always use strings for price and amount values to maintain decimal precision.

Returns: Created order data array

Cancel Order

$result = $client->clob()->orders()->cancel('order-id');

Parameters:

  • orderId (string): The unique identifier of the order to cancel

Returns: Cancellation result data

Error Handling

The SDK provides a comprehensive exception hierarchy for handling different error scenarios:

use Danielgnh\PolymarketPhp\Exceptions\{
    PolymarketException,
    AuthenticationException,
    ValidationException,
    RateLimitException,
    NotFoundException,
    ApiException
};

try {
    $market = $client->gamma()->markets()->get('invalid-id');
} catch (AuthenticationException $e) {
    // Handle 401/403 authentication errors
    echo "Authentication failed: " . $e->getMessage();
} catch (ValidationException $e) {
    // Handle 400/422 validation errors
    echo "Validation error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Handle 429 rate limit errors
    echo "Rate limit exceeded: " . $e->getMessage();
} catch (NotFoundException $e) {
    // Handle 404 not found errors
    echo "Resource not found: " . $e->getMessage();
} catch (ApiException $e) {
    // Handle other API errors (5xx)
    echo "API error: " . $e->getMessage();
} catch (PolymarketException $e) {
    // Catch-all for any SDK exception
    echo "Error: " . $e->getMessage();

    // Get additional error details
    $statusCode = $e->getCode();
    $response = $e->getResponse();
}

Enums

The SDK provides type-safe enums for API fields with fixed value sets, ensuring compile-time safety and better IDE autocomplete.

Available Enums

OrderSide

Specifies whether you're buying or selling shares:

use Danielgnh\PolymarketPhp\Enums\OrderSide;

OrderSide::BUY   // Buy shares
OrderSide::SELL  // Sell shares

OrderType

Determines the execution behavior of an order:

use Danielgnh\PolymarketPhp\Enums\OrderType;

OrderType::FOK  // Fill-Or-Kill: Execute immediately in full or cancel
OrderType::FAK  // Fill-And-Kill: Execute immediately for available shares, cancel remainder
OrderType::GTC  // Good-Til-Cancelled: Active until fulfilled or cancelled
OrderType::GTD  // Good-Til-Date: Active until specified date

OrderStatus

Indicates the current state of an order:

use Danielgnh\PolymarketPhp\Enums\OrderStatus;

OrderStatus::MATCHED    // Matched with existing order
OrderStatus::LIVE       // Resting on the order book
OrderStatus::DELAYED    // Marketable but subject to matching delay
OrderStatus::UNMATCHED  // Marketable but experiencing delay

SignatureType

For order authentication methods:

use Danielgnh\PolymarketPhp\Enums\SignatureType;

SignatureType::POLYMARKET_PROXY_EMAIL   // Email/Magic account (value: 1)
SignatureType::POLYMARKET_PROXY_WALLET  // Browser wallet (value: 2)
SignatureType::EOA                      // Externally owned account (value: 0)

Usage Example

use Danielgnh\PolymarketPhp\Enums\{OrderSide, OrderType};

$order = $client->clob()->orders()->create([
    'market_id' => 'market-id',
    'side' => OrderSide::BUY->value,
    'type' => OrderType::GTC->value,
    'price' => '0.52',
    'amount' => '10.00',
]);

Working with Decimal Values

When working with financial data (prices, amounts), always use string representation to maintain precision:

// Good - maintains precision
$order = $client->clob()->orders()->create([
    'price' => '0.52',
    'amount' => '10.00',
]);

// Bad - may lose precision
$order = $client->clob()->orders()->create([
    'price' => 0.52,  // Float loses precision!
    'amount' => 10.00,
]);

Development

Running Tests

composer test

Code Style

Format code using PHP CS Fixer:

composer cs-fix

Check code style without making changes:

composer cs-check

Static Analysis

Run PHPStan for static analysis:

composer phpstan

Test Coverage

Generate test coverage report:

composer test-coverage

Coverage reports will be generated in the coverage/ directory.

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Follow PSR-12 coding standards
  2. Write tests for new features
  3. Run composer cs-fix before committing
  4. Ensure all tests pass with composer test
  5. Run static analysis with composer phpstan

Security

If you discover any security-related issues, please email uhorman@gmail.com instead of using the issue tracker.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Resources

Support

For bugs and feature requests, please use the GitHub issue tracker.

About

PHP Framework for Polymarket API integration

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages