RedBlack Python SDK

Typed Python client for the RedBlack trading, portfolio-rebalancing, and order-management API.

Alpha: the SDK is implemented from the offline RedBlack 2026.3.0 contract. Live UAT validation has not yet been run. See docs/UAT_VALIDATION.md.

Requirements

• Python 3.11 or newer
• A RedBlack environment, API key, application client ID, and either:
  • a RedBlack API username, password, and client secret; or
  • an externally managed access token

Install for development

python3 -m pip install -e '.[dev]'

Quick start

from redblack import Environment, PasswordCredentials, RedBlackClient

credentials = PasswordCredentials(
    client_secret="read-from-a-secret-store",
    username="read-from-a-secret-store",
    password="read-from-a-secret-store",
)

with RedBlackClient(
    environment=Environment.UAT,
    api_version="2026.3.0",
    api_key="read-from-a-secret-store",
    client_id="read-from-a-secret-store",
    credentials=credentials,
) as client:
    page = client.accounts.list(top=100, order_by="id asc")
    for account in page.items:
        print(account)

The normal constructor never reads environment variables or files. Applications that intentionally want configuration lookup can use RedBlackClient.from_env() or RedBlackClient.from_dotenv().

Safety defaults

• UAT or production must be selected explicitly.
• TLS verification is on and ambient proxy/CA variables are ignored by default.
• Access tokens are cached in memory and concurrent refresh is single-flight.
• Automatic retries apply to safe reads only.
• POST, PATCH, and DELETE are never replayed automatically.
• Task updates/deletes require the exact ETag returned by task retrieval.
• Deleting all cash actions requires a separate explicit confirmation.
• Export storage downloads never receive RedBlack credentials.
• Unknown response fields and enum values are preserved.

API shape

Endpoints are grouped under:

client.accounts
client.households
client.restrictions
client.equivalents
client.cash_actions
client.securities
client.orders
client.review_sets
client.users
client.tasks

Collection methods support RedBlack's OData options through Python arguments: filter, order_by, top, skip, and count.

List Trade Blotter or Trade Reconciliation orders with the new Orders resource:

from redblack.models import OrderFilterType

page = client.orders.list(top=100, count=True)  # Active Trade Blotter orders
for order in client.orders.iter_all(
    filter_type=OrderFilterType.IN_RECONCILIATION,
    order_by="id asc",
    max_items=1_000,
):
    print(order.id, order.quantity)

The SDK now defaults to Accept-Version: 2026.3.0; older API versions are not supported by typed methods. Orders in review sets remain accessible through client.review_sets.list_pending_orders().

Friendly request and response types such as Account, Task, TaskUpdate, and CashActionCreate are exported from redblack.models. Dictionary inputs are also validated before an HTTP request is sent.

Development commands

ruff format --check .
ruff check .
pyright
pytest
python3 tools/generate_sdk_models.py --check
python3 api-docs/tools/build_openapi_docs.py --check
python3 tools/check_operation_coverage.py
python3 -m build --no-isolation

The normal test suite uses mock transports and must not call RedBlack.

Documentation

• docs/REDBLACK_PRIMER.md — start here if you are new to RedBlack, rebalancing, or trading workflows
• docs/USAGE.md
• docs/API_COVERAGE.md
• docs/COMPATIBILITY.md
• docs/UAT_VALIDATION.md