DEV Community: Igor

Full-Featured Crypto Trading with PHP: A Deep Dive into the zoomex-php Library

Igor — Mon, 16 Mar 2026 00:09:05 +0000

Introduction

The world of cryptocurrency trading is fast-paced and complex. For developers looking to build trading bots, analytics tools, or custom integrations, a reliable and easy-to-use API client is essential. While many exchanges offer APIs, navigating them can be a daunting task, involving complex authentication schemes, rate limiting, and raw JSON responses.

This is where SDKs (Software Development Kits) come in, providing a much-needed abstraction layer. Today, we're taking a deep dive into zoomex-php [1], a new, full-featured PHP/Laravel SDK for the Zoomex crypto exchange API v3 [2]. Whether you're a seasoned algo-trader or a PHP developer venturing into the crypto space, this library is designed to make your life easier.

Zoomex is a rapidly growing cryptocurrency exchange known for its high performance, with a trading engine capable of handling a high volume of transactions per second [3]. It offers a wide range of trading products, including spot and perpetual contracts for hundreds of cryptocurrencies. For developers, the Zoomex API v3 provides comprehensive access to market data, trading, and account management features.

What's Inside: A Feature-Rich SDK

The zoomex-php library is more than just a simple API wrapper. It's a complete toolkit for interacting with the Zoomex exchange, offering a wide range of features designed to streamline development and enhance productivity. Let's break down what makes this SDK stand out.

Feature	Description
Full API v3 Coverage	The library provides complete support for the Zoomex API v3, including both REST and WebSocket interfaces. This means you can access all of the exchange's features, from market data and trading to account and asset management.
Laravel Integration	For Laravel developers, `zoomex-php` offers a seamless integration experience. It includes a service provider and facade, allowing you to use the library with the familiar Laravel syntax.
Modern PHP Features	The SDK is built for modern PHP, requiring PHP 8.1+ and leveraging features like enums for type-safe and readable code. This helps to prevent common errors and makes the library easier to work with.
HMAC-SHA256 Authentication	Security is paramount in the crypto world. The library handles the complex HMAC-SHA256 request signing process for you, so you can focus on building your application without worrying about the intricacies of API authentication.
Testnet Support	The ability to switch between the mainnet and testnet environments is crucial for testing your trading strategies without risking real funds. `zoomex-php` makes this easy with a simple configuration option.
Comprehensive Testing	The library is thoroughly tested with Pest, a popular testing framework for PHP. This ensures a high level of code quality and reliability.

Getting Started: Installation and Setup

Getting started with zoomex-php is straightforward. The library is available as a Composer package, making it easy to install in any PHP project.

Installation

To install the library, simply run the following command in your project directory:

composer require tigusigalpa/zoomex-php

Standalone PHP

If you're using the library in a standalone PHP project, you can create a new client instance and configure it with your API keys:

use Tigusigalpa\Zoomex\Client;

$client = new Client([
    'api_key'    => 'YOUR_API_KEY',
    'secret_key' => 'YOUR_SECRET_KEY',
    'testnet'    => false, // Set to true for testnet
]);

The library also provides a convenient fluent interface for creating a client instance:

use Tigusigalpa\Zoomex\Client;

$client = Client::make()
    ->withApiKey('YOUR_API_KEY')
    ->withSecretKey('YOUR_SECRET_KEY')
    ->withTestnet(false);

Laravel Integration

For Laravel applications, the integration is even simpler. After installing the package, publish the configuration file:

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

This will create a config/zoomex.php file. You can then add your API credentials to your .env file:

ZOOMEX_API_KEY=your_api_key
ZOOMEX_SECRET_KEY=your_secret_key
ZOOMEX_TESTNET=false

You can then use the Zoomex facade to access the library's features:

use Tigusigalpa\Zoomex\Facades\Zoomex;

$tickers = Zoomex::market()->getTickers(/* ... */);

A Look at the Code: Practical Examples

Now that we've covered the basics, let's dive into some practical examples of how to use the zoomex-php library. These examples will demonstrate how to perform common tasks like retrieving market data, placing orders, and subscribing to real-time data streams.

Getting Market Data

One of the most common use cases for a crypto exchange SDK is to retrieve market data. The zoomex-php library makes this easy with its MarketService. For example, to get the latest tickers for the BTC/USDT linear perpetual contract, you can use the getTickers method:

use Tigusigalpa\Zoomex\Facades\Zoomex;
use Tigusigalpa\Zoomex\DTO\Market\GetTickersRequest;
use Tigusigalpa\Zoomex\Enums\Category;

$tickers = Zoomex::market()->getTickers(
    new GetTickersRequest(category: Category::LINEAR, symbol: 'BTCUSDT')
);

Notice the use of the GetTickersRequest DTO (Data Transfer Object) and the Category enum. This is a common pattern throughout the library, and it provides a clean and type-safe way to pass parameters to the API.

Placing an Order

Placing an order is just as simple. The TradeService provides a placeOrder method that accepts a PlaceOrderRequest DTO. Here's an example of how to place a limit order to buy 0.01 BTC at a price of $50,000:

use Tigusigalpa\Zoomex\DTO\Trade\PlaceOrderRequest;
use Tigusigalpa\Zoomex\Enums\{Category, OrderSide, OrderType, TimeInForce};

$order = Zoomex::trade()->placeOrder(new PlaceOrderRequest(
    category: Category::LINEAR,
    symbol: 'BTCUSDT',
    side: OrderSide::BUY,
    orderType: OrderType::LIMIT,
    qty: '0.01',
    price: '50000',
    timeInForce: TimeInForce::GTC
));

Again, the use of DTOs and enums makes the code clear, concise, and less prone to errors. You can see at a glance what parameters are required and what values are expected.

Real-Time Data with WebSockets

For applications that require real-time data, the zoomex-php library provides a WebSocket client. You can use it to subscribe to a variety of public and private data streams, such as order book updates, public trades, and private order updates.

Here's an example of how to subscribe to the order book for the BTC/USDT symbol:

use Tigusigalpa\Zoomex\WebSocket;

$ws = new WebSocket(['api_key' => '...', 'secret_key' => '...']);

$ws->subscribeOrderbook('BTCUSDT', 50, function ($data) {
    print_r($data);
});

$ws->run();

The WebSocket client runs in a loop, and you can subscribe to multiple topics. The library handles the authentication and subscription process for you, so you can focus on processing the incoming data.

Under the Hood: A Well-Designed Architecture

A well-designed SDK is more than just a collection of functions. It should have a clear and consistent architecture that makes it easy to use and extend. The zoomex-php library follows a number of best practices that contribute to its clean design.

Service-Oriented Architecture

The library is organized into a set of services, each responsible for a specific area of the API. For example, there are services for market data, trading, positions, and account management. This separation of concerns makes the library easy to navigate and understand.

Data Transfer Objects (DTOs)

As we saw in the examples, the library makes extensive use of DTOs to pass data to and from the API. This has a number of advantages:

Type Safety: DTOs provide type safety, which helps to prevent common errors and makes the code easier to reason about.
Readability: DTOs make the code more readable by clearly defining the structure of the data being passed.
Validation: DTOs can be used to validate the data before it is sent to the API, which helps to prevent invalid requests.

Enums for Type-Safe Values

The library also uses enums to represent a fixed set of values, such as order sides, order types, and time-in-force. This provides a type-safe alternative to using strings or integers, which can be error-prone.

Fluent Interface

The fluent interface for creating a client instance is a nice touch that makes the code more readable and expressive. It allows you to chain method calls together to configure the client, which is a common pattern in modern PHP libraries.

Conclusion: A Powerful Tool for PHP Developers

The zoomex-php library is a powerful and well-designed SDK that makes it easy to interact with the Zoomex crypto exchange. Its comprehensive feature set, modern architecture, and seamless Laravel integration make it an excellent choice for any PHP developer looking to build trading applications or custom integrations.

By providing a clean and consistent interface to the Zoomex API, the library allows you to focus on building your application without getting bogged down in the details of API authentication, request signing, and data parsing. Whether you're building a simple trading bot or a complex analytics platform, zoomex-php is a valuable tool that can help you get the job done.

If you're looking for a modern, reliable, and easy-to-use PHP library for the Zoomex exchange, I highly recommend checking out zoomex-php. It's a great example of how a well-designed SDK can simplify a complex domain and empower developers to build amazing things.

References

[1] tigusigalpa. (2026). zoomex-php [GitHub repository]. Retrieved from https://github.com/tigusigalpa/zoomex-php

[2] Zoomex. (n.d.). Zoomex API Documentation. Retrieved from https://zoomexglobal.github.io/docs/v3/intro

[3] CoinCodex. (2025, August 13). Zoomex Exchange Review. Retrieved from https://coincodex.com/article/71428/zoomex-exchange-review/

A Comprehensive Review of okx-php: The Best PHP/Laravel Library for the OKX API

Igor — Sun, 15 Mar 2026 02:33:15 +0000

In the world of cryptocurrency trading, speed, reliability, and ease of integration are paramount. For developers working with PHP and Laravel, having access to powerful tools for interacting with exchanges like OKX is a key success factor. Today, we will take a deep dive into the tigusigalpa/okx-php library—a modern, full-featured, and elegant PHP SDK for the latest OKX API v5.

This library is not just another API wrapper. It is a comprehensive solution designed to simplify development, increase code reliability, and provide access to all the features of one of the world's leading cryptocurrency exchanges.

Link to the repository: https://github.com/tigusigalpa/okx-php

What is okx-php?

okx-php is a PHP client for the OKX API v5 that provides developers with a convenient interface for interacting with all aspects of the exchange. The library is designed with modern PHP standards in mind (requiring PHP 8.2+) and offers full integration for both standalone projects and applications built on Laravel 11/12.

The key feature that immediately sets this package apart is its 100% API coverage. This means that every single one of the 335 REST endpoints and 53 WebSocket channels documented in the OKX API v5 is accessible through intuitive methods in your code.

Core Features

Feature	Description
Full API Coverage	Access to all 335 REST endpoints and 53 WebSocket channels.
Modern PHP	Utilizes PHP 8.2+ features, including `readonly` classes and named arguments.
Laravel Integration	Ships with a Service Provider and Facade for seamless integration into Laravel 11/12.
Standalone Mode	Can be used in any PHP 8.2+ project without framework dependencies.
Typed DTOs	All requests and responses use strictly typed Data Transfer Objects, improving code readability and IDE autocompletion.
WebSocket Client	An integrated WebSocket client with auto-reconnect functionality and heartbeat (ping/pong) support.
Security	Automatic HMAC-SHA256 signature generation for all requests.
Demo Trading Mode	Easily switch to the OKX sandbox environment for testing without using real funds.
Error Handling	A well-thought-out exception system for all types of API errors.
Logging	Supports any PSR-3 compatible logger.

Architecture and Design

Upon examining the source code of okx-php, it becomes clear that the author has paid great attention to the quality and cleanliness of the architecture. Instead of a single monolithic class, the library is divided into logical service classes that correspond to the OKX API categories.

The main Client class acts as the entry point. Through it, you gain access to the services:

$client = new \Tigusigalpa\OKX\Client(...);

// Access account endpoints
$client->account()->getBalance();

// Access trade endpoints
$client->trade()->placeOrder(...);

// Access market data
$client->market()->getTicker(...);

This approach makes the code clean, predictable, and easy to navigate. A total of 16 service classes are available, covering everything from Account and Trade to TradingBot and CopyTrading.

Type Safety with DTOs

One of the library's greatest strengths is its use of typed DTOs. Instead of working with anonymous arrays where you can easily make a key-related mistake, you work with objects whose structure is predefined. This not only prevents errors but also significantly improves the development experience thanks to IDE autocompletion.

An important detail: all numerical values representing prices or amounts are stored as string. This is a standard practice in financial programming to avoid floating-point precision issues that could lead to a loss of funds.

Installation and Setup

Getting started with the library is very simple.

1. Installation via Composer

composer require tigusigalpa/okx-php

2. Setup in Laravel

For Laravel users, the integration is nearly seamless.

a. Publish the configuration:

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

This command will create a config/okx.php file where you can configure the default settings.

b. Configure credentials in .env:

Add your API keys, obtained from your OKX account, to the .env file.

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

Setting OKX_DEMO=true will switch all requests to the OKX test environment.

c. Use the Facade:

You can now use the convenient OKX facade anywhere in your application.

use Tigusigalpa\OKX\Facades\OKX;

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

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

3. Setup in a Standalone Project

If you are not using Laravel, you simply need to create an instance of the Client class, passing all the necessary parameters to it.

use Tigusigalpa\OKX\Client;

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

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

