blockfill 0.1.0

Python SDK for the blockfill execution daemon

blockfill Python SDK

Python wrapper for the blockfill execution daemon. Covers the full lifecycle: install binary, configure credentials, manage daemon, place/query/cancel tickets.

Requirements

• Python 3.10+
• blockfill binary (see Install)
• blockfill daemon running (see Daemon)

Install

pip install blockfill
# or from source
pip install -e /path/to/python-sdk

Quickstart

from blockfill import Blockfill

bf = Blockfill(
    binary_path="/path/to/blockfill",   # or ~/.blockfill/bin/blockfill
    data_dir="~/.blockfill",
)

# First-time setup
bf.set_credentials("binance-futures", api_key="...", api_secret="...")
bf.set_qtex_endpoint("https://qtex.example.com")

# Start daemon
bf.start(env={"BLOCKFILL_API_KEY": "..."})
bf.health()

# Place a ticket
ticket = bf.place(
    exchange="binance-futures",
    symbol="btcusdt",
    strategy="maker_l2",
    target_position=0.1,
    time_constraint_ms=300_000,
)
print(ticket.ticket_id, ticket.status)  # tkt_xxx NEW

# Query
tickets = bf.query(status="NEW")

# Cancel
bf.cancel(ticket.ticket_id)

# Stop daemon
bf.stop()

---

API Reference

Blockfill(binary_path, data_dir, timeout_s)

Parameter	Default	Description
binary_path	~/.blockfill/bin/blockfill	Path to blockfill binary
data_dir	~/.blockfill	Data directory (config, socket, logs)
timeout_s	10.0	RPC call timeout (seconds)

---

Install & Version

bf.install(version="latest", force=False) -> str
# Returns installed version string.
# If binary already exists and force=False, skips download and returns current version.

bf.version() -> str
# Returns "blockfill 0.1.0"

---

Credentials

bf.set_credentials(
    exchange: str,            # "binance-futures" | "okx-swap"
    api_key: str,
    api_secret: str,
    api_passphrase: str | None = None,  # OKX only
) -> None
# Writes to {data_dir}/config.toml (chmod 0600)

bf.set_qtex_endpoint(endpoint: str) -> None
# e.g. bf.set_qtex_endpoint("https://qtex.example.com")

---

Daemon

bf.start(wait_timeout_s=10.0, env=None) -> None
# Starts daemon in background. No-op if already running.
# env: extra environment variables (e.g. {"BLOCKFILL_API_KEY": "..."})

bf.stop(wait_timeout_s=5.0) -> None
# Graceful shutdown. No-op if not running.

bf.restart() -> None

bf.is_running() -> bool

bf.health() -> DaemonStatus
# Raises DaemonNotRunning if daemon is not up.

bf.run_foreground(env=None) -> None
# Blocking. For dev/debug.

DaemonStatus fields: running, pid, exchanges, active_tickets, uptime_s, version

---

Tickets

bf.place(
    exchange: str,
    symbol: str,
    strategy: str,
    target_position: float,       # positive = buy, negative = sell
    time_constraint_ms: int,
    client_ticket_id: str | None = None,  # idempotency key
) -> Ticket

bf.query(
    status: str | None = None,    # "NEW" | "OPEN" | "COMPLETE" | "CANCEL"
    symbol: str | None = None,
    ticket_id: str | None = None,
    from_ms: int | None = None,
    to_ms: int | None = None,
    limit: int = 100,
) -> list[Ticket]

bf.cancel(ticket_id: str) -> None
# Raises TicketNotFound if ticket doesn't exist.

bf.cancel_all() -> int
# Returns number of cancelled tickets.

Ticket fields: ticket_id, status, exchange, symbol, strategy, target_position, executed_position, time_constraint_ms, start_time_ms, last_update_time_ms, is_expired, cancel_reason

Auto-cancel: placing a new ticket for the same exchange+symbol automatically cancels existing NEW tickets for that pair.

---

Context Manager

with Blockfill(binary_path=..., data_dir=...) as bf:
    bf.start(env={"BLOCKFILL_API_KEY": "..."})
    ticket = bf.place(...)
# daemon is stopped on exit

---

Exceptions

Exception	When
BinaryNotFound	binary not found, call install() first
DaemonNotRunning	daemon socket not found or unreachable
DaemonStartTimeout	start() timed out waiting for daemon
RpcError(code, message)	daemon returned a JSON-RPC error
TicketNotFound	cancel() called with non-existent ticket_id
CredentialsError	invalid exchange name in set_credentials()
InstallError	binary download failed

---

Patterns

Strategy system integration

from blockfill import Blockfill, DaemonNotRunning

bf = Blockfill(binary_path="/path/to/blockfill")

# On startup
if not bf.is_running():
    bf.start(env={"BLOCKFILL_API_KEY": "..."})
bf.health()

# On each signal
ticket = bf.place(
    exchange="binance-futures",
    symbol=symbol,
    strategy="maker_l2",
    target_position=position,
    time_constraint_ms=300_000,
)

Idempotent placement (safe to retry)

import uuid

key = str(uuid.uuid4())  # generate once, reuse on retry

ticket = bf.place(
    exchange="binance-futures",
    symbol="btcusdt",
    strategy="maker_l2",
    target_position=0.1,
    time_constraint_ms=300_000,
    client_ticket_id=key,
)

Check open positions

open_tickets = bf.query(status="NEW") + bf.query(status="OPEN")
for t in open_tickets:
    print(t.symbol, t.target_position, t.executed_position)

---

AI Agent Usage

The SDK is designed for programmatic use by AI agents (Claude, GPT, etc.).

import sys
sys.path.insert(0, "/path/to/python-sdk")

import os
os.environ["BLOCKFILL_API_KEY"] = "your_api_key"

from blockfill import Blockfill, DaemonNotRunning, TicketNotFound

bf = Blockfill(
    binary_path="/path/to/blockfill",
    data_dir="/path/to/data_dir",
)

if not bf.is_running():
    bf.start(env={"BLOCKFILL_API_KEY": os.environ["BLOCKFILL_API_KEY"]})

bf.health()  # raises if daemon not ready

Key points for agents:

• Always call bf.health() before placing tickets
• Use client_ticket_id=uuid.uuid4() for idempotent retries
• place() auto-cancels existing NEW tickets for the same exchange+symbol
• query() returns data from qtex MongoDB (not exchange realtime)

---

Directory Structure

~/.blockfill/
├── config.toml              # credentials + qtex endpoint (chmod 0600)
├── bin/
│   └── blockfill            # binary
├── runtime/
│   ├── daemon.sock          # UDS socket (CLI ↔ daemon IPC)
│   ├── daemon.pid           # PID file
│   └── daemon.log           # daemon logs
└── trading-log/             # Channel B upload retry buffer

Supported Exchanges

Exchange	Value
Binance Futures	"binance-futures"
OKX Swap	"okx-swap"