README

About ChangeNOW API

ChangeNOW API is a type-safe, feature-complete PHP library for the ChangeNOW cryptocurrency exchange REST API. It wraps both v1 and v2 endpoints with strictly typed DTOs, modular services, and full test coverage — no magic arrays, no guesswork.

✨ Features

• Full API Coverage: All 29 endpoints from v1 and v2 — currencies, rates, exchanges, private transfers, address validation, and more.
• Strictly Typed DTOs: Every response is a readonly value object with a static fromArray() factory and full PHPDoc generics.
• Modular Architecture: Separate service classes per API section (common(), standardFlow(), fixedRateFlow(), markets(), etc.).
• PSR-compliant HTTP: Built on GuzzleHttp\ClientInterface — inject your own client for mocking or custom middleware.
• Tested: 40+ PHPUnit tests covering every endpoint, including error responses and edge cases.
• API Key Authentication: Automatically sent via x-api-key header — no manual header management.

📦 Installation

Ensure you have ext-curl and ext-json installed.

composer require happyslucker/changenow-api

🚀 Quick Start

1. Fetch Available Currencies

Retrieve all tradable assets from the ChangeNOW platform.

use ChangeNow\ChangeNowClient;

$client = new ChangeNowClient('your-api-key');

$currencies = $client->common()->getCurrencies();

foreach ($currencies as $currency) {
    echo $currency->ticker . ' — ' . $currency->name . PHP_EOL;
}

2. Estimate & Create an Exchange

Get a rate estimate and immediately create a standard-flow transaction.

use ChangeNow\ChangeNowClient;
use ChangeNow\Model\Request\CreateExchangeRequest;

$client = new ChangeNowClient('your-api-key');

// Step 1: Estimate
$estimate = $client->standardFlow()->getEstimatedAmount('btc', 'eth', '1');
echo "You'll receive: {$estimate->estimatedAmount} ETH" . PHP_EOL;

// Step 2: Create exchange
$request = new CreateExchangeRequest(
    fromCurrency: 'btc',
    toCurrency: 'eth',
    address: '0xRecipientAddress',
    fromAmount: '1',
    refundAddress: '1MyRefundAddress',
);
$exchange = $client->standardFlow()->createExchange($request);

echo "Exchange ID: {$exchange->id}" . PHP_EOL;
echo "Send BTC to: {$exchange->payinAddress}" . PHP_EOL;

3. Fixed-Rate Exchange (Reverse)

Create a fixed-rate transaction where you specify the exact output amount.

use ChangeNow\ChangeNowClient;
use ChangeNow\Model\Request\CreateExchangeRequest;

$client = new ChangeNowClient('your-api-key');

$request = new CreateExchangeRequest(
    fromCurrency: 'btc',
    toCurrency: 'eth',
    address: '0xRecipient',
    fromAmount: '1',
    toAmount: '15.5',          // exact desired output
    flow: 'fixed-rate',
    type: 'reverse',
);

$exchange = $client->fixedRateFlow()->createExchange($request);
echo "{$exchange->id} — send {$exchange->amountExpectedFrom} BTC";

4. Validate an Address

Check if a cryptocurrency address is valid before sending funds.

$result = $client->validate()->address('btc', '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa');

echo $result->result
    ? '✓ Address is valid'
    : "✗ Invalid: {$result->message}";

🛠️ Architecture

Module Structure

The library is split into domain-aligned services, each accessible via a lazy-loaded property on the client.

Data Transfer Objects

Every API response is mapped to a readonly DTO. No associative arrays leak out of the library — you always work with typed objects.

$tx = $client->common()->getTransactionStatus('abc123');

echo $tx->status->value;           // enum-backed string
echo $tx->fromCurrency;            // string
echo $tx->amountExpectedTo;       // string (numeric, atomic precision)

Exception Handling

All API errors throw ChangeNowException with the upstream message and HTTP status code.

use ChangeNow\Exception\ChangeNowException;

try {
    $client->common()->getCurrencies();
} catch (ChangeNowException $e) {
    echo "API error [{$e->getCode()}]: {$e->getMessage()}";
}

⚙️ Requirements

• PHP: 8.4 or higher
• Extensions:
  • curl — Required by Guzzle for HTTP transport
  • json — Required for request/response serialisation
  • mbstring — Recommended for multibyte string handling

📜 License

The MIT License (MIT).

Created by HappySlucker. Happy coding! 🍻