Practical Examples

Let's look at a few use-case scenarios for the library.

Example 1: Placing an Order with Take Profit and Stop Loss

use Tigusigalpa\OKX\Facades\OKX;

$order = OKX::trade()->placeOrder(
    instId: 'BTC-USDT',
    tdMode: 'cross', // Margin mode
    side: 'buy',
    ordType: 'limit',
    sz: '0.1', // Quantity
    px: '60000', // Price
    tpTriggerPx: '65000', // Take Profit trigger price
    tpOrdPx: '-1', // Execute at market price
    slTriggerPx: '58000', // Stop Loss trigger price
    slOrdPx: '-1' // Execute at market price
);

print_r($order);

Example 2: Working with WebSocket

The library significantly simplifies subscribing to WebSocket channels. You don't have to worry about the authentication process or maintaining the connection.

use Tigusigalpa\OKX\WebsocketClient;

$ws = new WebsocketClient(
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
    passphrase: 'your-passphrase'
);

// Subscribe to the public tickers channel
$ws->connectPublic();
$ws->subscribe('tickers', ['instId' => 'BTC-USDT'], function ($data) {
    echo "BTC-USDT Last Price: " . $data['data'][0]['last'] . PHP_EOL;
});

// Subscribe to the private balance channel (authentication is automatic)
$ws->connectPrivate();
$ws->subscribe('account', ['ccy' => 'BTC'], function ($data) {
    foreach ($data['data'] as $account) {
        echo "Balance: {$account['bal']} {$account['ccy']}" . PHP_EOL;
    }
});

// Run the client to listen for messages
$ws->run();

Example 3: Error Handling

okx-php provides a set of custom exceptions, allowing for elegant handling of API errors.

use Tigusigalpa\OKX\Facades\OKX;
use Tigusigalpa\OKX\Exceptions\AuthenticationException;
use Tigusigalpa\OKX\Exceptions\RateLimitException;
use Tigusigalpa\OKX\Exceptions\OKXException;

try {
    $balance = OKX::account()->getBalance();
} catch (AuthenticationException $e) {
    // Authentication error (invalid keys)
    log_error('Bad OKX credentials');
} catch (RateLimitException $e) {
    // Rate limit exceeded
    sleep(1);
} catch (OKXException $e) {
    // Other errors from the OKX API
    log_error("OKX error [{$e->okxCode}]: " . $e->getMessage());
}

Conclusion

tigusigalpa/okx-php is, without exaggeration, an exemplary API integration library. It combines full feature coverage, a modern development approach, attention to detail (such as financial calculation accuracy), and an excellent developer experience (DX) for both beginners and seasoned developers.

If you work with PHP and plan to create trading bots, analytical tools, or any other applications that interact with the OKX exchange, this library should be your number one choice. It will save you dozens of development hours and help you avoid numerous potential pitfalls.

Don't forget to check out the GitHub repository, give it a star, and perhaps even contribute to the development of this outstanding project.

okx-go: A Production-Ready Go Client for the OKX v5 API — Deep Dive Review

Igor — Wed, 11 Mar 2026 16:31:51 +0000

Algorithmic trading in Go has never had it easier when it comes to OKX. The okx-go library, authored by Igor Sazonov, is a comprehensive, production-ready Go client for the OKX v5 API. In this article, we will take a thorough look at the library's architecture, feature set, usage patterns, and overall developer experience. Whether you are building a high-frequency trading bot, a portfolio monitoring tool, or a market data aggregator, okx-go is likely the most complete Go solution available for the OKX exchange today.

GitHub: https://github.com/tigusigalpa/okx-go
Wiki Documentation: https://github.com/tigusigalpa/okx-go/wiki

Why Go for Crypto Trading?

Go has become an increasingly popular language for building financial and trading systems. Its combination of static typing, compiled performance, excellent concurrency primitives (goroutines and channels), and a strong standard library makes it an ideal choice for latency-sensitive applications. When you need to process thousands of market data events per second, manage concurrent WebSocket connections, and execute orders with minimal overhead, Go's runtime characteristics offer a compelling advantage over interpreted languages like Python.

Despite this, the Go ecosystem for cryptocurrency exchange clients has historically lagged behind Python and JavaScript. Most major exchanges provide official SDKs only for Python, and community-maintained Go libraries are often incomplete, unmaintained, or poorly documented. okx-go aims to fill this gap for OKX specifically, and it does so with remarkable thoroughness.

What is OKX?

OKX is one of the world's largest cryptocurrency exchanges by trading volume, offering spot trading, perpetual and delivery futures, options, margin trading, and a wide range of financial products including staking, lending, and structured products. The exchange's v5 API is a unified API that covers all of these product types through a consistent interface, making it one of the most feature-rich exchange APIs available.

The OKX v5 API provides both REST and WebSocket interfaces. The REST API is used for operations that require a request-response pattern, such as placing orders or querying account balances. The WebSocket API is used for real-time data streams, such as live price feeds, order book updates, and account notifications.

Library Overview

okx-go is a Go module that wraps the OKX v5 API in an idiomatic, type-safe Go interface. It requires Go 1.21 or later (to leverage generics) and has only two dependencies: the Go standard library and gorilla/websocket. This minimal dependency footprint is a significant advantage, as it reduces the risk of dependency conflicts and keeps the library lightweight.

The library is organized into the following top-level packages and files:

File / Directory	Purpose
`okx.go`	Package entry point and top-level types
`client.go`	REST client implementation
`websocket.go`	WebSocket client implementation
`options.go`	Functional options for client configuration
`errors.go`	Error types and sentinel errors
`models/`	Type-safe request and response structs
`rest/`	REST service implementations per category
`examples/`	Practical usage examples

Installation

Installing okx-go is as simple as running a single go get command:

go get github.com/tigusigalpa/okx-go

The library is published as a Go module at github.com/tigusigalpa/okx-go and is also available on pkg.go.dev for browsable API documentation.

REST API Coverage

One of the most impressive aspects of okx-go is its breadth of REST API coverage. The library implements 335 endpoints across 16 categories, which is effectively the complete OKX v5 REST API. The following table summarizes the coverage:

Category	Endpoints	Description
Account	53	Balance, positions, leverage, account config
Trade	32	Order placement, cancellation, amendment, history
Market Data	24	Tickers, order books, candles, trades
Public Data	24	Instruments, funding rates, mark prices
Asset	26	Funding account, deposits, withdrawals, transfers
Sub-account	8	Sub-account management
Trading Bot	44	Grid trading, DCA, signal bots
Copy Trading	26	Lead trader and copy trader operations
Block Trading	20	RFQ and block trade execution
Spread Trading	13	Spread order management
Financial Products	33	Staking, savings, and structured products
Fiat	13	Fiat on/off ramp operations
Trading Statistics	15	Taker volume, long/short ratios
System	1	System status
Announcement	2	Exchange announcements
Affiliate	1	Affiliate program data
Total	335

This level of completeness is rare in community-maintained libraries. Most unofficial clients cover only the most commonly used endpoints (trading and market data), leaving developers to implement the rest themselves. With okx-go, you get the full API surface from day one.

WebSocket API Coverage

The library provides a WebSocket client that supports 53 channels across three connection types: public, private, and business. The WebSocket client handles the full lifecycle of a connection, including authentication, subscription management, heartbeats, and automatic reconnection.

Public channels (31) include real-time data that does not require authentication, such as:

tickers — best bid/ask and last trade price
books / books5 / bbo-tbt — order book at various depths
trades / trades-all — live trade feed
candle1D, candle1H, candle30m — OHLCV candlestick data
funding-rate — perpetual swap funding rates
mark-price — mark price for derivatives
liquidation-orders — real-time liquidation events
index-tickers — index price feed
economic-calendar — macro economic events

Private channels (22) require authentication and provide account-level data, such as:

account — real-time balance and equity updates
positions — live position updates
orders — order status changes
fills — trade execution notifications
balance_and_position — combined balance and position snapshot
deposit-info / withdrawal-info — funding notifications
grid-orders-spot, grid-orders-contract, grid-positions — trading bot updates

Client Configuration

The library uses the functional options pattern for client configuration, which is idiomatic Go and provides a clean, extensible API. The following options are available:

Option	Description	Default
`WithHTTPClient(c)`	Provide a custom `*http.Client`	`&http.Client{Timeout: 30s}`
`WithBaseURL(url)`	Override the base REST URL	`https://www.okx.com`
`WithDemoTrading()`	Enable demo/simulated trading mode	off
`WithTimeout(d)`	Set the default request timeout	`30s`
`WithRateLimiter(true)`	Enable the built-in rate limiter	off
`WithLogger(l)`	Provide a custom logger implementation	no-op

For example, to create a client with demo trading enabled, a custom timeout, and rate limiting:

client := okx.NewRestClient(
    os.Getenv("OKX_API_KEY"),
    os.Getenv("OKX_SECRET_KEY"),
    os.Getenv("OKX_PASSPHRASE"),
    okx.WithDemoTrading(),
    okx.WithTimeout(10*time.Second),
    okx.WithRateLimiter(true),
)

Authentication

OKX uses a three-component authentication scheme: an API key, a secret key, and a passphrase. For each authenticated REST request, the library automatically computes an HMAC-SHA256 signature and attaches the required headers:

OK-ACCESS-KEY — your API key
OK-ACCESS-SIGN — the computed signature
OK-ACCESS-TIMESTAMP — the current UTC timestamp in ISO 8601 format
OK-ACCESS-PASSPHRASE — your passphrase

The signature is computed as Base64(HMAC-SHA256(timestamp + method + requestPath + body, secretKey)). All of this is handled transparently by the library, so you never need to deal with the signing logic directly.

For WebSocket private channels, the library handles the login flow automatically via ws.Login(ctx), which sends the appropriate authentication message to the server.

The library's documentation strongly recommends storing credentials in environment variables rather than hardcoding them, which is a security best practice that should always be followed:

client := okx.NewRestClient(
    os.Getenv("OKX_API_KEY"),
    os.Getenv("OKX_SECRET_KEY"),
    os.Getenv("OKX_PASSPHRASE"),
)

Getting Started: REST Client

Getting started with the REST client is straightforward. Here is a complete example that demonstrates how to get your account balance and place a limit order:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    okx "github.com/tigusigalpa/okx-go"
    "github.com/tigusigalpa/okx-go/models"
)

