https://github.com/danielgnh/polymarket-php
PHP Framework for Polymarket API integration
https://github.com/danielgnh/polymarket-php
api clob gamma package php polymarket polymarket-api polymarket-php
Last synced: 7 months ago
JSON representation
PHP Framework for Polymarket API integration
- Host: GitHub
- URL: https://github.com/danielgnh/polymarket-php
- Owner: danielgnh
- License: mit
- Created: 2025-11-26T15:30:40.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-12-08T12:49:26.000Z (8 months ago)
- Last Synced: 2025-12-08T19:48:46.290Z (8 months ago)
- Topics: api, clob, gamma, package, php, polymarket, polymarket-api, polymarket-php
- Language: PHP
- Homepage:
- Size: 104 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Polymarket PHP SDK
[Polymarket API](https://polymarket.com) 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?](https://docs.polymarket.com/polymarket-learn/get-started/what-is-polymarket)
[](https://packagist.org/packages/danielgnh/polymarket-php)
[](https://packagist.org/packages/danielgnh/polymarket-php)
[](https://packagist.org/packages/danielgnh/polymarket-php)
[](https://packagist.org/packages/danielgnh/polymarket-php)
[](https://github.com/danielgnh/polymarket-php/actions)
[](https://phpstan.org/)
## Requirements
- PHP 8.1 or higher
- Composer
## Installation
Install the package via Composer:
```bash
composer require danielgnh/polymarket-php
```
## Configuration
Add your polymarket credentials to your `.env` file:
```env
POLYMARKET_API_KEY=your-api-key
POLYMARKET_PRIVATE_KEY=0x...
```
Here is documentation [how to export you private key](https://docs.polymarket.com/polymarket-learn/FAQ/how-to-export-private-key)
## Quick Start
```php
gamma()->markets()->list();
/* Trading & Orders */
$client->clob()->orders()->create([...]);
```
## API Reference
### Client Initialization
```php
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
```php
$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
```php
$market = $client->gamma()->markets()->get('market-id');
```
**Parameters:**
- `marketId` (string): The unique identifier of the market
**Returns:** Market data array
#### Search Markets
```php
$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
```php
$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
```php
$order = $client->clob()->orders()->get('order-id');
```
**Parameters:**
- `orderId` (string): The unique identifier of the order
**Returns:** Order data array
#### Create Order
```php
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
```php
$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:
```php
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:
```php
use Danielgnh\PolymarketPhp\Enums\OrderSide;
OrderSide::BUY // Buy shares
OrderSide::SELL // Sell shares
```
#### OrderType
Determines the execution behavior of an order:
```php
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:
```php
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:
```php
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
```php
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:
```php
// 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
```bash
composer test
```
### Code Style
Format code using PHP CS Fixer:
```bash
composer cs-fix
```
Check code style without making changes:
```bash
composer cs-check
```
### Static Analysis
Run PHPStan for static analysis:
```bash
composer phpstan
```
### Test Coverage
Generate test coverage report:
```bash
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](LICENSE) file for details.
## Credits
- **Author**: Daniel Goncharov
- **Email**: uhorman@gmail.com
## Resources
- [Polymarket Official Website](https://polymarket.com)
- [Polymarket API Documentation](https://docs.polymarket.com)
- [Package on Packagist](https://packagist.org/packages/danielgnh/polymarket-php)
## Support
For bugs and feature requests, please use the [GitHub issue tracker](https://github.com/danielgnh/polymarket-php-sdk/issues).