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.
- PHP 8.1 or higher
- Composer
Install the package via Composer:
composer require danielgnh/polymarket-phpAdd 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
<?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');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([...]);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,
]);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 |
The Markets resource provides access to prediction market data via the Gamma API.
$markets = $client->gamma()->markets()->list(
filters: ['active' => true, 'category' => 'politics'],
limit: 100,
offset: 0
);Parameters:
filters(array, optional): Filtering options for marketslimit(int, optional): Maximum number of results (default: 100)offset(int, optional): Pagination offset (default: 0)
Returns: Array of market data
$market = $client->gamma()->markets()->get('market-id');Parameters:
marketId(string): The unique identifier of the market
Returns: Market data array
$results = $client->gamma()->markets()->search(
query: 'election',
filters: ['active' => true],
limit: 50
);Parameters:
query(string): Search query stringfilters(array, optional): Additional filtering optionslimit(int, optional): Maximum number of results (default: 100)
Returns: Array of matching markets
The Orders resource handles order management and execution via the CLOB API.
$orders = $client->clob()->orders()->list(
filters: ['status' => 'open'],
limit: 100,
offset: 0
);Parameters:
filters(array, optional): Filtering options for orderslimit(int, optional): Maximum number of results (default: 100)offset(int, optional): Pagination offset (default: 0)
Returns: Array of order data
$order = $client->clob()->orders()->get('order-id');Parameters:
orderId(string): The unique identifier of the order
Returns: Order data array
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 identifierside(string): Order side - useOrderSideenumtype(string): Order type - useOrderTypeenumprice(string): Order price as decimal stringamount(string): Order amount as decimal string
Important: Always use strings for price and amount values to maintain decimal precision.
Returns: Created order data array
$result = $client->clob()->orders()->cancel('order-id');Parameters:
orderId(string): The unique identifier of the order to cancel
Returns: Cancellation result data
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();
}The SDK provides type-safe enums for API fields with fixed value sets, ensuring compile-time safety and better IDE autocomplete.
Specifies whether you're buying or selling shares:
use Danielgnh\PolymarketPhp\Enums\OrderSide;
OrderSide::BUY // Buy shares
OrderSide::SELL // Sell sharesDetermines 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 dateIndicates 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 delayFor 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)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',
]);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,
]);composer testFormat code using PHP CS Fixer:
composer cs-fixCheck code style without making changes:
composer cs-checkRun PHPStan for static analysis:
composer phpstanGenerate test coverage report:
composer test-coverageCoverage reports will be generated in the coverage/ directory.
Contributions are welcome! Please follow these guidelines:
- Follow PSR-12 coding standards
- Write tests for new features
- Run
composer cs-fixbefore committing - Ensure all tests pass with
composer test - Run static analysis with
composer phpstan
If you discover any security-related issues, please email uhorman@gmail.com instead of using the issue tracker.
This project is licensed under the MIT License - see the LICENSE file for details.
- Author: Daniel Goncharov
- Email: uhorman@gmail.com
For bugs and feature requests, please use the GitHub issue tracker.