func main() {
    client := okx.NewRestClient(
        os.Getenv("OKX_API_KEY"),
        os.Getenv("OKX_SECRET_KEY"),
        os.Getenv("OKX_PASSPHRASE"),
        okx.WithDemoTrading(),
    )

    ctx := context.Background()

    // Get account balance
    balances, err := client.Account.GetBalance(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    for _, b := range balances {
        fmt.Printf("Total Equity: %s\n", *b.TotalEq)
    }

    // Place a limit order
    px := "30000"
    order := models.PlaceOrderRequest{
        InstID:  "BTC-USDT",
        TdMode:  "cash",
        Side:    "buy",
        OrdType: "limit",
        Px:      &px,
        Sz:      "0.01",
    }

    result, err := client.Trade.PlaceOrder(ctx, order)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Order ID: %s\n", result[0].OrdID)
}

The REST client is organized into service objects that mirror the OKX API categories. For example, client.Account provides all account-related endpoints, client.Trade provides trading endpoints, client.Market provides market data endpoints, and so on. This organization makes it intuitive to discover and use the API.

Getting Started: WebSocket Client

The WebSocket client supports three types of connections: public (no authentication required), private (requires login), and business (for business-specific data). Here is how to subscribe to a public real-time ticker feed:

ws := okx.NewWSClient("", "", "", okx.WSPublicURL)

ctx := context.Background()
if err := ws.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer ws.Close()

ch, err := ws.Subscribe(ctx, "tickers", map[string]interface{}{
    "instId": "BTC-USDT",
})
if err != nil {
    log.Fatal(err)
}

for msg := range ch {
    fmt.Printf("Ticker update: %s\n", msg)
}

For private channels, you need to authenticate after connecting:

ws := okx.NewWSClient(
    os.Getenv("OKX_API_KEY"),
    os.Getenv("OKX_SECRET_KEY"),
    os.Getenv("OKX_PASSPHRASE"),
    okx.WSPrivateURL,
)

ctx := context.Background()
if err := ws.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer ws.Close()

if err := ws.Login(ctx); err != nil {
    log.Fatal(err)
}

ch, err := ws.Subscribe(ctx, "orders", map[string]interface{}{
    "instType": "SPOT",
})
if err != nil {
    log.Fatal(err)
}

for msg := range ch {
    fmt.Printf("Order update: %s\n", msg)
}

The WebSocket client automatically handles heartbeats (ping/pong every 25 seconds) and reconnects with exponential backoff if the connection is lost. You do not need to implement any of this logic yourself.

Demo Trading Mode

One of the most developer-friendly features of okx-go is its first-class support for OKX's demo trading environment. By passing okx.WithDemoTrading() to the REST client constructor, the library automatically adds the x-simulated-trading: 1 header to all requests, routing them to the demo environment. For WebSocket connections, dedicated demo URLs are provided:

okx.WSDemoPublicURL
okx.WSDemoPrivateURL
okx.WSDemoBusinessURL

This makes it trivially easy to test your trading logic against a live-like environment without risking real funds. The OKX demo environment mirrors the production environment closely, including order matching, funding rates, and liquidation mechanics.

Error Handling

okx-go provides a well-structured error handling system. API errors are wrapped in a custom OKXError type:

type OKXError struct {
    Code    string // OKX error code (e.g., "50011")
    Message string // Human-readable error message
    Raw     []byte // Raw JSON response body
}

In addition to this custom type, the library defines a set of sentinel errors for the most common failure scenarios, allowing you to use the idiomatic errors.Is pattern:

okx.ErrUnauthorized — invalid or missing credentials
okx.ErrRateLimited — API rate limit exceeded
okx.ErrInvalidParameter — malformed request parameter
okx.ErrNotFound — requested resource does not exist
okx.ErrInternalServer — server-side error
okx.ErrBadRequest — malformed request
okx.ErrForbidden — access denied
okx.ErrServiceUnavail — service temporarily unavailable

A typical error handling block might look like this:

balances, err := client.Account.GetBalance(ctx, nil)
if err != nil {
    if errors.Is(err, okx.ErrUnauthorized) {
        log.Fatal("Invalid API credentials — check your API key and passphrase")
    }
    if errors.Is(err, okx.ErrRateLimited) {
        // Implement exponential backoff and retry
        time.Sleep(time.Second)
    }
    if okxErr, ok := err.(*okx.OKXError); ok {
        log.Printf("OKX API error %s: %s", okxErr.Code, okxErr.Message)
    }
}

The wiki's Error Handling page also provides a comprehensive table of common OKX error codes (such as 50011 for rate limit exceeded, 50100 for invalid API key, and 50102 for invalid signature), along with patterns for implementing retry logic with exponential backoff.

Pagination

OKX uses cursor-based pagination for endpoints that return lists of historical data. The library provides a generic Paginator[T] helper that abstracts away the pagination logic, making it easy to retrieve all results from a paginated endpoint without writing boilerplate loop code:

paginator := models.NewPaginator(func(after string) ([]models.Order, string, error) {
    orders, err := client.Trade.GetOrdersHistory(
        ctx, "SPOT", nil, nil, nil, nil, nil, nil,
        &after, nil, nil, nil, nil,
    )
    if err != nil {
        return nil, "", err
    }
    var next string
    if len(orders) > 0 {
        next = orders[len(orders)-1].OrdID
    }
    return orders, next, nil
})

allOrders, err := paginator.All()
fmt.Printf("Retrieved %d total orders\n", len(allOrders))

Advanced Usage Examples

The library's examples/ directory and wiki contain a rich set of practical examples. Here are a few highlights that demonstrate the library's capabilities in real-world scenarios.

Placing an Order with Stop Loss and Take Profit

px := "30000"
tpPx := "35000"
slPx := "28000"

order := models.PlaceOrderRequest{
    InstID:      "BTC-USDT",
    TdMode:      "cash",
    Side:        "buy",
    OrdType:     "limit",
    Px:          &px,
    Sz:          "0.001",
    TpTriggerPx: &tpPx,
    TpOrdPx:     &tpPx,
    SlTriggerPx: &slPx,
    SlOrdPx:     &slPx,
}

result, err := client.Trade.PlaceOrder(ctx, order)

Monitoring Multiple Instruments via WebSocket

ws := okx.NewWSClient("", "", "", okx.WSPublicURL)
ws.Connect(ctx)
defer ws.Close()

instruments := []string{"BTC-USDT", "ETH-USDT", "SOL-USDT"}

for _, inst := range instruments {
    ch, _ := ws.Subscribe(ctx, "tickers", map[string]interface{}{
        "instId": inst,
    })
    go func(instrument string, channel <-chan []byte) {
        for msg := range channel {
            fmt.Printf("[%s] %s\n", instrument, msg)
        }
    }(inst, ch)
}

select {} // Keep running

Batch Order Placement

orders := []models.PlaceOrderRequest{
    {InstID: "BTC-USDT", TdMode: "cash", Side: "buy", OrdType: "market", Sz: "0.001"},
    {InstID: "ETH-USDT", TdMode: "cash", Side: "buy", OrdType: "market", Sz: "0.01"},
}

results, err := client.Trade.PlaceBatchOrders(ctx, orders)
for _, r := range results {
    fmt.Printf("Order %s: %s\n", r.OrdID, r.SMsg)
}

Setting Leverage for Futures

req := models.SetLeverageRequest{
    InstID:  "BTC-USDT-SWAP",
    Lever:   "10",
    MgnMode: "cross",
}

result, err := client.Account.SetLeverage(ctx, req)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Leverage set to %s\n", result[0].Lever)

Testing

okx-go includes both unit tests and integration tests. Unit tests can be run without any credentials:

go test ./...

Integration tests run against the OKX demo environment and require valid demo API credentials:

OKX_API_KEY=... OKX_SECRET_KEY=... OKX_PASSPHRASE=... go test -tags=integration ./...

The inclusion of integration tests is a strong signal of the library's commitment to correctness. Many community libraries lack integration tests entirely, which can lead to subtle bugs that only surface in production.

Documentation

The library is accompanied by a comprehensive wiki at https://github.com/tigusigalpa/okx-go/wiki, which contains 12 pages covering:

Installation — step-by-step setup guide
Getting Started — quick introduction with basic examples
REST API Guide — detailed documentation for all REST categories with code examples
WebSocket Guide — complete guide to WebSocket connections, subscriptions, and advanced usage
Authentication — explanation of the authentication mechanism and security best practices
Error Handling — comprehensive guide to error types, sentinel errors, and retry patterns
Configuration — all available client options explained
Examples — a rich collection of practical code examples
API Reference — auto-generated API reference
FAQ — answers to common questions

This level of documentation is exceptional for a community-maintained library and significantly lowers the barrier to entry for new users.

Strengths and Considerations

Strengths:

Complete coverage of the OKX v5 API (335 REST endpoints, 53 WebSocket channels)
Type-safe models with Go generics for a robust developer experience
Minimal dependencies (stdlib + gorilla/websocket)
First-class demo trading support
Built-in rate limiter and automatic WebSocket reconnection
Comprehensive wiki documentation with practical examples
Integration tests against the demo environment
Idiomatic Go design (functional options, context.Context, sentinel errors)
Thread-safe and production-ready

Considerations:

As an unofficial library, it is not maintained by OKX directly; API changes may require updates
The library is relatively new (v1.0.0), so it has not yet accumulated a large community of users
WebSocket message parsing returns raw []byte, requiring the consumer to unmarshal into their own structs

Conclusion

okx-go is a remarkably complete and well-engineered Go client for the OKX v5 API. Its comprehensive API coverage, idiomatic Go design, minimal dependencies, and excellent documentation make it the go-to choice for Go developers building applications on top of the OKX exchange. The inclusion of demo trading support, a built-in rate limiter, automatic WebSocket reconnection, and integration tests demonstrates a commitment to production quality that is rare in community-maintained libraries.

If you are building a trading bot, a portfolio tracker, a market data service, or any other application that needs to interact with OKX from Go, okx-go is the library you should reach for first.

GitHub Repository: https://github.com/tigusigalpa/okx-go
Wiki Documentation: https://github.com/tigusigalpa/okx-go/wiki

Disclaimer: okx-go is an unofficial, community-maintained library and is not affiliated with or endorsed by OKX. Always test your code thoroughly in the demo environment before deploying to production with real funds.

A Deep Dive into bingx-python: The Unofficial Python SDK for the BingX Crypto Exchange

Igor — Mon, 09 Mar 2026 08:12:55 +0000

The world of cryptocurrency trading is fast-paced and competitive. To succeed, traders need access to reliable and efficient tools that can help them automate their strategies and react quickly to market changes. The BingX exchange is a popular platform for crypto traders, offering a wide range of features, including perpetual futures, spot trading, and copy trading. However, to make the most of what BingX has to offer, developers need a way to interact with its API programmatically. This is where bingx-python comes in.

bingx-python is an unofficial Python client library for the BingX cryptocurrency exchange API. It provides a comprehensive and easy-to-use interface for interacting with all of the exchange's features, from market data and account management to trading and WebSocket streaming. The library is designed to be both powerful and developer-friendly, with a clean and intuitive API, extensive documentation, and a strong focus on security.

This article will provide a deep dive into the bingx-python library, exploring its features, architecture, and usage. We will cover everything you need to know to get started with the library, from installation and basic setup to advanced trading strategies and WebSocket integration. Whether you are a seasoned algorithmic trader or a Python developer looking to explore the world of cryptocurrency, this article will show you how bingx-python can help you take your trading to the next level.

What is bingx-python?

bingx-python is a third-party Python library that provides a convenient and powerful way to interact with the BingX cryptocurrency exchange's API. It is not an official library from BingX, but it is a well-maintained and comprehensive open-source project that has been designed to make it easy for Python developers to build their own trading bots, analysis tools, and other applications that leverage the full power of the BingX platform. The library is built on top of the popular requests library for making HTTP requests and websockets for real-time data streaming. It also includes a number of other features that make it a great choice for both beginners and experienced developers, such as:

A clean and intuitive API: The library's API is designed to be easy to learn and use, with a consistent and predictable structure.
Comprehensive documentation: The library comes with extensive documentation that covers all of its features and provides numerous examples.
A strong focus on security: The library includes a number of security features to help protect your API keys and prevent unauthorized access to your account.
Support for all of BingX's features: The library provides full support for all of BingX's features, including USDT-M and Coin-M perpetual futures, spot trading, copy trading, and sub-accounts.

Key Features

bingx-python is packed with features that make it a powerful and versatile tool for cryptocurrency traders and developers. Here are some of its key features:

Comprehensive API Coverage

The library provides access to over 170 methods, covering all of the features of the BingX API. This includes:

Market Service: Get real-time market data, including symbols, prices, candles, and order book depth.
Account Service: Manage your account, including your balance, positions, leverage, and margin.
Trade Service: Place and manage orders, view your trade history, and manage your positions.
Wallet Service: Manage your wallet, including deposits, withdrawals, and wallet addresses.
Spot Account Service: Manage your spot account, including your balance and transfers.
Sub-Account Service: Manage your sub-accounts, including API keys and transfers.
Copy Trading Service: Automate your copy trading strategies.
Contract Service: Access the standard contract API.
Coin-M Perpetual Futures: Trade crypto-margined contracts.

Security

Security is a top priority for bingx-python. The library includes a number of features to help protect your API keys and prevent unauthorized access to your account, including:

HMAC-SHA256 request signing: All authenticated requests are signed with an HMAC-SHA256 signature to ensure that they have not been tampered with.
Automatic timestamp validation: The library automatically validates the timestamp of each request to prevent replay attacks.
base64 and hex signature encoding: The library supports both base64 and hex signature encoding.
recvWindow for replay attack protection: The library uses a recvWindow to protect against replay attacks.

WebSocket Support

bingx-python provides full support for WebSocket streaming, allowing you to receive real-time market data and account updates. This is essential for building high-frequency trading bots and other applications that require low-latency data.

Developer Experience

The library is designed to be easy to use and developer-friendly. It includes a number of features that make it a great choice for both beginners and experienced developers, such as:

Type hints: The library includes type hints throughout, which can help you catch errors early and improve the readability of your code.
Custom exceptions: The library includes custom exceptions for different error types, which can help you handle errors more effectively.
Clean and intuitive API: The library's API is designed to be easy to learn and use, with a consistent and predictable structure.
Extensive documentation and examples: The library comes with extensive documentation and examples that cover all of its features.

Getting Started

Getting started with bingx-python is a straightforward process. This section will guide you through the installation of the library and the initial setup of the client.

Installation

The library can be easily installed using pip, the Python package manager. Open your terminal or command prompt and enter the following command:

pip install bingx-python

Alternatively, if you want to work with the latest development version, you can clone the repository from GitHub and install it from the source:

git clone https://github.com/tigusigalpa/bingx-python.git
cd bingx-python
pip install -e .

Obtaining API Keys

Before you can start using the library, you will need to obtain an API key and secret key from the BingX website. Here is how you can do that:

Log in to your BingX account and navigate to the API settings page.
Click on the "Create API" button.
Give your API key a descriptive name and configure the necessary permissions. For security reasons, it is recommended to only grant the permissions that are absolutely necessary for your application.
Click on the "Create" button. Your API key and secret key will be displayed. Make sure to save them in a secure location, as the secret key will only be shown once.

Initializing the Client

Once you have your API key and secret key, you can initialize the BingXClient. The client is the main entry point for interacting with the BingX API. Here is how you can initialize it:

from bingx import BingXClient

# Initialize the client
client = BingXClient(
    api_key="your_api_key_here",
    api_secret="your_api_secret_here",
)

Make sure to replace "your_api_key_here" and "your_api_secret_here" with your actual API key and secret key. It is highly recommended to use environment variables or a configuration file to store your API keys, rather than hardcoding them in your code.

Usage

Now that you have installed the library and initialized the client, let's explore some of the common operations you can perform with bingx-python. The library is organized into a number of services, each of which corresponds to a different area of the BingX API.

Market Service

The Market Service provides access to a wide range of market data, including real-time prices, order book depth, and candlestick data. Here are some examples of how you can use the Market Service:

Getting the Latest Price

You can get the latest price of a trading pair using the get_latest_price() method:

# Get the latest price of BTC-USDT
price_data = client.market().get_latest_price("BTC-USDT")
price = price_data['data']['price']
print(f"The latest price of BTC-USDT is: {price}")

Getting the Order Book

The order book, or depth, provides a snapshot of the current buy and sell orders for a trading pair. You can get the order book using the get_depth() method:

# Get the order book for BTC-USDT
depth = client.market().get_depth("BTC-USDT", 20)
print(depth)

Getting Candlestick Data

Candlestick data, or klines, provides a historical view of the price of a trading pair. You can get candlestick data using the get_klines() method:

# Get the last 100 1-hour candles for BTC-USDT
klines = client.market().get_klines("BTC-USDT", "1h", 100)
print(klines)

Account Service

The Account Service allows you to manage your BingX account, including checking your balance, viewing your open positions, and setting your leverage.

Getting Your Account Balance

You can retrieve your account balance using the get_balance() method:

# Get your account balance
balance = client.account().get_balance()
print(balance)

Getting Your Positions

To see your current open positions, you can use the get_positions() method:

# Get all open positions
positions = client.account().get_positions()
print(positions)

# Get positions for a specific symbol
btc_positions = client.account().get_positions("BTC-USDT")
print(btc_positions)

Setting Leverage

You can adjust the leverage for a specific symbol using the set_leverage() method:

# Set leverage for BTC-USDT to 10x for both long and short positions
client.account().set_leverage("BTC-USDT", "BOTH", 10)

Trade Service

The Trade Service is the heart of any trading bot, and bingx-python provides a comprehensive set of methods for placing and managing orders.

Placing an Order

You can place a new order using the create_order() method. This method accepts a dictionary of order parameters, including the symbol, side (buy or sell), type (market or limit), and quantity.

# Place a market buy order for 0.001 BTC
order = client.trade().create_order({
    "symbol": "BTC-USDT",
    "side": "BUY",
    "type": "MARKET",
    "quantity": 0.001
})
print(order)

# Place a limit sell order for 0.01 ETH at a price of 3000 USDT
limit_order = client.trade().create_order({
    "symbol": "ETH-USDT",
    "side": "SELL",
    "type": "LIMIT",
    "quantity": 0.01,
    "price": 3000
})
print(limit_order)

The library also provides convenient "quick methods" for placing common order types:

# Place a spot market buy order
client.trade().spot_market_buy("BTC-USDT", 0.001)

# Place a futures market long order
client.trade().futures_long_market("BTC-USDT", 100, 10) # 100 USDT worth, 10x leverage

Managing Orders

Once you have placed an order, you can manage it using the methods provided by the Trade Service.

# Get a list of your open orders
open_orders = client.trade().get_open_orders("BTC-USDT")
print(open_orders)

# Cancel a specific order
client.trade().cancel_order("BTC-USDT", "order_id_to_cancel")

# Cancel all open orders for a symbol
client.trade().cancel_all_orders("BTC-USDT")

WebSocket Streaming

For applications that require real-time data, bingx-python provides a powerful and easy-to-use WebSocket client. The WebSocket client allows you to subscribe to a variety of data streams, including trades, klines, and order book depth.

Here is an example of how you can use the MarketDataStream to subscribe to real-time trade and kline data for BTC-USDT:

from bingx.websocket import MarketDataStream

# Define a message handler
def on_message(data):
    print(f"Received: {data}")

# Create a market data stream
market_stream = MarketDataStream()
market_stream.connect()

# Subscribe to trade and kline streams
market_stream.subscribe_trade("BTC-USDT")
market_stream.subscribe_kline("BTC-USDT", "1m")

# Set the message handler and start listening for messages
market_stream.on_message(on_message)
market_stream.listen_async()

The library also provides an AccountDataStream for receiving private account updates, such as balance changes and order updates.

Error Handling

Robust error handling is crucial for building reliable trading applications. bingx-python provides a set of custom exceptions that make it easy to handle different types of errors that may occur when interacting with the BingX API.

The base exception class is BingXException, and all other exceptions inherit from it. This allows you to catch all library-specific errors with a single except block. The library also provides more specific exceptions for common API errors, such as AuthenticationException, RateLimitException, and InsufficientBalanceException.

Here is an example of how you can use a try...except block to handle potential errors when fetching your account balance:

from bingx.exceptions import (
    BingXException,
    APIException,
    AuthenticationException,
    RateLimitException,
    InsufficientBalanceException
)

try:
    balance = client.account().get_balance()
except AuthenticationException as e:
    print(f"Authentication Error: {e}")
except RateLimitException as e:
    print(f"Rate Limit Exceeded: {e}")
except InsufficientBalanceException as e:
    print(f"Insufficient Balance: {e}")
except APIException as e:
    print(f"API Error: {e}")
except BingXException as e:
    print(f"An unexpected error occurred: {e}")

By using these custom exceptions, you can write more granular and effective error handling logic in your applications.

Advanced Features

Beyond the core functionalities, bingx-python also supports more advanced features for sophisticated trading strategies.

Coin-M Perpetual Futures

In addition to the standard USDT-margined futures, the library provides full support for Coin-M perpetual futures. These contracts are margined and settled in cryptocurrency (e.g., BTC, ETH) instead of a stablecoin. The coinm client provides a dedicated set of methods for interacting with these markets.

# Get the ticker for a Coin-M contract
ticker = client.coinm().market().get_ticker("BTC-USD")
print(ticker)

# Place a market order for a Coin-M contract
order = client.coinm().trade().create_order({
    "symbol": "BTC-USD",
    "side": "BUY",
    "positionSide": "LONG",
    "type": "MARKET",
    "quantity": 100
})
print(order)

Sub-Account Management

For traders who manage multiple portfolios, the Sub-Account Service is an invaluable feature. It allows you to create and manage sub-accounts, transfer assets between them, and manage their API keys programmatically.

# Create a new sub-account
sub_account = client.sub_account().create_sub_account("MyNewSubAccount")
print(sub_account)

# Transfer assets from the main account to a sub-account
client.sub_account().internal_transfer(
    "main_account_uid",
    "sub_account_uid",
    "USDT",
    100
)

Conclusion

bingx-python is a powerful and comprehensive Python library that provides a first-class developer experience for interacting with the BingX API. Its extensive feature set, clean API design, and strong focus on security make it an excellent choice for building a wide range of cryptocurrency trading applications, from simple market data analysis tools to sophisticated high-frequency trading bots.

This article has provided a detailed overview of the library, covering its key features, installation, and usage. We have explored how to use the various services to access market data, manage your account, place orders, and stream real-time data with WebSockets. With the knowledge you have gained from this article, you are now well-equipped to start building your own powerful trading applications with bingx-python.

Whether you are a hobbyist looking to automate your trading strategies or a professional algorithmic trader, bingx-python provides the tools you need to succeed in the fast-paced world of cryptocurrency trading. The library is actively maintained and the developer is responsive to issues and feature requests, making it a reliable and future-proof choice for your trading needs.

Architecture and Project Structure

Understanding the architecture of bingx-python can help you use it more effectively and contribute to its development. The library is organized into a clean and logical structure, with a clear separation of concerns between the different modules.

The main package is located in the bingx/ directory and is organized as follows. The client.py file contains the main BingXClient class, which is the primary entry point for the library. The coinm_client.py file contains the CoinMClient class, which provides access to the Coin-M perpetual futures API. The exceptions.py file contains the custom exception classes. The http/ directory contains the base HTTP client, which handles request signing and other low-level HTTP operations. The services/ directory contains the individual service modules, one for each area of the BingX API. Finally, the websocket/ directory contains the WebSocket client modules.

This modular architecture makes the library easy to extend and maintain. If BingX adds new features to its API, it is straightforward to add new methods to the existing service modules or create new ones.

Supported Services at a Glance

The following table provides a summary of all the services supported by bingx-python and the number of methods available in each:

Service	Category	Methods
Market Service	USDT-M Futures	40
Account Service	USDT-M Futures	25
Trade Service	USDT-M Futures	30
Wallet Service	USDT-M Futures	5
Spot Account Service	USDT-M Futures	7
Sub-Account Service	USDT-M Futures	20
Copy Trading Service	USDT-M Futures	13
Contract Service	USDT-M Futures	3
Listen Key Service	USDT-M Futures	3
Coin-M Market	Coin-M Futures	6
Coin-M Trade	Coin-M Futures	17
Coin-M Listen Key	Coin-M Futures	3
Total		172+

Exception Hierarchy

The library's exception hierarchy is designed to be both comprehensive and easy to use. The following table summarizes the available exception classes and the conditions under which they are raised:

Exception	Raised When
`BingXException`	Base exception; covers network errors and invalid responses
`APIException`	The API returned an error code
`AuthenticationException`	Invalid API key or secret (error codes 100001–100004)
`RateLimitException`	Too many requests have been made (error code 100005)
`InsufficientBalanceException`	The account does not have enough funds (error code 200001)

Testing

bingx-python includes a comprehensive test suite that covers the core functionality of the library. The tests are written using pytest and can be run with the following commands:

# Install development dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest tests/ -v

# Run tests with coverage report
pytest tests/ --cov=bingx

The test suite includes unit tests for the HTTP client, the exception classes, and the main client. This ensures that the library behaves correctly and that any changes to the codebase do not introduce regressions.

Multi-Language Ecosystem

One of the unique aspects of the bingx-python library is that it is part of a broader multi-language ecosystem. The same author, Igor Sazonov, has also developed equivalent SDKs for PHP and Go. This means that if you are working in a polyglot environment or need to switch languages for a specific part of your project, you can rely on a consistent API design across all three SDKs. This is a significant advantage for teams that work with multiple programming languages.

Supercharge Your PHP and Laravel Apps with Manus AI: A Deep Dive into the `manus-ai-php` SDK

Igor — Sat, 07 Mar 2026 05:19:11 +0000

The artificial intelligence landscape is no longer confined to Python and Node.js. Thanks to a growing ecosystem of community-driven libraries, PHP and Laravel developers can now integrate powerful AI capabilities into their applications with ease. One of the most exciting recent developments in this space is the release of tigusigalpa/manus-ai-php, a comprehensive, open-source PHP SDK for the Manus AI platform. [1]

For those unfamiliar, Manus AI is not just another large language model (LLM) API. It's a full-fledged autonomous AI agent platform designed to handle complex, multi-step tasks that go far beyond simple text generation. [2] While a traditional AI API might respond to a prompt with a block of text, the Manus API allows you to delegate entire workflows—such as conducting in-depth research, analyzing data, generating reports, or even writing code—to an autonomous agent that can plan, use tools, and deliver complete, structured results. [3]

This distinction is crucial. It represents a shift from prompt-and-response interactions to true task delegation. The manus-ai-php SDK bridges the gap between this powerful platform and the robust, scalable applications built with PHP and Laravel. This article provides an in-depth review of the SDK, exploring its architecture, features, and practical applications for developers looking to build the next generation of AI-powered services.

Core Features and Architecture: A Well-Crafted Foundation

A deep dive into the SDK's source code reveals a thoughtfully designed architecture that prioritizes clarity, flexibility, and adherence to modern PHP standards. It successfully avoids the monolithic, hard-to-maintain structure that can plague community libraries, opting instead for a clean, modular design.

At the heart of the package is the ManusAIClient, a lean and focused class responsible for all communication with the Manus AI REST API. It handles HTTP requests, authentication, and basic response parsing. However, the real elegance of the SDK lies in its supporting components, which are organized into distinct namespaces:

Directory	Purpose
`src/`	The core logic of the SDK, including the main client and helper classes.
`src/Contracts/`	(Future-proofing) Defines interfaces for key components, allowing for custom implementations.
`src/Exceptions/`	A set of custom exception classes for granular error handling (e.g., `ApiException`, `InvalidPayloadException`).
`src/Helpers/`	Contains invaluable helper classes like `AgentProfile`, `TaskAttachment`, and `WebhookHandler` that simplify complex data structures.
`src/Laravel/`	Houses all the Laravel-specific integration components, including the `ManusAIServiceProvider`, `ManusAIFacade`, and Artisan commands.

This separation of concerns is a significant strength. The core SDK has no hard dependency on Laravel, making it perfectly viable for use in any PHP project, including those built with Symfony, Slim, or even vanilla PHP. The Laravel integration is an enhancement built on top of this solid foundation, not a requirement.

Key Architectural Highlights:

PSR-4 and PSR-12 Compliance: The code is clean, readable, and follows established community standards, making it easy for new developers to understand and contribute. [4]
Guzzle HTTP Client: By leveraging the popular and robust Guzzle library for HTTP communication, the SDK ensures reliable and battle-tested request handling. [5]
Helper Classes for Complex Payloads: Instead of forcing developers to construct complex arrays manually, the SDK provides helper classes like TaskAttachment and AgentProfile. These helpers use static methods and constants to create the correct data structures for API calls, reducing errors and improving code readability.

// Instead of this:
$attachment = [ 'type' => 'file_id', 'file_id' => 'file_123' ];

// You can write this:
use Tigusigalpa\ManusAI\Helpers\TaskAttachment;
$attachment = TaskAttachment::fromFileId('file_123');

This fluent, expressive syntax is a recurring theme throughout the SDK and significantly enhances the developer experience.

Seamless Laravel Integration: Built for Artisans

While the SDK is framework-agnostic, its first-class support for Laravel is where it truly shines. The author, Igor Sazonov, has clearly invested significant effort into making the integration feel native to the Laravel ecosystem. [6]

Auto-Discovery and Configuration

Thanks to Laravel's package auto-discovery feature, installation is a breeze. After a simple composer require, the ManusAIServiceProvider is automatically registered. This provider handles binding the ManusAIClient into the service container, making it available for dependency injection anywhere in your application.

Configuration is managed through a config/manus-ai.php file, which can be published using the standard vendor:publish command. This allows developers to set their API key, default agent profile, and other parameters in the familiar .env file, keeping sensitive credentials out of version control.

MANUS_AI_API_KEY=your-api-key-here
MANUS_AI_DEFAULT_AGENT_PROFILE=manus-1.6
MANUS_AI_DEFAULT_TASK_MODE=agent

The `ManusAI` Facade

For developers who prefer the convenience of Laravel's facades, the SDK provides ManusAI. This offers a static, expressive syntax for interacting with the API, which is perfect for quick prototyping or use in contexts where dependency injection is less convenient.

use Tigusigalpa\ManusAI\Laravel\ManusAI;

// Create a task using the facade
$result = ManusAI::createTask("Generate a list of 10 blog post ideas about Laravel.");

// Get task details
$task = ManusAI::getTask($result["task_id"]);

This is a clean and idiomatic implementation of the facade pattern, providing a simple entry point to the SDK's functionality without cluttering the global namespace.

Artisan Commands for Task Management

A standout feature of the Laravel integration is its suite of Artisan commands. These commands allow developers to interact with the Manus AI platform directly from the command line, which is incredibly useful for testing, debugging, and manual task management.

Command	Description
`php artisan manus-ai:test`	Verifies the API key and connection to the Manus AI platform.
`php artisan manus-ai:task:create`	Creates a new task with a specified prompt.
`php artisan manus-ai:task:list`	Lists existing tasks with filtering options.
`php artisan manus-ai:task:get`	Retrieves the details and output of a specific task.
`php artisan manus-ai:task:delete`	Deletes a task from the platform.

These commands are well-documented and provide a powerful tool for managing AI workflows without ever leaving the terminal. This demonstrates a deep understanding of the Laravel developer's workflow and a commitment to providing a superior developer experience.

Practical Use Cases: From Content Generation to Data Analysis

The true value of this SDK is realized when you start applying it to real-world problems. The comprehensive README provides a wealth of examples that serve as an excellent starting point. [1] Let's explore a few common scenarios.

1. Advanced Content Generation

Imagine you need to generate a detailed blog post, complete with SEO keywords and a specific tone. With manus-ai-php, this is remarkably straightforward. Because Manus AI is an agent, you can provide a much more detailed and nuanced prompt than you would with a simple text generation model.

use Tigusigalpa\ManusAI\Laravel\ManusAI;

$prompt = 'Write a 1500-word blog post about the benefits of AI in e-commerce. ' . 
          'Target audience: non-technical business owners. ' . 
          'Tone: informative and optimistic. ' . 
          'Include a meta description, SEO keywords, and three real-world examples of AI improving online sales.';

$task = ManusAI::createTask($prompt, [
    'agentProfile' => 'manus-1.6', // Use a powerful model for a complex task
]);

// You can now store $task['task_id'] and use a webhook or polling to retrieve the completed article.

2. Document Analysis and Summarization

One of Manus AI's most powerful features is its ability to process and analyze files. The SDK simplifies the two-step file upload process (create a file record, then upload content to a presigned URL) and makes it easy to attach files to tasks.

This opens up a huge range of possibilities, from summarizing legal contracts to analyzing financial reports.

use Tigusigalpa\ManusAI\Laravel\ManusAI;
use Tigusigalpa\ManusAI\Helpers\TaskAttachment;

// 1. Create the file record on Manus AI
$fileResult = ManusAI::createFile('quarterly-sales-report.pdf');

// 2. Upload the local file content to the provided presigned URL
ManusAI::uploadFileContent(
    $fileResult['upload_url'],
    file_get_contents(storage_path('app/reports/quarterly-sales-report.pdf')),
    'application/pdf'
);

// 3. Create a task to analyze the document
$prompt = 'Analyze the attached sales report. Identify the top 3 performing products, ' . 
          'summarize sales trends for the quarter, and provide three actionable recommendations for the next quarter.';

$task = ManusAI::createTask($prompt, [
    'attachments' => [TaskAttachment::fromFileId($fileResult['id'])],
]);

3. Asynchronous Workflows with Webhooks

Complex AI tasks can take time to complete. Instead of blocking the user experience with long-running HTTP requests, the best practice is to use asynchronous workflows. The SDK provides first-class support for Manus AI webhooks.

The WebhookHandler helper class makes it trivial to parse incoming webhook payloads and react to different events, such as task_completed or task_asking_for_input.

// In your webhook controller (e.g., /api/manus-webhook)
use Illuminate\Http\Request;
use Tigusigalpa\ManusAI\Helpers\WebhookHandler;

public function handle(Request $request)
{
    $payload = WebhookHandler::parsePayload($request->getContent());

    if (WebhookHandler::isTaskCompleted($payload)) {
        $taskDetail = WebhookHandler::getTaskDetail($payload);
        $attachments = WebhookHandler::getAttachments($payload);

        // Logic to store the completed task result in your database
        // e.g., App\Models\Article::createFromManusTask($taskDetail, $attachments);
    }

    return response()->json(['status' => 'received']);
}

This robust, event-driven approach is essential for building scalable, production-ready AI applications.

Final Thoughts and Conclusion

The tigusigalpa/manus-ai-php SDK is an exemplary open-source project. It is more than just a simple API wrapper; it is a well-architected, thoroughly documented, and developer-friendly toolkit that brings the power of the Manus AI autonomous agent platform to the PHP and Laravel ecosystems.

The clear separation between the core client and the Laravel-specific integration makes it a versatile tool for any PHP developer. The thoughtful inclusion of helper classes, Artisan commands, and detailed examples demonstrates a deep commitment to creating a positive developer experience.

By providing a seamless bridge to an AI platform capable of handling complex, multi-step tasks, this SDK empowers PHP developers to move beyond simple AI text generation and start building truly intelligent, autonomous features. Whether you are looking to automate content creation, build sophisticated data analysis pipelines, or integrate AI-powered workflows into your SaaS product, manus-ai-php provides the solid foundation you need.

For any PHP or Laravel developer looking to explore the frontier of agentic AI, this SDK is an essential tool and comes highly recommended. It sets a high standard for what a community-driven API client library can and should be.

References

[1] Sazonov, I. (2026). tigusigalpa/manus-ai-php. GitHub. https://github.com/tigusigalpa/manus-ai-php

[2] Manus. (2026). Manus: Hands On AI. https://manus.im/

[3] Manus. (2026). Manus API - Manus Documentation. https://manus.im/docs/integrations/manus-api

[4] PHP-FIG. (2026). PSR-12: Extended Coding Style. https://www.php-fig.org/psr/psr-12/

[5] Guzzle. (2026). Guzzle, PHP HTTP client. https://docs.guzzlephp.org/en/stable/

[6] Sazonov, I. (2026). tigusigalpa (Igor Sazonov). GitHub. https://github.com/tigusigalpa

bcs-trade-go: Удобный клиент для алготрейдинга на Московской бирже через БКС

Igor — Fri, 06 Mar 2026 13:33:42 +0000

Для разработчиков на Go, интересующихся алгоритмической торговлей на Московской бирже, появление качественных и удобных инструментов для взаимодействия с брокерскими API — всегда важное событие. Сегодня мы рассмотрим именно такой инструмент — библиотеку bcs-trade-go, которая представляет собой готовый клиент для нового торгового API от БКС Брокера.

Эта статья будет полезна Go-разработчикам, которые хотят автоматизировать свои торговые стратегии, создавать торговых ботов, анализировать рыночные данные или просто интегрировать свой портфель в БКС с собственными приложениями.

Что такое BCS Trade API?

BCS Trade API — это современный программный интерфейс от БКС Брокера, построенный на основе REST и WebSocket. Он предоставляет полный спектр возможностей для работы на бирже:

Получение рыночных данных: котировки, исторические свечи (OHLCV), биржевой стакан (Level 2).
Управление портфелем: получение информации об активах, балансе, лимитах и маржинальных показателях.
Торговые операции: выставление, изменение и отмена лимитных и рыночных заявок.
Справочная информация: данные об инструментах, расписании торгов и т.д.

Авторизация в API происходит по стандарту OAuth 2.0, с использованием пары refresh и access токенов, что обеспечивает безопасность, но добавляет дополнительный слой логики, который нужно реализовывать разработчику.

Зачем нужен `bcs-trade-go`? Проблема и решение

Хотя наличие документированного API — это уже большой плюс, прямая работа с ним сопряжена с рядом рутинных задач:

Управление токенами: access токен живёт всего 24 часа, и его нужно регулярно обновлять с помощью refresh токена. Этот процесс требует написания дополнительного кода для отслеживания срока жизни токена и его своевременного обновления.
Пагинация: При запросе исторических данных, например, свечей, API возвращает не более 1000 элементов за раз. Для получения больших объемов данных нужно делать несколько последовательных запросов, корректно сдвигая временные окна.
Работа с WebSocket: WebSocket — мощный инструмент для получения данных в реальном времени, но он требует обработки переподключений при обрывах связи, а также корректного управления подписками.
Обработка ошибок и повторные запросы: Сетевые взаимодействия не всегда стабильны. Нужно обрабатывать ошибки, связанные с превышением лимитов запросов (rate limits), и реализовывать логику повторных попыток (retry).

Библиотека bcs-trade-go элегантно решает все эти проблемы, предоставляя высокоуровневый, готовый к использованию клиент. Она абстрагирует всю сложность взаимодействия с API, позволяя разработчику сосредоточиться на бизнес-логике своего приложения.

Ключевые возможности `bcs-trade-go`

Рассмотрим основные преимущества и функции, которые делают эту библиотеку отличным выбором.

Функция	Описание
Полное покрытие API	Реализованы все HTTP-эндпоинты и WebSocket-каналы, описанные в официальной документации БКС.
Автоматическое управление OAuth2	Клиент самостоятельно получает и обновляет `access` токен. При получении ошибки 401 (Unauthorized) он автоматически пытается обновить токен и повторить запрос.
Умная пагинация свечей	Метод `GetCandlesPaginated` позволяет запросить исторические свечи за любой период, а библиотека сама разобьет запрос на части нужного размера и склеит результат.
Надежные WebSocket-соединения	При обрыве WebSocket-соединения клиент автоматически пытается восстановить его с экспоненциальной задержкой, что обеспечивает стабильность получения потоковых данных.
Типобезопасность	Все запросы и ответы API представлены в виде строго типизированных Go-структур, что исключает ошибки и делает работу с данными удобной.
Контекстно-ориентированный дизайн	Все методы клиента принимают `context.Context`, что позволяет легко управлять таймаутами, отменой запросов и интегрировать библиотеку в современные Go-приложения.
Продуманная обработка ошибок	Библиотека определяет кастомные типы ошибок (например, `AuthError`, `RateLimitError`, `ValidationError`), что позволяет гибко реагировать на различные сбои.
Потокобезопасность	Клиент спроектирован для безопасной работы из нескольких горутин одновременно.

Начало работы

Начать использовать библиотеку очень просто.

Установка

go get github.com/tigusigalpa/bcs-trade-go

Настройка

Для работы с API вам понадобится refresh токен. Его можно получить в личном кабинете БКС Мир Инвестиций в разделе настроек API. Токен можно выпустить с правами "только для чтения" (trade-api-read) или с полными правами для торговли (trade-api-write).

Самый простой способ передать токен в приложение — через переменные окружения:

export BCS_TRADE_REFRESH_TOKEN="ваш-refresh-token"
export BCS_TRADE_CLIENT_ID="trade-api-read" # или trade-api-write

После этого можно инициализировать клиент.

Примеры использования

Инициализация клиента и получение портфеля

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/tigusigalpa/bcs-trade-go"
)

