Start Here

Using the Python SDK

Configure authentication, timeouts, retries, and logging for the Python SDK.

Initialize the client

Your Blnk client is the single entry point to everything: ledgers, balances, transactions, webhooks, and more. Configure it once when your app starts, then use it everywhere.

from blnk_sdk import BlnkClientOptions, blnk_init

api_key = os.environ.get("BLNK_API_KEY", "")
base_url = os.environ.get(
    "BLNK_BASE_URL",
    "http://localhost:5001",
)

blnk = blnk_init(
    api_key,
    BlnkClientOptions(base_url=base_url),
)

That’s it. One import, one call, one client. From here you can create ledgers, move money, reconcile transactions, and manage your entire financial infrastructure.

from blnk_client import blnk

response = blnk.ledgers.create(
    {
        "name": "Customer Savings Account",
        "meta_data": {
            "project_owner": "YOUR_APP_NAME",
        },
    }
)

print("Ledger Created:", response.data)

Use a context manager when you want the underlying requests.Session closed automatically:

from blnk_sdk import BlnkClientOptions, blnk_init

with blnk_init(api_key, BlnkClientOptions(base_url=base_url)) as blnk:
    response = blnk.ledgers.create({"name": "Temporary ledger"})

Authentication

blnk_init takes two arguments: an API key and a BlnkClientOptions object.

The options object must include base_url, the root URL of your Blnk Core instance. The SDK sends the API key on every request in the X-Blnk-Key header.

How you set the API key depends on whether Core runs in secure mode:

from blnk_sdk import BlnkClientOptions, blnk_init

api_key = os.environ.get("BLNK_API_KEY", "")
base_url = os.environ.get(
    "BLNK_BASE_URL",
    "http://localhost:5001",
)

blnk = blnk_init(
    api_key,
    BlnkClientOptions(base_url=base_url),
)

from blnk_sdk import BlnkClientOptions, blnk_init

blnk = blnk_init(
    "",
    BlnkClientOptions(base_url="http://localhost:5001"),
)

Timeouts and retries

When connections fail, Core restarts, or requests hang, the SDK handles it without blocking your app. Pass these parameters on BlnkClientOptions:

from blnk_sdk import BlnkClientOptions, blnk_init

blnk = blnk_init(
    api_key,
    BlnkClientOptions(
        base_url="http://localhost:5001",
        timeout=30000,
        retry_count=3,
        retry_delay_ms=2000,
    ),
)

When to tune these:

• Keep defaults if you’re making fast, local calls and want to fail fast.
• Increase timeout if you’re running large batch requests that may take a while to complete synchronously.
• Increase retry_count if you’re reading data across an unreliable network.

Custom logger

By default, the SDK logs internal events through a built-in logger that writes to the console with INFO:, ERROR:, and DEBUG: prefixes.

Pass a custom logger to route these messages to your own logging system instead of the console.

from blnk_sdk import BlnkClientOptions, CustomLogger, blnk_init

class AppLogger(CustomLogger):
    def info(self, message, *meta):
        app_logger.info(message, extra={"meta": meta})

    def error(self, message, *meta):
        app_logger.error(message, extra={"meta": meta})

blnk = blnk_init(
    api_key,
    BlnkClientOptions(
        base_url="http://localhost:5001",
        logger=AppLogger(),
    ),
)

INFO: Retrying request to transactions/txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94 { attempt: 2, maxAttempts: 3, delayMs: 2000 }

ERROR: Request timed out { endpoint: 'transactions/txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94', timeoutMs: 30000 }

ERROR: Request to transactions/txn_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94 failed with status 404.