blockfill

What this skill does

## What is blockfill

blockfill is a **local-first smart execution daemon** for crypto trading. It runs entirely on your machine — your API keys are stored locally and never transmitted to any third-party server.

**Why blockfill**:

- **Secure** — API keys stay local, no cloud dependency
- **Smart execution** — built-in maker/TWAP strategies, handles order slicing and timing automatically
- **Multi-exchange** — Binance Futures and OKX Swap from a single daemon
- **Self-healing** — daemon auto-restarts executors on panic; supervises per-exchange WS connections
- **AI-native** — CLI + Python SDK designed for programmatic use by scripts and AI agents

**Key concepts**:

- **Ticket**: an execution order (`exchange + symbol + strategy + target_position + time_constraint_ms`)
- **Daemon**: background process that manages exchange WS connections and executes tickets
- **CLI**: `blockfill` binary — human and agent interface to the daemon
- **Python SDK**: `from blockfill import Blockfill` — zero-overhead programmatic interface

---

## Install

```bash
pip install blockfill                    # latest
pip install -U blockfill                 # upgrade (pip never auto-upgrades)
```

The wheel ships with the executor binary bundled inside (no separate
download). PyPI publishes only platform-specific wheels — incompatible
hosts get a clean `No matching distribution`. Currently:

- `manylinux2014_x86_64` (Linux x86_64)
- `manylinux2014_aarch64` (Linux arm64)
- `macosx_11_0_arm64` (Apple Silicon)
- `macosx_10_15_x86_64` (Intel macOS)

The qtex endpoint and API key are hardcoded into the binary at release time —
users never set them.

---

## Supported exchanges

| Exchange                 | Value             | Credentials                                          | Multi-exchange in one daemon |
| ------------------------ | ----------------- | ---------------------------------------------------- | ---------------------------- |
| Binance Futures (USDT-M) | `binance-futures` | `api_key`, `api_secret`, `testnet`                   | ✓                            |
| OKX Swap                 | `okx-swap`        | `api_key`, `api_secret`, `api_passphrase`, `testnet` | ✓                            |

A single daemon can run **both** exchanges concurrently. Add credentials for
each one — the daemon spawns a per-exchange executor.

---

## Supported symbols

Each exchange uses its **own native symbol format** — they are not the same.

| Exchange          | Format                                                | Examples                                                            |
| ----------------- | ----------------------------------------------------- | ------------------------------------------------------------------- |
| `binance-futures` | Lowercase, concatenated (Binance native)              | `btcusdt`, `ethusdt`, `solusdt`, `dogeusdt`                         |
| `okx-swap`        | Dash-separated, includes contract suffix (OKX native) | `BTC-USDT-SWAP`, `ETH-USDT-SWAP`, `SOL-USDT-SWAP`, `DOGE-USDT-SWAP` |

Use the exact format the target exchange expects — blockfill does NOT
cross-translate.

---

## Execution strategies

Two strategies are supported via the public ticket API:

| Strategy | Behavior                                                                                                                                                                                     | When to use                                                                  |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `maker`  | **Passive maker.** Posts PostOnly limit orders that sit on the book and earn the maker rebate. In the last segment of the time window, falls back to IOC to clean up any unfilled remainder. | Default. Cost-optimal when fill speed is not critical.                       |
| `twap`   | **Pure-taker TWAP.** Places IOC orders on a TWAP schedule across the full time window — no PostOnly phase. Always crosses the spread.                                                        | When you need guaranteed completion within the window and accept taker cost. |

Default: `maker`.

---

## Ticket parameters

| Parameter            | Type   | Required | Default  | Description                                                                                                                             |
| -------------------- | ------ | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `exchange`           | string | ✅       | —        | `binance-futures` or `okx-swap`                                                                                                         |
| `symbol`             | string | ✅       | —        | Lowercase, e.g. `btcusdt`                                                                                                               |
| `target_position`    | float  | ✅       | —        | Target position in base asset. Positive = long, negative = short                                                                        |
| `strategy`           | string |          | `maker`  | `maker` \| `twap`                                                                                                                       |
| `time_constraint_ms` | int    |          | `300000` | Execution window in ms (10,000–86,400,000). At the end of the window the executor falls back to taker fills for any unfilled remainder. |

**Auto-supersede**: placing a new ticket for the same `exchange+symbol` automatically cancels existing **NEW and OPEN** tickets for that pair (`cancel_reason: "superseded"`). The superseded ticket remains visible in queries with `status: CANCEL`.

---

## Ticket schema

```json
{
    "ticket_id": "tkt_18b2b09ca766001e",
    "status": "OPEN",
    "exchange": "binance-futures",
    "symbol": "btcusdt",
    "strategy": "maker",
    "target_position": 0.5,
    "init_position": 0.0,
    "executed_position": 0.13,
    "time_constraint_ms": 300000,
    "start_time_ms": 1779287926007,
    "last_update_time_ms": 1779287935063,
    "is_expired": false,
    "cancel_reason": null
}
```

| Field                 | Type           | Description                                                                                                                 |
| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id`           | string         | `tkt_<hex>`                                                                                                                 |
| `status`              | string         | `NEW` \| `OPEN` \| `COMPLETE` \| `CANCEL`                                                                                   |
| `exchange`            | string         | `binance-futures` \| `okx-swap`                                                                                             |
| `symbol`              | string         | Lowercase symbol                                                                                                            |
| `strategy`            | string         | `maker` \| `twap`                                                                                                           |
| `target_position`     | float          | Requested net position                                                                                                      |
| `init_position`       | float \| null  | Exchange position at activation time (null while NEW)                                                                       |
| `executed_position`   | float