func main() {
    ctx := context.Background()

    // Инициализация клиента из переменных окружения
    client, err := bcstrade.NewFromEnv(ctx)
    if err != nil {
        log.Fatalf("Ошибка создания клиента: %v", err)
    }

    // Получение данных портфеля
    portfolio, err := client.Portfolio.Get(ctx)
    if err != nil {
        log.Fatalf("Ошибка получения портфеля: %v", err)
    }

    fmt.Printf("Стоимость портфеля: %.2f %s\n",
        portfolio.Summary.TotalValue,
        portfolio.Summary.Currency)
}

Получение исторических свечей

Используем GetCandlesPaginated для загрузки данных за неделю.

params := models.GetCandlesParams{
    ClassCode: "TQBR", // Акции и паи
    Ticker:    "SBER",
    StartDate: time.Now().AddDate(0, 0, -7),
    EndDate:   time.Now(),
    TimeFrame: models.TimeFrameH1, // Часовые свечи
}

candles, err := client.MarketData.GetCandlesPaginated(ctx, params)
if err != nil {
    log.Fatalf("Ошибка получения свечей: %v", err)
}

fmt.Printf("Загружено %d свечей для SBER\n", len(candles.Bars))
for _, bar := range candles.Bars {
    fmt.Printf("[%s] O:%.2f H:%.2f L:%.2f C:%.2f V:%.0f\n",
        bar.Time.Format("2006-01-02 15:04"),
        bar.Open, bar.High, bar.Low, bar.Close, bar.Volume)
}

