README

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?

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

• Author: Daniel Goncharov
• Email: uhorman@gmail.com

Resources

• Polymarket Official Website
• Polymarket API Documentation
• Package on Packagist

Support

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