PHPackages                             wprigollopes/bcb-ptax - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. wprigollopes/bcb-ptax

ActiveLibrary[API Development](/categories/api)

wprigollopes/bcb-ptax
=====================

PHP client for Banco Central do Brasil PTAX currency exchange rates

v2.0.0(2mo ago)31MITPHPPHP >=8.1

Since Feb 7Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/wprigollopes/bcb-ptax)[ Packagist](https://packagist.org/packages/wprigollopes/bcb-ptax)[ RSS](/packages/wprigollopes-bcb-ptax/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (4)Versions (4)Used By (0)

BCB PTAX
========

[](#bcb-ptax)

A PHP library to fetch daily PTAX exchange rates from Banco Central do Brasil's public API.

Background
----------

[](#background)

This project was born out of a real operational need at a Brazilian import company. Every business day, the company needed the official PTAX closing rate to price imports, settle invoices, and comply with Brazilian customs regulations. What started as a quick utility script grew into a Composer package shared with the community.

In 2026, the library was modernized with the help of [Claude Code](https://claude.ai/claude-code) — rewritten from the ground up with PHP 8.1+ features, proper type safety, full test coverage, and i18n support while keeping the same simple API.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Composer

Installation
------------

[](#installation)

```
composer require wprigollopes/bcb-ptax
```

Usage
-----

[](#usage)

### Basic example

[](#basic-example)

```
use BcbPtax\PTAX;
use BcbPtax\Currency;

$ptax = new PTAX();
$result = $ptax->get(Currency::USD, new \DateTime('2024-01-15'));

echo $result->buyRate;      // 4.8759 (cotacaoCompra)
echo $result->sellRate;     // 4.8765 (cotacaoVenda)
echo $result->bulletinType; // "Fechamento PTAX"
echo $result->date->format('Y-m-d'); // "2024-01-15"
```

### Custom HTTP client

[](#custom-http-client)

If you need to configure timeouts, proxies, or other HTTP options, pass your own Guzzle client:

```
use BcbPtax\PTAX;
use BcbPtax\Currency;
use GuzzleHttp\Client;

$ptax = new PTAX(
    client: new Client(['timeout' => 10]),
);

$result = $ptax->get(Currency::EUR, new \DateTime('2024-06-20'));
```

### Portuguese error messages

[](#portuguese-error-messages)

Exception messages default to English (`en_US`). To get messages in Portuguese:

```
$ptax = new PTAX(locale: 'pt_BR');

// Throws: "Nenhum PTAX de fechamento encontrado para USD em 01-01-2024"
$ptax->get(Currency::USD, new \DateTime('2024-01-01')); // Holiday, no PTAX
```

### Handling errors

[](#handling-errors)

```
use BcbPtax\PTAX;
use BcbPtax\Currency;
use BcbPtax\Exception\ApiException;

$ptax = new PTAX();

try {
    $result = $ptax->get(Currency::USD, new \DateTime('2024-01-15'));
    echo "Buy rate: {$result->buyRate}";
} catch (ApiException $e) {
    // API returned an error, no data for that date, or malformed response
    echo "Error: {$e->getMessage()}";
}
```

### Working with user input

[](#working-with-user-input)

The `Currency` enum provides safe parsing from strings:

```
use BcbPtax\PTAX;
use BcbPtax\Currency;

$input = 'USD';
$currency = Currency::tryFrom($input);

if ($currency === null) {
    echo "Unsupported currency: {$input}";
    return;
}

$ptax = new PTAX();
$result = $ptax->get($currency, new \DateTime('2024-01-15'));
```

Supported Currencies
--------------------

[](#supported-currencies)

The BCB PTAX service provides daily closing rates for the following currencies against BRL:

CodeCurrencyAUDAustralian DollarCADCanadian DollarCHFSwiss FrancDKKDanish KroneEUREuroGBPBritish PoundJPYJapanese YenNOKNorwegian KroneSEKSwedish KronaUSDUS DollarSource: [BCB PTAX Moedas endpoint](https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/Moedas?$format=json)

API Reference
-------------

[](#api-reference)

### `PTAX`

[](#ptax)

```
new PTAX(
    ClientInterface $client = new Client(), // Custom Guzzle client (optional)
    string $locale = 'en_US',               // 'en_US' or 'pt_BR'
)
```

#### `get(Currency $currency, DateTimeInterface $date): PTAXResult`

[](#getcurrency-currency-datetimeinterface-date-ptaxresult)

Fetches the closing PTAX rate for the given currency and date. Throws `ApiException` if the API returns an error, the response is malformed, or no closing PTAX exists for that date (weekends, holidays).

### `PTAXResult`

[](#ptaxresult)

PropertyTypeDescription`buyRate``float`Purchase rate (cotacaoCompra)`sellRate``float`Selling rate (cotacaoVenda)`date``DateTimeImmutable`Quotation timestamp`bulletinType``string`Bulletin type (always "Fechamento PTAX")### `Currency`

[](#currency)

PHP 8.1 string-backed enum with all 10 supported currency codes. Use `Currency::tryFrom('USD')` for safe parsing from user input.

Development
-----------

[](#development)

```
# Install dependencies
composer install

# Run unit tests
vendor/bin/phpunit --exclude-group integration

# Run integration tests (calls real BCB API)
vendor/bin/phpunit --group integration

# Static analysis
vendor/bin/phpstan analyse src/ --level=max

# Code modernization checks
vendor/bin/rector --dry-run
```

License
-------

[](#license)

[MIT](LICENSE)

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance86

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

71d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ffecca0959723837eac69d42af6800a9908fbb54ed15ecb80b820324e16463d9?d=identicon)[wprigollopes](/maintainers/wprigollopes)

---

Top Contributors

[![wprigollopes](https://avatars.githubusercontent.com/u/8663950?v=4)](https://github.com/wprigollopes "wprigollopes (24 commits)")

---

Tags

apicomposer

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/wprigollopes-bcb-ptax/health.svg)

```
[![Health](https://phpackages.com/badges/wprigollopes-bcb-ptax/health.svg)](https://phpackages.com/packages/wprigollopes-bcb-ptax)
```

###  Alternatives

[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3731.2M42](/packages/tencentcloud-tencentcloud-sdk-php)[convertkit/convertkitapi

Kit PHP SDK for the Kit API

2167.1k1](/packages/convertkit-convertkitapi)[mapado/rest-client-sdk

Rest Client SDK for hydra API

1125.9k2](/packages/mapado-rest-client-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)