Подписка на котировки через WebSocket

Получение котировок в реальном времени — ключевая задача для торговых ботов.

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// Подписка на котировки по SBER и GAZP
quoteCh, errCh, err := client.WebSocket.Quotes(ctx, []string{"TQBR:SBER", "TQBR:GAZP"})
if err != nil {
    log.Fatalf("Ошибка подписки на котировки: %v", err)
}

fmt.Println("Ожидание котировок...")

for {
    select {
    case q := <-quoteCh:
        fmt.Printf("Тикер: %s, Bid: %.2f, Ask: %.2f, Last: %.2f\n", q.Ticker, q.Bid, q.Ask, q.Last)
    case err := <-errCh:
        // Логируем ошибку, но не выходим, т.к. клиент попытается переподключиться
        log.Printf("Ошибка WebSocket: %v", err)
    case <-ctx.Done():
        fmt.Println("Контекст отменен, завершение работы.")
        return
    }
}

Архитектура библиотеки

Код bcs-trade-go хорошо структурирован и легко читается. Основные компоненты:

client.go: Содержит главную структуру Client, которая является точкой входа и агрегирует все сервисы.
bcs.go: Определяет константы и основные типы, такие как ClientID.
config.go: Конфигурация клиента.
auth.go: Вся логика, связанная с OAuth 2.0 и управлением токенами.
transport.go: Кастомный http.RoundTripper, который "оборачивает" стандартный транспорт и добавляет в каждый запрос заголовок Authorization, а также реализует логику повторного запроса при ошибке 401.
services/: Директория, где каждый сервис (Portfolio, Orders, MarketData и т.д.) вынесен в отдельный файл, что соответствует разделению эндпоинтов в официальном API.
websocket/: Логика для работы с WebSocket, включая подписки и переподключения.

