README

PHP client for the OKX v5 API. Covers the entire REST API (335 endpoints, 16 categories) and WebSocket API (53 channels). Works standalone or plugs into Laravel 11/12/13 via a Service Provider.

Go version: tigusigalpa/okx-go | Wiki

What's inside

335 REST endpoints grouped into service classes (account(), trade(), market(), etc.)
WebSocket client with auto-reconnect and ping/pong heartbeat
HMAC-SHA256 request signing
Demo trading mode (just flip a flag)
Typed DTOs for requests and responses; all prices/amounts stay as string to avoid float rounding
Laravel Service Provider, Facade, publishable config
PSR-3 logging, PSR-12 code style
PHP 8.2+ (readonly classes, named arguments)

Requirements

PHP 8.2+
Composer
Laravel 11, 12 or 13 (optional)

Installation

composer require tigusigalpa/okx-php

Laravel setup

Publish the config:

php artisan vendor:publish --tag=okx-config

Add credentials to .env:

OKX_API_KEY=your-api-key
OKX_SECRET_KEY=your-secret-key
OKX_PASSPHRASE=your-passphrase
OKX_DEMO=false

Then use the facade:

use Tigusigalpa\OKX\Facades\OKX;

$balance = OKX::account()->getBalance();

$order = OKX::trade()->placeOrder(
    instId: 'BTC-USDT',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'limit',
    sz: '0.01',
    px: '50000'
);

$ticker = OKX::market()->getTicker('BTC-USDT');

Standalone usage

use Tigusigalpa\OKX\Client;

$client = new Client(
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    passphrase: 'your-passphrase',
    // Region::Us for US/AU accounts; Region::Eea for my.okx.com accounts.
    region: \Tigusigalpa\OKX\Region::Global,
);

$balance = $client->account()->getBalance();

$order = $client->trade()->placeOrder(
    instId: 'BTC-USDT-SWAP',
    tdMode: 'cash',
    side: 'buy',
    ordType: 'market',
    sz: '100',
    tgtCcy: 'quote_ccy'
);

$trades = $client->market()->getTrades('BTC-USDT', limit: 100);

Configuration

Option	Env variable	Default
`api_key`	`OKX_API_KEY`	`''`	API key
`secret_key`	`OKX_SECRET_KEY`	`''`	Secret key
`passphrase`	`OKX_PASSPHRASE`	`''`	Passphrase
`demo`	`OKX_DEMO`	`false`	Use demo trading environment
`region`	`OKX_REGION`	`global`	`global`, `us` (also AU), `eea`, or `tr`
`base_url`	`OKX_BASE_URL`	Region-specific endpoint	Optional REST endpoint override

Regional API domains

OKX requires the API domain to match the region where the account was registered. Set OKX_REGION once; the REST and WebSocket clients then select the matching live and demo endpoints.

Account registration	`OKX_REGION`	REST endpoint	Live WebSocket host
Other regions	`global`	`https://openapi.okx.com`	`wss://ws.okx.com:8443`
US or AU (`app.okx.com`)	`us`	`https://us.okx.com`	`wss://wsus.okx.com:8443`
EEA (`my.okx.com`)	`eea`	`https://eea.okx.com`	`wss://wseea.okx.com:8443`
Turkey	`tr`	`https://tr.okx.com`	`wss://ws.okx.com:8443`

For a standalone client, pass region: Region::Us or region: Region::Eea. OKX_BASE_URL remains available for a proxy or another explicit REST override. It does not change WebSocket hosts.

REST API coverage

335 endpoints across 16 categories:

Category	#	Docs
Account	53	Trading Account
Trade	32	Order Book Trading
Market	24	Market Data
Public Data	24	Public Data
Asset	26	Funding Account
Finance	33	Financial Products
Copy Trading	26	Copy Trading
Trading Bot	44	Trading Bot
RFQ	20	Block Trading
Spread Trading	13	Spread Trading
Rubik	15	Trading Statistics
Fiat	13	Fiat
Users	8	Sub-account
Support	2	Announcements
System Status	1	Status
Affiliate	1	Affiliate

WebSocket

Public channel:

use Tigusigalpa\OKX\WebsocketClient;

$ws = new WebsocketClient(
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    passphrase: 'your-passphrase',
    region: \Tigusigalpa\OKX\Region::Eea,
);

$ws->connectPublic();

$ws->subscribe('tickers', ['instId' => 'BTC-USDT'], function ($data) {
    echo "BTC-USDT: " . $data['data'][0]['last'] . PHP_EOL;
});

$ws->run();

Private channel (authenticated automatically on connect):

$ws->connectPrivate();

$ws->subscribe('account', ['ccy' => 'BTC'], function ($data) {
    foreach ($data['data'] as $account) {
        echo "Balance: {$account['bal']} {$account['ccy']}" . PHP_EOL;
    }
});

$ws->run();

For a public channel served from the business endpoint, call connectBusiness(requiresAuth: false).

Public channels include tickers, books, books5, trades, candle*, index-tickers, mark-price, funding-rate, open-interest, liquidation-orders, and others.

