API Reference¶

Client¶

pixbr.PixClient ¶

Client for the Brazilian Central Bank PIX Open Data API.

Parameters:

Name	Type	Description	Default
`timeout`	`float`	Request timeout in seconds (default 120). The BCB API can be slow for large queries, so a generous timeout is recommended.	`DEFAULT_TIMEOUT`
`max_retries`	`int`	Number of retry attempts on transport errors (default 3).	`3`
`verbose`	`bool`	If True (default), log progress messages at INFO level.	`True`

Examples:

>>> client = PixClient()
>>> df = client.keys(date="2025-12-01", top=100)

build_url ¶

build_url(
    endpoint: str,
    params: Optional[Mapping[str, ParamValue]] = None,
    *,
    fmt: str = "json",
    filter: Optional[str] = None,
    select: Optional[Sequence[str]] = None,
    orderby: Optional[str] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None
) -> str

Build (without sending) the URL for a request. Useful for debugging.

query ¶

query(
    endpoint: str,
    params: Optional[Mapping[str, ParamValue]] = None,
    *,
    filter: Optional[str] = None,
    select: Optional[Sequence[str]] = None,
    orderby: Optional[str] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    verbose: Optional[bool] = None
) -> pd.DataFrame

Low-level call to any PIX endpoint; returns a DataFrame.

This is the Python equivalent of pixr::pix_query.

keys ¶

keys(
    date: str,
    *,
    filter: Optional[str] = None,
    columns: Optional[Sequence[str]] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[str] = None,
    verbose: Optional[bool] = None
) -> pd.DataFrame

PIX keys stock by participant (ChavesPix endpoint).

date is required, in YYYY-MM-DD form. The API returns data for the last day of the month containing the given date.

transaction_stats ¶

transaction_stats(
    database: str,
    *,
    filter: Optional[str] = None,
    columns: Optional[Sequence[str]] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[str] = None,
    verbose: Optional[bool] = None
) -> pd.DataFrame

PIX transaction statistics (EstatisticasTransacoesPix endpoint).

database is required, in YYYYMM form.

transactions_by_municipality ¶

transactions_by_municipality(
    database: str,
    *,
    filter: Optional[str] = None,
    columns: Optional[Sequence[str]] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[str] = None,
    verbose: Optional[bool] = None
) -> pd.DataFrame

PIX transactions by municipality (TransacoesPixPorMunicipio endpoint).

database is required, in YYYYMM form. Note this endpoint uses the DataBase parameter (capital B).

fraud_stats ¶

fraud_stats(
    database: str,
    *,
    filter: Optional[str] = None,
    columns: Optional[Sequence[str]] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[str] = None,
    verbose: Optional[bool] = None
) -> pd.DataFrame

PIX fraud statistics / MED (EstatisticasFraudesPix endpoint).

database is required, in YYYYMM form. The exact schema varies, so columns are not validated; numeric-looking columns are coerced.

ping ¶

ping() -> pd.DataFrame

Test connectivity to all four endpoints with a single-record request.

Convenience functions¶

These mirror the R package pixr. Each creates a short-lived PixClient.

PIX keys¶

pixbr.get_pix_keys ¶

get_pix_keys(
    date: str, *, verbose: bool = True, **kwargs
) -> pd.DataFrame

pixbr.get_pix_keys_summary ¶

get_pix_keys_summary(
    date: str, n_top: int = 20, *, verbose: bool = True
) -> pd.DataFrame

pixbr.get_pix_keys_by_type ¶

get_pix_keys_by_type(
    date: str, *, verbose: bool = True
) -> pd.DataFrame

Transactions by municipality¶

pixbr.get_pix_transactions_by_municipality ¶

get_pix_transactions_by_municipality(
    database: str, *, verbose: bool = True, **kwargs
) -> pd.DataFrame

pixbr.get_pix_transactions_by_state ¶

get_pix_transactions_by_state(
    database: str, *, verbose: bool = True
) -> pd.DataFrame

pixbr.get_pix_transactions_by_region ¶

get_pix_transactions_by_region(
    database: str, *, verbose: bool = True
) -> pd.DataFrame

Transaction statistics¶

pixbr.get_pix_transaction_stats ¶

get_pix_transaction_stats(
    database: str, *, verbose: bool = True, **kwargs
) -> pd.DataFrame

pixbr.get_pix_summary ¶

get_pix_summary(
    database: str,
    group_by="NATUREZA",
    *,
    verbose: bool = True
) -> pd.DataFrame

pixbr.get_pix_transaction_stats_multi ¶

get_pix_transaction_stats_multi(
    databases: Sequence[str], **kwargs
) -> pd.DataFrame

Fraud statistics¶

pixbr.get_pix_fraud_stats ¶

get_pix_fraud_stats(
    database: str, *, verbose: bool = True, **kwargs
) -> pd.DataFrame

pixbr.get_pix_fraud_stats_multi ¶

get_pix_fraud_stats_multi(
    databases: Sequence[str], **kwargs
) -> pd.DataFrame

API utilities¶

pixbr.pix_ping ¶

pix_ping() -> pd.DataFrame

pixbr.pix_query ¶

pix_query(
    endpoint: str,
    params: Optional[dict] = None,
    *,
    verbose: bool = True,
    **kwargs
) -> pd.DataFrame

pixbr.pix_url ¶

pix_url(
    endpoint: str, params: Optional[dict] = None, **kwargs
) -> str

pixbr.pix_endpoints ¶

pix_endpoints() -> pd.DataFrame

Return a DataFrame describing the available BCB PIX API endpoints.

pixbr.pix_columns ¶

pix_columns(endpoint: str = 'keys') -> pd.DataFrame

Return column metadata for an endpoint.

endpoint is one of "keys", "municipality", "stats", "fraud".

Data helpers¶

pixbr.year_month_to_date ¶

year_month_to_date(
    year_month: Union[str, Iterable[str]],
) -> Union[pd.Timestamp, pd.DatetimeIndex]

Convert YYYYMM string(s) to date(s) at the first day of the month.

pixbr.format_brl ¶

format_brl(
    x: Union[float, Iterable[float]],
    prefix: bool = True,
    decimal_mark: str = ",",
    big_mark: str = ".",
) -> Union[str, list[str]]

Format number(s) as Brazilian Real currency (e.g. R$ 1.234.567,89).

Errors¶

pixbr.PixApiError ¶

Bases: RuntimeError

Raised when the BCB PIX API returns an error or cannot be reached.