Такая архитектура делает библиотеку расширяемой и простой в поддержке.

Заключение

bcs-trade-go — это зрелый и качественный инструмент, который значительно упрощает разработку торговых приложений на Go для клиентов БКС. Автор проделал большую работу, скрыв под капотом всю сложность сетевого взаимодействия и авторизации, и предоставил разработчикам чистый и идиоматичный интерфейс.

Если вы ищете надежное решение для алготрейдинга на Московской бирже с использованием Go, bcs-trade-go определенно заслуживает вашего внимания.

Полезные ссылки:

Yandex Search API на стероидах: обзор PHP-библиотеки yandex-search-php

Igor — Fri, 06 Mar 2026 11:07:08 +0000

Привет, dev.to! Сегодня мы погрузимся в мир программного доступа к поисковым технологиям Яндекса. Если вы когда-либо хотели интегрировать поиск Яндекса в свое PHP-приложение, создать кастомную поисковую выдачу, анализировать тренды с помощью Wordstat или даже использовать генеративные возможности YandexGPT, то эта статья для вас.

Речь пойдет о библиотеке yandex-search-php, которая представляет собой мощный и удобный SDK для работы с Yandex Search API. Мы разберем, почему стоит использовать именно эту библиотеку, как ее установить и какие возможности она открывает.

Зачем нужен SDK, если есть API?

Yandex Search API — это мощный инструмент, но работа с ним напрямую через HTTP-запросы может быть сопряжена с рядом рутинных задач:

Аутентификация: API требует использования IAM-токенов, которые нужно получать, используя OAuth-токен, и своевременно обновлять. Это лишний слой логики, который приходится реализовывать и поддерживать.
Обработка ответов: API возвращает данные в формате JSON. Для удобной и безопасной работы в коде эти данные нужно преобразовывать в объекты (DTO), что требует написания дополнительного кода.
Интеграция с фреймворками: При использовании фреймворков, таких как Laravel, хочется иметь готовую интеграцию: сервис-провайдеры, фасады, автоматическое внедрение зависимостей.

Библиотека yandex-search-php элегантно решает все эти проблемы, предоставляя разработчику чистый и интуитивно понятный интерфейс для взаимодействия с API.

Ключевые возможности `yandex-search-php`

Пакет предоставляет доступ ко всем основным функциям Yandex Search API:

Классический веб-поиск: Полнотекстовый поиск по интернету с возможностью тонкой настройки (сортировка, группировка, фильтрация, регион).
Генеративный поиск (YandexGPT): Возможность задавать вопросы и получать осмысленные ответы, сгенерированные нейросетью на основе реальных данных из поисковой выдачи.
Поиск изображений: Поиск картинок по текстовому описанию и обратный поиск по изображению (по URL или загруженному файлу).
Аналитика Wordstat: Программный доступ к данным Яндекс.Вордстат для анализа популярности ключевых слов, их динамики и распределения по регионам.
Асинхронные операции: Возможность запускать долгие поисковые запросы и получать результат позже, не блокируя основной процесс.
Типобезопасные DTO: Все ответы API типизированы и представлены в виде удобных объектов, что исключает ошибки при работе с данными.
Готовая интеграция с Laravel: Пакет "из коробки" поддерживает Laravel 8-12, предоставляя фасад, сервис-провайдер и возможность внедрения зависимостей.

Начало работы

Требования

PHP 8.0+
Аккаунт в Yandex Cloud с подключенным Search API.
OAuth-токен, который можно получить на oauth.yandex.ru.

Установка

Установка производится стандартно через Composer:

composer require tigusigalpa/yandex-search-php

Быстрый старт (Plain PHP)

Для использования в обычном PHP-проекте достаточно всего нескольких строк кода:

<?php

require_once 'vendor/autoload.php';

use Tigusigalpa\YandexCloudClient\YandexCloudClient;
use Tigusigalpa\YandexSearch\YandexSearchClient;

// 1. Создаем клиент Yandex Cloud с вашим OAuth-токеном
$cloudClient = new YandexCloudClient('ВАШ_OAUTH_ТОКЕН');

// 2. Создаем клиент Yandex Search, передавая клиент облака и ID вашего каталога
$searchClient = new YandexSearchClient($cloudClient, 'ВАШ_FOLDER_ID');

// 3. Выполняем поисковый запрос
$results = $searchClient->web()->search('Статья о PHP на dev.to');

echo "Найдено: {$results->found} результатов\n";
foreach ($results->documents as $doc) {
    echo "- {$doc->title} ({$doc->url})\n";
}

Как видите, никакой магии с IAM-токенами. Библиотека берет всю работу по аутентификации на себя.

Быстрый старт (Laravel)

В Laravel все еще проще.

Публикуем конфигурационный файл:
```
php artisan vendor:publish --tag=yandex-search-config
```

Добавляем учетные данные в .env:

YANDEX_OAUTH_TOKEN=ваш_oauth_токен
YANDEX_FOLDER_ID=ваш_folder_id

Используем фасад или внедрение зависимостей:

use Tigusigalpa\YandexSearch\Laravel\Facades\YandexSearch;

// Через фасад
$results = YandexSearch::web()->search('Лучшие практики Laravel');

// Или через внедрение зависимости в контроллере
public function __construct(private \Tigusigalpa\YandexSearch\YandexSearchClient $searchClient)
{
    // ...
}

public function search(string $query)
{
    $results = $this->searchClient->web()->search($query);
    return view('search_results', compact('results'));
}

Углубляемся в возможности

Рассмотрим подробнее, как работать с основными модулями библиотеки.

Веб-поиск (`web()`)

Это основной модуль для текстового поиска. Метод search() принимает поисковый запрос и опциональный массив параметров для тонкой настройки.

$results = $searchClient->web()->search('Новости PHP 8.3', [
    'sortSpec' => [
        'sortMode' => 'SORT_MODE_BY_TIME',      // Сортировка по времени
        'sortOrder' => 'SORT_ORDER_DESC'     // От новых к старым
    ],
    'region' => 225, // Россия
    'page' => 0,     // Первая страница результатов
]);

// Результат - это объект SearchResultDTO
echo "Найдено (в числовом формате): {$results->found}\n";
echo "Найдено (в читаемом формате): {$results->foundHuman}\n";

// $results->documents - это коллекция объектов SearchDocumentDTO
foreach ($results->documents as $doc) {
    echo "\nЗаголовок: {$doc->title}\n";
    echo "URL: {$doc->url}\n";
    echo "Домен: {$doc->domain}\n";
    echo "Отрывок: {$doc->passage}\n";
}

Генеративный поиск (`gen()`)

Самая интересная часть — интеграция с YandexGPT. Вы можете задать вопрос и получить связный текстовый ответ, основанный на результатах поиска. Это открывает огромные возможности для создания чат-ботов, ассистентов и систем Q&A.

$response = $searchClient->gen()->search([
    ['role' => 'ROLE_USER', 'content' => 'В чем ключевые отличия PHP 8.2 от 8.3?']
]);

// Ответ - это объект GenerativeSearchResponseDTO
echo "Ответ ИИ:\n{$response->answer}\n";

echo "\nИсточники, использованные для ответа:\n";
foreach ($response->sources as $source) {
    if ($source->used) {
        echo "- {$source->title} ({$source->url})\n";
    }
}

Библиотека также поддерживает многоходовые диалоги, позволяя создавать более сложные сценарии взаимодействия с ИИ.

Поиск изображений (`images()`)

Модуль позволяет искать картинки по текстовому запросу или выполнять обратный поиск.

Поиск по тексту с фильтрами:

$results = $searchClient->images()->search('закат в горах', [
    'imageSpec' => [
        'size' => 'IMAGE_SIZE_LARGE',             // Только большие изображения
        'orientation' => 'IMAGE_ORIENTATION_HORIZONTAL', // Горизонтальные
        'color' => 'IMAGE_COLOR_ORANGE'          // С преобладанием оранжевого цвета
    ]
]);