Private channels include account, positions, orders, orders-algo, fills, balance_and_position, liquidation-warning, deposit-info, withdrawal-info, and others.

Demo trading

Set OKX_DEMO=true in .env, or pass isDemo: true to the constructor. Same API, sandbox environment, no real money involved.

$client = new Client(
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    passphrase: 'your-passphrase',
    isDemo: true
);

Examples

Order with attached TP/SL:

$order = $client->trade()->placeOrder(
    instId: 'BTC-USDT',
    tdMode: 'isolated',
    side: 'buy',
    ordType: 'market',
    sz: '0.1',
    attachAlgoOrds: [[
        'tpTriggerPx' => '55000',
        'tpOrdPx' => '-1', // -1 executes this TP at market price after triggering
        'tpTriggerPxType' => 'last', // last, index, or mark
        'slTriggerPx' => '48000',
        'slOrdPx' => '-1',
        'slTriggerPxType' => 'last',
    ]],
);

OKX may reject the legacy inline TP/SL fields with sCode=54070; prefer attachAlgoOrds. A typed request form is also available when it fits the application better:

use Tigusigalpa\OKX\DTO\Trade\AttachAlgoOrderRequest;
use Tigusigalpa\OKX\DTO\Trade\PlaceOrderRequest;

$order = $client->trade()->placeOrderRequest(new PlaceOrderRequest(
    instId: 'BTC-USDT-SWAP',
    tdMode: 'isolated',
    side: 'sell',
    ordType: 'market',
    sz: '1',
    attachAlgoOrds: [new AttachAlgoOrderRequest(
        tpTriggerPx: '64000',
        tpOrdPx: '-1',
        tpTriggerPxType: 'last',
        slTriggerPx: '66000',
        slOrdPx: '-1',
        slTriggerPxType: 'last',
    )],
));

Batch orders:

$orders = $client->trade()->batchOrders([
    [
        'instId' => 'BTC-USDT',
        'tdMode' => 'cash',
        'side' => 'buy',
        'ordType' => 'limit',
        'sz' => '0.01',
        'px' => '50000'
    ],
    [
        'instId' => 'ETH-USDT',
        'tdMode' => 'cash',
        'side' => 'buy',
        'ordType' => 'limit',
        'sz' => '0.1',
        'px' => '3000'
    ]
]);

Set leverage:

$client->account()->setLeverage(
    lever: '10',
    mgnMode: 'cross',
    instId: 'BTC-USDT-SWAP'
);

Historical candles:

$candles = $client->market()->getHistoryCandles(
    instId: 'BTC-USDT',
    bar: '1H',
    limit: 100
);

Withdrawal:

$withdrawal = $client->asset()->withdrawal(
    ccy: 'USDT',
    amt: '100',
    dest: '4',
    toAddr: 'your-wallet-address',
    fee: '1',
    chain: 'USDT-TRC20'
);

Error handling

Each error type has its own exception class. They all extend OKXException, which carries the raw OKX error code in $e->okxCode. The decoded response envelope is also available in $e->response, so order-specific data[0].sCode and sMsg are not lost when the top-level API code is non-zero.

use Tigusigalpa\OKX\Exceptions\AuthenticationException;
use Tigusigalpa\OKX\Exceptions\RateLimitException;
use Tigusigalpa\OKX\Exceptions\InvalidParameterException;
use Tigusigalpa\OKX\Exceptions\InsufficientFundsException;
use Tigusigalpa\OKX\Exceptions\OKXException;

try {
    $balance = $client->account()->getBalance();
} catch (AuthenticationException $e) {
    // bad credentials or signature
} catch (RateLimitException $e) {
    // slow down
} catch (InvalidParameterException $e) {
    // check your request params
} catch (InsufficientFundsException $e) {
    // not enough balance
} catch (OKXException $e) {
    // everything else from OKX
    echo "OKX error [{$e->okxCode}]: " . $e->getMessage();
}

Logging

Pass any PSR-3 logger to the constructor:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('okx');
$logger->pushHandler(new StreamHandler('okx.log', Logger::DEBUG));

$client = new Client(
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    passphrase: 'your-passphrase',
    logger: $logger
);

Credentials are never written to logs.

Testing

Unit tests:

vendor/bin/phpunit

Integration tests (needs demo credentials):

export OKX_API_KEY=your-demo-api-key
export OKX_SECRET_KEY=your-demo-secret-key
export OKX_PASSPHRASE=your-demo-passphrase
vendor/bin/phpunit -c phpunit.integration.xml

Contributing

Fork it
Create a branch (git checkout -b fix/something)
Make your changes, add tests
Push and open a PR

Code must follow PSR-12. Tests must pass.

Security

Found a vulnerability? Email sovletig@gmail.com directly. Don't open a public issue.

License

MIT. See LICENSE.

tigusigalpa / okx-php

Package info

Security

Statistics

README

What's inside

Requirements

Installation

Laravel setup

Standalone usage

Configuration

Regional API domains

REST API coverage

WebSocket

Demo trading

Examples

Error handling

Logging

Testing

Contributing

Security

License

Links