// Результат - объект ImageSearchResultDTO
foreach ($results->images as $image) {
    echo "- {$image->url} ({$image->width}x{$image->height})\n";
}

Обратный поиск по URL:

$results = $searchClient->images()->searchByImage([
    'url' => 'https://example.com/my-cat.jpg'
]);

Аналитика Wordstat (`wordstat()`)

Программный доступ к Яндекс.Вордстат — мечта любого SEO-специалиста или маркетолога. Библиотека делает эту мечту реальностью.

Получение топа связанных фраз:

$top = $searchClient->wordstat()->getTop('купить слона', [
    'regions' => [213] // Москва
]);

foreach ($top->topPhrases as $phrase) {
    echo "- {$phrase['phrase']}: {$phrase['count']} запросов\n";
}

Получение динамики популярности запроса:

$dynamics = $searchClient->wordstat()->getDynamics('Laravel');

foreach ($dynamics->dynamics as $period) {
    echo "{$period['date']}: {$period['count']} запросов\n";
}

Заключение

Библиотека yandex-search-php — это высококачественный, хорошо документированный и удобный инструмент для любого PHP-разработчика, желающего работать с поисковыми технологиями Яндекса. Она абстрагирует от сложностей аутентификации, предоставляет удобные DTO для работы с результатами и отлично интегрируется с современными фреймворками, такими как Laravel.

Будь то добавление поиска по сайту, создание умного ассистента на базе YandexGPT или автоматизация сбора SEO-метрик, этот SDK станет вашим надежным помощником.

Полезные ссылки

Introducing zoomex-go: A Golang Client for the Zoomex Crypto Exchange API

Igor — Fri, 27 Feb 2026 12:24:50 +0000

If you're a Go developer building tools for the cryptocurrency derivatives market, you know how much time gets lost dealing with raw HTTP plumbing, HMAC signature generation, and WebSocket connection management before you can even write a single line of business logic. zoomex-go is an open-source library by Igor Sazonov that solves exactly this problem for the Zoomex exchange — providing a clean, idiomatic Go wrapper around the full Zoomex v3 API.

What is Zoomex?

Zoomex is a cryptocurrency derivatives exchange established in 2021, offering over 500 perpetual contracts across both USDT-margined (linear) and coin-margined (inverse) instruments, with leverage up to 150x. It has gained traction among derivatives traders for its broad asset coverage, deep liquidity, and low-friction onboarding. The exchange exposes a well-documented REST and WebSocket API (v3) that allows developers to build trading bots, market data collectors, risk management tools, and portfolio trackers programmatically.

Why a Dedicated Go Client?

Go is a natural fit for high-performance trading infrastructure. Its goroutine-based concurrency model, low latency, and strong standard library make it a popular choice for building exchange connectors, order management systems, and data pipelines. However, writing a robust API client from scratch means dealing with:

HMAC-SHA256 request signing with timestamps and receive windows
Correct construction of X-BAPI-* authentication headers
Parsing and mapping API responses to typed Go structs
Managing WebSocket connections, heartbeats, and reconnection logic

zoomex-go handles all of this transparently, so you can start interacting with the exchange in minutes rather than hours.

Installation

The library requires Go 1.21 or later and can be installed with a single command:

go get github.com/tigusigalpa/zoomex-go

Client Configuration

The client is configured using a functional options pattern, which is idiomatic Go and keeps the API clean and extensible:

client := zoomex.NewClient(
    zoomex.WithTestnet(true),             // use testnet (default: mainnet)
    zoomex.WithAPIKey("your-api-key"),    // API key for private endpoints
    zoomex.WithSecretKey("your-secret"), // secret for HMAC signing
    zoomex.WithRecvWindow(10000),         // request validity window in ms
    zoomex.WithHTTPClient(customClient), // bring your own http.Client
)

The same options apply to the WebSocket client. Switching between testnet and mainnet is a single boolean flag — no URL juggling required. The library resolves the correct base URLs automatically:

Environment	REST Endpoint	WebSocket Endpoint
Mainnet	`https://openapi.zoomex.com`	`wss://stream.zoomex.com/v3/private`
Testnet	`https://openapi-testnet.zoomex.com`	`wss://stream-testnet.zoomex.com/v3/private`

REST API Usage

All REST methods accept a context.Context as their first argument, enabling proper timeout and cancellation handling — a must-have for production trading systems.

Fetching Market Data

tickers, err := client.Market.GetTickers(context.Background(), &zoomex.GetTickersRequest{
    Category: zoomex.CategoryLinear,
    Symbol:   "BTCUSDT",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Last price: %s\n", tickers.List[0].LastPrice)

Placing an Order

Private endpoints are authenticated automatically. There is no need to calculate timestamps or build signature strings manually:

order, err := client.Trade.PlaceOrder(ctx, &zoomex.PlaceOrderRequest{
    Category:    zoomex.CategoryLinear,
    Symbol:      "BTCUSDT",
    Side:        zoomex.OrderSideBuy,
    OrderType:   zoomex.OrderTypeLimit,
    Qty:         "0.001",
    Price:       "30000",
    TimeInForce: zoomex.TimeInForceGTC,
    TakeProfit:  "35000",
    StopLoss:    "28000",
})

Managing Positions

// Set leverage
client.Position.SetLeverage(ctx, &zoomex.SetLeverageRequest{
    Category:     zoomex.CategoryLinear,
    Symbol:       "BTCUSDT",
    BuyLeverage:  "10",
    SellLeverage: "10",
})

// Switch to isolated margin
client.Position.SwitchIsolated(ctx, &zoomex.SwitchIsolatedRequest{
    Category:     zoomex.CategoryLinear,
    Symbol:       "BTCUSDT",
    TradeMode:    zoomex.MarginModeIsolated,
    BuyLeverage:  "10",
    SellLeverage: "10",
})

WebSocket API Usage

The WebSocket client uses a callback-based API. Subscriptions are non-blocking — you pass a handler function and the library invokes it on each incoming message:

ws := zoomex.NewWebSocket(
    zoomex.WithAPIKey("your-api-key"),
    zoomex.WithSecretKey("your-secret"),
)
defer ws.Close()

// Public: real-time order book
ws.SubscribeOrderbook("BTCUSDT", func(data *zoomex.OrderbookData) {
    log.Printf("Orderbook: %+v\n", data)
})

// Private: order status updates
ws.SubscribeOrder(func(data *zoomex.OrderUpdateData) {
    log.Printf("Order update: %+v\n", data)
})

// Private: wallet balance changes
ws.SubscribeWallet(func(data *zoomex.WalletUpdateData) {
    log.Printf("Wallet: %+v\n", data)
})

select {} // keep alive

Full API Coverage

The library covers all major service areas of the Zoomex v3 API:

Service	Endpoints
Market	Server Time, Kline (and Mark/Index/Premium variants), Tickers, Orderbook, Instruments Info, Funding Rate History, Public Trade History, Risk Limit
Trade	Place / Amend / Cancel Order, Cancel All Orders, Open Orders, Order History, Trade History
Position	Position Info, Set Leverage, Switch Isolated/Cross Margin, Set Trading Stop, Set Risk Limit
Account	Wallet Balance, Upgrade Status
Asset	Coin Info, All Coins Balance, Single Coin Balance, Internal Transfers, Subaccount Transfers, Deposit Records, Withdrawal Records, Withdraw, Cancel Withdrawal, Coin Exchange History, Delivery/Settlement Records
WebSocket (Public)	Orderbook
WebSocket (Private)	Order, Position, Execution, Wallet

Error Handling and Best Practices

The library follows standard Go conventions: every method returns a typed result and an error. API-level errors from Zoomex (non-zero retCode) are surfaced as Go errors with the format "API error: code=<retCode>, msg=<retMsg>", making them easy to handle and log.

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

result, err := client.Market.GetTickers(ctx, req)
if err != nil {
    log.Printf("Error: %v", err)
    return
}

A few recommended practices when using the library in production:

Store API keys in environment variables, never in source code.
Always test new strategies on the testnet first (get testnet keys at testnet.zoomex.com).
Use context.WithTimeout to prevent hanging requests.
Always call ws.Close() (ideally via defer) to release WebSocket resources cleanly.

Getting Involved

The project is MIT-licensed and open to contributions. If you encounter a missing endpoint, a bug, or want to improve the library, pull requests are welcome on the GitHub repository. The repository also includes an examples/ directory with runnable code samples to help you get started quickly.

Links:

GitHub: https://github.com/tigusigalpa/zoomex-go
Zoomex API v3 Docs: https://zoomexglobal.github.io/docs/v3/intro
Zoomex Exchange: https://www.zoomex.com

BingX PHP SDK: The Laravel Developer's Gateway to Crypto Exchange Integration

Igor — Tue, 24 Feb 2026 02:56:24 +0000

For developers in the PHP and Laravel ecosystem, integrating with external APIs is a daily reality. When it comes to the dynamic world of cryptocurrency trading, however, the bar for a good SDK is exceptionally high. It needs to be more than just a wrapper; it must be robust, intuitive, and seamlessly fit into the frameworks we know and love.

Enter the BingX PHP SDK, a client built from the ground up with the modern PHP and Laravel developer in mind. This isn't just about making API calls; it's about providing a first-class development experience that makes building sophisticated trading applications more accessible than ever.

A Modern SDK for a Modern Ecosystem

While many API clients are simple, stateless wrappers, the BingX PHP SDK offers a deeply integrated experience. With over 220 methods and a 100% API coverage, it provides a comprehensive toolkit for interacting with the BingX exchange, covering everything from market data and spot trading to perpetual futures and advanced features like copy trading and sub-account management.

The library supports both pure PHP and offers a first-class integration for Laravel 8-12, making it a versatile choice for any project.

The Laravel-First Experience

Where this SDK truly shines for Laravel developers is its native integration. Forget manual configuration and service binding; the package is designed to feel like a natural extension of the framework.

Installation and Setup

Getting started is as simple as requiring the package via Composer:

composer require tigusigalpa/bingx-php:*

Next, publish the configuration file:

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

This creates a config/bingx.php file and allows you to manage your API credentials directly in your .env file, just like any other Laravel service:

BINGX_API_KEY=your_api_key_here
BINGX_API_SECRET=your_api_secret_here
BINGX_BASE_URI=https://open-api.bingx.com

With the Bingx facade, you can now access all the SDK's services directly and elegantly within your application:

use Tigusigalpa\BingX\Facades\Bingx;

// Get the latest BTC price
$price = Bingx::market()->getLatestPrice("BTC-USDT");

// Get your account balance
$balance = Bingx::account()->getBalance();

The Fluent OrderBuilder: Expressive Trading Logic

One of the standout features is the OrderBuilder, a fluent interface that makes creating complex orders incredibly intuitive and readable. This PHP-native approach, with its chainable methods, is a significant step up from building raw request arrays.

Here’s how you can construct a leveraged futures order with a stop-loss and take-profit:

$order = Bingx::trade()->order()
    ->futures()
    ->symbol("BTC-USDT")
    ->buy()
    ->long()
    ->type("LIMIT")
    ->margin(100) // 100 USDT margin
    ->price(50000)
    ->leverage(10)
    ->stopLossPercent(5)      // 5% stop-loss
    ->takeProfitPercent(15)   // 15% take-profit
    ->execute();

This clean, expressive syntax not only reduces the chance of errors but also makes your trading logic self-documenting.

Real-Time Data with WebSocket Streaming

For any serious trading application, real-time data is non-negotiable. The SDK includes a straightforward WebSocket client to stream market data directly into your Laravel application. You can subscribe to trades, k-lines, order book depth, and more.

use Tigusigalpa\BingX\WebSocket\MarketDataStream;

$stream = new MarketDataStream();
$stream->connect();

$stream->subscribeTrade("BTC-USDT");
$stream->subscribeKline("BTC-USDT", "1m");

$stream->onMessage(function ($data) {
    // Process real-time data for a live dashboard or bot
    if (isset($data["dataType"]) && $data["dataType"] === "BTC-USDT@trade") {
        echo "New trade price: {$data["data"]["p"]}";
    }
});

$stream->listen();

Advanced Trading Features

The SDK goes beyond the basics, offering powerful features for sophisticated strategies:

TWAP Orders: Execute large orders over a specified duration using Time-Weighted Average Price (TWAP) to minimize market impact.
Coin-M Perpetual Futures: Trade contracts margined and settled in cryptocurrency (like BTC or ETH) for hedging or speculation.
Copy Trading: Build services that programmatically manage copy trading operations.

Robust Error Handling

A trading bot is only as good as its ability to handle errors gracefully. The SDK provides a hierarchy of custom exceptions, allowing you to catch specific issues like AuthenticationException, RateLimitException, or InsufficientBalanceException.

try {
    $balance = Bingx::account()->getBalance();
} catch (RateLimitException $e) {
    // Handle rate limiting, maybe queue the job for later
    Log::warning("Rate limit exceeded. Retrying after: " . $e->getRetryAfter());
} catch (ApiException $e) {
    // Handle API-specific errors
    Log::error("API Error: " . $e->getErrorCode() . " - " . $e->getMessage());
}

Conclusion

The BingX PHP SDK is a powerful, well-designed tool that bridges the gap between the PHP/Laravel ecosystem and the world of professional cryptocurrency trading. Its focus on developer experience, seamless Laravel integration, and comprehensive feature set make it an excellent choice for anyone looking to build reliable and sophisticated trading applications.

To get started, check out the official resources:

GitHub Repository
BingX API Documentation

Happy coding!

Supercharge Your PHP Shipping Integrations with the New ShipTime API Client

Igor — Tue, 17 Feb 2026 02:40:23 +0000

Shipping can be a major headache for developers building e-commerce sites and business applications. Juggling multiple carrier APIs, calculating rates, printing labels, and tracking shipments often leads to complex and brittle integrations. But what if you could manage it all through a single, streamlined platform?

Enter ShipTime, an all-in-one shipping service designed to simplify logistics for businesses. ShipTime provides a unified platform to compare rates from major carriers, print labels, and manage all your shipments in one place, often at discounted prices [1].

To make integration even easier for PHP developers, I'm excited to introduce a new, modern PHP client library for the ShipTime REST API: tigusigalpa/shiptime-php [2].

This library is built from the ground up for PHP 8.1+ and offers seamless integration with Laravel, empowering you to add robust shipping capabilities to your applications with minimal effort.

Why a New Client Library?

While ShipTime offers a powerful REST API [3], integrating it directly can still involve a lot of boilerplate code for handling HTTP requests, authentication, and data mapping. This library abstracts away that complexity, providing a clean, object-oriented interface that feels right at home in any modern PHP project.

Key Features

🚀 Modern PHP 8.1+: Leverages the latest language features like enums, readonly properties, and strict typing for more reliable and maintainable code.
🔧 Full Laravel Integration: Includes a service provider and facade for effortless integration into your Laravel applications. Configuration is a breeze—just add your API keys to your .env file.
📦 Complete API Coverage: Provides access to all major ShipTime API features, including Rates, Shipments, Tracking, Orders, and Pickups.
🎨 Clean Architecture: Designed with a service-oriented architecture and comprehensive Data Transfer Objects (DTOs) for a clean, type-safe, and intuitive developer experience.
🛡️ Robust Error Handling: Comes with specific exception types for different API errors, making debugging and error handling straightforward.

Getting Started

Integrating the library into your project is simple. First, install it via Composer:

composer require tigusigalpa/shiptime-php

For Laravel Users

If you're using Laravel, the service provider will be automatically registered. All you need to do is publish the configuration file and add your credentials:

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

Then, add your ShipTime API key and secret to your .env file:

SHIPTIME_API_KEY=your_api_key
SHIPTIME_API_SECRET=your_api_secret

You can now inject the ShipTime client directly into your controllers or use the ShipTime facade:

use Tigusigalpa\ShipTime\Facades\ShipTime;

// Get shipping rates for a package
$rates = ShipTime::rates()->getRates($rateRequest);

Standalone PHP

Not using Laravel? No problem. You can use the client in any PHP project by instantiating it directly:

use Tigusigalpa\ShipTime\ShipTime;

$shiptime = new ShipTime(
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret'
);

// Create a shipment
$shipment = $shiptime->shipments()->createShipment($shipRequest);

Example: Fetching Shipping Rates

Let's see how easy it is to get shipping rates. The library uses DTOs to ensure all data sent to the API is correctly structured and validated.

use Tigusigalpa\ShipTime\DTOs\RateRequest;
use Tigusigalpa\ShipTime\DTOs\Address;
use Tigusigalpa\ShipTime\DTOs\LineItem;
use Tigusigalpa\ShipTime\Enums\PackageType;
use Tigusigalpa\ShipTime\Enums\UnitOfMeasurement;

$from = new Address(/* ... */);
$to = new Address(/* ... */);
$lineItem = new LineItem(length: 12.0, width: 8.0, height: 6.0, weight: 5.5);

$rateRequest = new RateRequest(
    from: $from,
    to: $to,
    packageType: PackageType::PACKAGE,
    lineItems: [$lineItem],
    unitOfMeasurement: UnitOfMeasurement::IMPERIAL,
    shipDate: '2024-02-20'
);

$rateResponse = ShipTime::rates()->getRates($rateRequest);

foreach ($rateResponse->availableRates as $quote) {
    echo "Carrier: {$quote->carrierName} - {$quote->totalCharge->amount} {$quote->totalCharge->currency->value}\n";
}

In just a few lines of code, you can retrieve a list of available shipping options and their costs, ready to be displayed to your users.

Final Thoughts

The shiptime-php library is designed to make integrating with ShipTime a fast and enjoyable experience for PHP developers. By providing a modern, type-safe, and well-structured client, it allows you to focus on building great features for your users instead of wrestling with API integration details.

Give it a try in your next project! The library is open-source and available on GitHub. Contributions, feedback, and feature requests are always welcome.

Happy shipping!

References

[1] ShipTime | Find the Cheapest Shipping Rates
[2] GitHub - tigusigalpa/shiptime-php
[3] ShipTime API Documentation

Simplify International Shipping in PHP/Laravel with the EasyShip API

Igor — Mon, 16 Feb 2026 16:22:34 +0000

In modern eCommerce, fast and reliable shipping isn't just a nice-to-have; it's a critical factor for success. Customers expect transparency, speed, and fair prices, especially for international orders. For developers, integrating with multiple shipping carriers, calculating rates, tracking shipments, and handling customs documentation can be a major headache. Fortunately, platforms exist to handle the complexities of logistics, and one such platform is EasyShip.

What is EasyShip?

EasyShip is an all-in-one shipping platform that connects to over 550 courier services worldwide. It provides a unified API to access a wide range of logistics services, allowing online stores, marketplaces, and enterprise clients to automate and optimize their shipping processes. The platform offers discounted rates of up to 91%, automatic tax and duty calculations, and tools for tracking and returns. Giants like eBay and Shopify already use EasyShip to expand their global operations.

Key features of the EasyShip API include:

Rate Comparison: Get real-time shipping quotes from hundreds of carriers.
Label Generation: Create and print shipping labels in bulk.
Tracking: Monitor shipment status with webhook notifications.
Customs Clearance: Automatically calculate duties and taxes (DDP or DDU).
Returns Management: Generate pre-paid return labels.

Introducing `easyship-php`: A PHP/Laravel Client for the EasyShip API

For developers working with PHP and Laravel, a new convenient tool for integrating with EasyShip has emerged: the tigusigalpa/easyship-php library. This SDK provides full support for all 348+ EasyShip API endpoints and significantly simplifies the integration process.

The library is built with modern PHP standards (PSR-4/PSR-12) and supports PHP 8.1+ and Laravel 9-12. It includes essential features such as:

Complete API Coverage: All available EasyShip API methods are implemented.
Laravel Integration: Includes a service provider, facade, and configuration file.
OAuth 2.0 Support: Simplifies the creation of partner integrations.
Webhook Handling: Built-in signature verification for secure notification processing.
Typed Exceptions: Convenient API error handling.
Automatic Retries: Increases reliability during temporary network failures.
Sandbox and Production Support: Easy switching between environments.

Quick Start

Getting started with the library is very simple. First, install it via Composer:

composer require tigusigalpa/easyship-php

For a standalone PHP project:

use Tigusigalpa\EasyShip\EasyShipClient;

$client = new EasyShipClient([
    'api_token' => 'sand_xxxxxxxxxxxxxxxx', // or prod_xxxxxxxxxxxxxxxx
    'timeout' => 30,
    'retry' => 3,
]);

$shipments = $client->shipments()->list();

For a Laravel project:

Publish the configuration file:

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

Add your API key to your .env file:

EASYSHIP_API_TOKEN=sand_xxxxxxxxxxxxxxxx

Use the facade or dependency injection:

use Tigusigalpa\EasyShip\Laravel\Facades\EasyShip;

// Via facade
$shipments = EasyShip::shipments()->list();

// Via Dependency Injection
use Tigusigalpa\EasyShip\EasyShipClient;

class ShippingController extends Controller
{
    public function __construct(private EasyShipClient $easyship) {}

    public function index()
    {
        $shipments = $this->easyship->shipments()->list();
    }
}

Conclusion

EasyShip provides a powerful solution for automating international shipping, and the easyship-php library makes its integration into PHP and Laravel projects incredibly simple and fast. With its complete API coverage, modern architecture, and convenient framework integration, this SDK will become an indispensable tool for developers looking to take their e-commerce business to a global level.

If you are looking for a reliable and functional solution for working with the EasyShip API, be sure to check out this library.

Taming the Shipping Beast: A Modern PHP/Laravel SDK for the Shippo API

Igor — Mon, 16 Feb 2026 14:24:51 +0000

Shipping can be a major headache for any e-commerce business. From comparing carrier rates to printing labels and tracking packages, the logistics can quickly become overwhelming. This is where services like Shippo come in, offering a unified platform to streamline the entire shipping process. But to truly unlock the power of Shippo, you need a way to integrate it into your applications.

Today, we're going to explore a brand new, modern PHP/Laravel client for the Shippo API that makes this integration a breeze: tigusigalpa/shippo-php.

What is Shippo and Why Should You Care?

For those unfamiliar, Shippo is a multi-carrier shipping API and platform that acts as a bridge between your business and a global network of shipping carriers like USPS, FedEx, UPS, and DHL. Instead of building and maintaining separate integrations for each carrier, Shippo provides a single, unified API to:

Shippo provides a single, unified API to compare shipping rates, purchase labels, validate addresses, track packages, and handle international customs.

By using Shippo, developers can save countless hours of development time and businesses can save significant money on shipping costs, with discounts of up to 90% on some carriers. It’s a powerful tool for any application that deals with physical goods.

Introducing `shippo-php`: A Modern PHP SDK for Shippo

While Shippo has an official client, tigusigalpa/shippo-php by Igor Sazonov provides a more modern and robust experience, especially for Laravel developers. It's built with PHP 8.1+ and adheres to the latest PSR standards.

Here are some of the standout features:

Key features include modern PHP 8.1+ support, PSR compliance, type-safe DTOs for all API responses, automatic retry logic for rate limits, seamless Laravel integration with a dedicated Facade, and comprehensive exception handling.

Getting Started

Installation is straightforward with Composer:

composer require tigusigalpa/shippo-php

For Laravel Users

The package auto-registers its service provider. All you need to do is publish the config file and add your API token to your .env file.

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

SHIPPO_API_TOKEN=your_shippo_api_token_here
SHIPPO_IS_TEST=true

Now you can use the Shippo facade anywhere in your Laravel application.

Standalone PHP

You can also use the library in any PHP project. Just instantiate the Shippo class with a PSR-18 HTTP client and a configuration object.

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Tigusigalpa\Shippo\Shippo;
use Tigusigalpa\Shippo\Config;

$httpFactory = new HttpFactory();
$config = Config::make('your_api_token');

$shippo = new Shippo(
    httpClient: new GuzzleClient(),
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
    config: $config
);

A Quick Example: Creating a Shipping Label

Creating a shipping label is simple. It involves creating a shipment with address and parcel details, selecting a rate, and purchasing the label.

use Tigusigalpa\Shippo\Laravel\Facades\Shippo;

// 1. Create a shipment
$shipment = Shippo::shipments()->create([
    'address_from' => [ /* ... */ ],
    'address_to' => [ /* ... */ ],
    'parcels' => [ /* ... */ ],
]);

// 2. Select the cheapest rate
$rateId = $shipment->rates[0]['object_id'];

// 3. Purchase the label
$transaction = Shippo::transactions()->create([
    'rate' => $rateId,
    'label_file_type' => 'PDF',
]);

// 4. Get your label and tracking number!
echo "Label URL: {$transaction->labelUrl}\n";
echo "Tracking Number: {$transaction->trackingNumber}\n";

The library supports all major Shippo API endpoints. For more examples, including address validation, tracking, and customs, check out the GitHub repository.

Conclusion

For any PHP or Laravel project integrating with Shippo, tigusigalpa/shippo-php is an excellent choice. Its modern design and robust features will help you write cleaner, more reliable shipping code. Give it a try and tame the shipping beast in your next project!