Blockfill Python SDK
BlockFill Agent Execution is an AI-agent-ready Python SDK and local execution
engine for crypto perpetual-futures and spot order execution. It enables AI
agents, trading systems, and developers to execute large orders through TWAP and
maker-style strategies across 11 CEX and DEX venues (Binance, OKX, Bybit,
Bitget, Gate.io, KuCoin, Kraken, Deribit, Hyperliquid, Aster, Orderly), while
keeping exchange API keys on the user's own machine.
You declare a target position; BlockFill works the order over a time window
using maker (PostOnly resting + IOC fallback) or twap (taker-sliced)
strategies, cutting execution slippage vs. naïve market orders.
One Python API, one local daemon, 11 venues across spot + perp (see
Supported venues), one bf.place(...) call per target
position.
Supported venues
The agent exchange id is <venue>-<product> — pass it to set_credentials(...)
and use it everywhere (bf.place, bf.quota, …).
| Exchange | Exchange id (perp/futures · spot) | Quote (spot · perp) |
|---|
| Binance | binance-futures · binance-spot | usdt, usdc, fdusd, usd · usdt, usdc |
| OKX | okx-swap · okx-spot | usdt, usdc, usd · usdt |
| Bybit | bybit-perp · bybit-spot | usdt, usdc, usd · usdt, usdc |
| Bitget | bitget-futures · bitget-spot | usdt, usdc, usd · usdt, usdc |
| Gate.io | gateio-futures · gateio-spot | usdt, usdc · usdt |
| KuCoin | kucoin-futures · kucoin-spot | usdt, usdc · usdt, usdc |
| Kraken | kraken-futures · kraken-spot | usd, usdt, usdc · usd |
| Deribit | deribit-perp · deribit-spot | usdc, usdt · usdc |
| Hyperliquid | hyperliquid-perp · hyperliquid-spot | usdc · usdc |
| Aster | aster-perp · aster-spot | usdt · usdt |
| Orderly | orderly-<broker> (WOOFi Pro, …) | — · usdc |
CEX (Binance, OKX, Bybit, Bitget, Gate.io, KuCoin, Kraken, Deribit) use
api_key + api_secret (+ api_passphrase for OKX / KuCoin / Bitget) and are
billed by x402 quota. DEX (Hyperliquid, Aster, Orderly) sign with a wallet
and pay builder-code execution fees — no quota. Binance also supports TradFi
perpetuals (e.g. xauusdt).
Designed for AI Agents
BlockFill Agent Execution is designed to be called by AI agents, trading
copilots, MCP servers, strategy systems, and execution workflows.
Typical agent instruction:
Buy 100,000 USDT worth of BTC perpetuals over 30 minutes using TWAP, with
local API-key signing and no third-party custody.
BlockFill provides the execution layer behind that instruction:
- The agent decides the trading intent.
- BlockFill converts the intent into an executable ticket.
- The local daemon signs and places orders through the user's own exchange
API keys.
- The agent can query ticket status, positions, and execution results.
Security Model
BlockFill Agent Execution is self-custodial by design.
Exchange API keys stay on the user's own machine (~/.blockfill/config.toml,
chmod 0600). The local daemon signs orders locally and sends them directly to
the exchange. BlockFill does not custody user funds, store exchange API keys,
or route orders through a third-party trading server — no key custody, no
order routing, no order-flow visibility by a third party. The package only
ships the execution engine.
Requirements
- Python 3.10+
- macOS (Apple Silicon / arm64) or Linux (x86_64) — the daemon binary is bundled inside the wheel, so
pip fetches the platform-specific wheel automatically (macosx_11_0_arm64 or manylinux2014_x86_64). Other platforms (Windows, Intel macOS, linux-arm64) are not yet packaged.
Install
python3 -m venv .venv && source .venv/bin/activate
pip install -U blockfill
-U is intentional: it installs the latest release if you don't have it, and
upgrades in place if you do (without it, pip install blockfill is a no-op
when any version is already installed).
Verify the install
from blockfill import Blockfill
print(Blockfill().version())
Quickstart
⚠️ Order matters. bf.start() will refuse to launch if no exchange
credentials are configured. Always call set_credentials() first on a
fresh machine — see DaemonStartTimeout: no config.toml at ... below.
from blockfill import Blockfill
bf = Blockfill()
bf.set_credentials("binance-futures", api_key="...", api_secret="...", testnet=True)
bf.start()
bf.status()
ticket = bf.place(
exchange="binance-futures",
symbol="btcusdt",
strategy="maker",
target_position=0.1,
time_constraint_ms=300_000,
)
print(ticket.ticket_id, ticket.status)
tickets = bf.query(status="NEW")
bf.cancel(ticket.ticket_id)
bf.stop()
MCP (Claude Code / Claude Desktop)
BlockFill ships an MCP server that exposes the local daemon as tools an LLM can
call directly — status, instruments, place, query, cancel,
positions, nav, tca, quota, open_orders. Same security model: the
server runs on your machine and your API keys never leave the host.
Install (one command)
Claude Code — no prior install needed (uvx fetches blockfill[mcp] from
PyPI, bundled binary included):
claude mcp add blockfill -- uvx --from 'blockfill[mcp]' blockfill-mcp
Already pip installed? Register the installed server in one step:
pip install -U "blockfill[mcp]"
blockfill-mcp --install
--install detects and configures Claude Code (claude mcp add), Codex
(~/.codex/config.toml), and Cursor (~/.cursor/mcp.json) without clobbering
existing entries, and prints the generic block below for any other client. The
launch command is identical everywhere — only the config location/format differs.
Claude Desktop / any MCP client — add to the client config (e.g.
claude_desktop_config.json), then restart the client:
{
"mcpServers": {
"blockfill": { "command": "uvx", "args": ["--from", "blockfill[mcp]", "blockfill-mcp"] }
}
}
Then set exchange credentials once (credential entry is intentionally not an
MCP tool):
blockfill set-credentials --exchange binance-futures --api-key ... --api-secret ...
Plugin marketplace (optional — also bundles the skill)
For discovery / to ship the BlockFill skill alongside the tools:
/plugin marketplace add <this repo url>
/plugin install blockfill@blockfill
/reload-plugins
(The plugin's MCP server still uses the same uvx --from blockfill[mcp] blockfill-mcp command under the hood.)
API Reference
Version
Credentials
bf.set_credentials(
exchange: str,
api_key: str,
api_secret: str,
api_passphrase: str | None = None,
testnet: bool = False,
) -> None
The blockfill-server endpoint and API key are compiled into the binary at release time — you do not configure them.
Payment — x402 quota top-up
Quota applies to CEX venues only (Binance, OKX, Bybit, Bitget, Gate.io,
KuCoin, Kraken, Deribit); DEX venues (Hyperliquid, Aster, Orderly) pay
builder-code execution fees instead and have no quota.
Quota is tracked per (account, exchange) pair. Your account is a
de-identified hash of the exchange api_key (or, for wallet venues, the wallet
address) — computed locally, so the raw key/address never leaves your machine.
Each exchange credential therefore has its own quota.
Every pair starts with a free tier. When it runs out you buy more quota by
paying USDC on Base over x402 — a
gasless EIP-3009 transferWithAuthorization. The daemon holds the wallet key
and signs locally; only the signature + authorization leave the machine.
bf.set_payment(private_key: str | None) -> None
bf.topup(exchange: str, usdc: float = 1.0) -> dict | None
bf.set_payment("0x<64-hex private key>")
bf.topup("okx-swap", 1)
The key is never sent anywhere — the server only ever sees the signature and a
de-identified (hashed) account id, never your api_key or wallet key.
Daemon
bf.start(wait_timeout_s=10.0, env=None) -> None
bf.stop(wait_timeout_s=5.0) -> None
bf.restart() -> None
bf.status() -> DaemonStatus
For debugging, tail the daemon log directly:
tail -F ~/.blockfill/runtime/daemon.startup.log
DaemonStatus fields:
| Field | Type | Meaning |
|---|
running | bool | Daemon process is up and the RPC socket answered. |
pid | int | Daemon process id (0 if not running). |
exchange (prop) | dict[str, ExchangeStatus] | Per-exchange status keyed by name — see below. Primary way to check what's configured and what's ready. |
active_tickets | int | NEW/OPEN tickets currently tracked. |
uptime_s | int | Daemon process uptime in seconds. |
version | str | Daemon binary version (e.g. "1.0.X"). |
proxy | str | None | Active outbound proxy URL (or None for direct). |
blockfill-server | bool | True if blockfill-server is reachable. blockfill-server hosts the ticket-history endpoints (/public/v1/tickets/*) used by bf.query(history=True); when down, live trading is unaffected but history queries fail. Updated by a 10s background ping; flips False after 30s of no response. |
exchanges (list[str], configured names) and ready_exchanges
(list[str], warmed-up names) are also present on the dataclass as
flat-list shortcuts — they're just list(exchange.keys()) and
[n for n,e in exchange.items() if e.ready] respectively. Prefer
exchange[name].ready in code.
Per-exchange readiness (the only way to check ready — there is no
top-level ready flag because "all-ready" is rarely meaningful in a
multi-exchange daemon):
s = bf.status()
s.exchange
if s.exchange["binance-futures"].ready:
bf.place(exchange="binance-futures", ...)
ready=True means the executor finished warmup (REST symbol/book fetch,
authenticated get_account_balances, market-stream connect — ready_cb
fired). ready=False covers:
- daemon not running
- warmup in progress (typical 30–60s after
bf.start())
- init failed and supervisor is in its retry backoff (bad creds, IP
whitelist, geo block, exchange API down)
bf.place(exchange=X, ...) while X is not ready is rejected at the RPC
layer with -32000 X not ready — executor still warming up; poll system.status until ready_exchanges contains it — no ticket is created.
Tickets
Strategies
strategy | Behavior |
|---|
"maker" | Passive maker. Posts PostOnly limit orders that sit on the book. In the last segment of the time window, falls back to IOC to clean up any unfilled remainder. Lower fees (maker rebate when available), no guarantee of full fill if the book never crosses. |
"twap" | Pure-taker TWAP. Places IOC orders on a TWAP schedule across the time window — no PostOnly phase. Guarantees completion at the cost of crossing the spread on every slice. |
bf.place(
exchange: str,
symbol: str,
strategy: str = "maker",
target_position: float,
time_constraint_ms: int = 300_000,
) -> Ticket
bf.query(
status: str | None = None,
symbol: str | None = None,
ticket_id: str | None = None,
from_ms: int | None = None,
to_ms: int | None = None,
limit: int = 100,
history: bool = False,
) -> list[Ticket]
bf.cancel(ticket_id=None, symbol=None, all=False) -> None | int
Spot vs perp target_position. For perp/futures it is the net
directional position (positive = long, negative = short) — target=0.1 from
flat opens 0.1 long. For spot it is the absolute base-asset holding you want
to end up with, and init_position is your current base balance — so
target=0.001 on a 1.0 BTC balance sells 0.999. To add to a spot holding,
set target = current_holding + delta.
Ticket fields:
| Field | Type | Notes |
|---|
ticket_id | str | tkt_<hex> |
status | str | NEW / OPEN / COMPLETE / CANCEL |
exchange | str | binance-futures / okx-swap |
symbol | str | exchange-format symbol |
strategy | str | maker / twap |
target_position | float | requested net position |
init_position | float | None | exchange position at activation time |
executed_position | float | None | actual delta filled so far |
time_constraint_ms | int | execution time limit |
start_time_ms | int | None | set when executor activates the ticket (NEW → OPEN) |
last_update_time_ms | int | None | refreshed on every state change |
is_expired | bool | flag-only; status stays OPEN until separately cancelled |
cancel_reason | str | None | see table below |
cancel_reason values: external, superseded, stale, rejected, min_notional, risk_breach, insufficient_margin, paused
Auto-supersede: placing a new ticket for the same exchange+symbol immediately cancels any existing NEW/OPEN ticket for that pair (cancel_reason="superseded"). The superseded ticket remains in query results.
Diagnostics
bf.check_credentials() -> None
Positions
bf.positions() -> list[dict]
bf.nav() -> dict
bf.tca(ticket_id=None, symbol=None, from_ms=None, to_ms=None,
limit=100, history=False) -> list[dict]
Proxy / Geo-bypass
For hosts that can't reach Binance directly (US IPs return HTTP 451),
route exchange REST traffic through an HTTP CONNECT proxy.
Starchild users — the free sc-vpn skill provides a managed
proxy across 18 countries (500 GB/month, no credentials). Pick a country
code and pass the URL:
bf.set_proxy("http://jp:x@sc-vpn.internal:8080")
bf.set_proxy("http://sg:x@sc-vpn.internal:8080")
bf.set_proxy("http://hk:x@sc-vpn.internal:8080")
bf.set_proxy()
Country codes (ISO-2):
| Asia-Pacific | Europe | Americas |
|---|
jp Japan | uk United Kingdom | ca Canada |
sg Singapore | de Germany | br Brazil |
hk Hong Kong | fr France | mx Mexico |
kr South Korea | nl Netherlands | |
tw Taiwan | ch Switzerland | |
au Australia | it Italy | |
in India | es Spain | |
| se Sweden | |
For binance, jp / sg / hk give the lowest latency. See the
sc-vpn skill repo
for the authoritative list.
You can also pass any HTTP CONNECT proxy URL (residential / paid):
bf.set_proxy("http://user:pass@proxy.example.com:8080")
set_proxy auto-restarts the daemon (when running) so the new proxy
takes effect immediately — the daemon reads the proxy only at startup
and stashes it in a global, so a write-without-restart would leave the
running daemon on the OLD proxy.
The proxy applies to all REST traffic from daemon → exchange.
WebSocket proxy is on the TODO list — until then, daemon's market-data
streams go direct (and will fail on geo-blocked hosts).
Verify before committing: after bf.set_proxy(...) re-set credentials —
set_credentials auto-runs check_credentials which does a signed REST
round-trip through the proxy. A failure there means the proxy can't reach
the exchange, so you find out before starting the daemon.
Context Manager
with Blockfill() as bf:
bf.start()
ticket = bf.place(...)
Patterns
Strategy system integration
from blockfill import Blockfill
bf = Blockfill()
if not bf.status().running:
bf.start()
ticket = bf.place(
exchange="binance-futures",
symbol=symbol,
strategy="maker",
target_position=position,
time_constraint_ms=300_000,
)
Supported Exchanges
| Exchange | Value | Credentials |
|---|
| Binance Futures | "binance-futures" | api_key + api_secret (HMAC or Ed25519) |
| OKX Swap | "okx-swap" | api_key + api_secret + api_passphrase (HMAC) |
| Hyperliquid Perp | "hyperliquid-perp" | master address + agent wallet key (EIP-712) |
| Aster Perp | "aster-perp" | user + signer + agent wallet key (EIP-712) |
| Orderly (perps) | "orderly-<broker>" | account_id + ed25519 secret + broker_id |
("aster-perp-v1" also exists — Aster's legacy HMAC api_key/secret flow,
configured like a CEX. Prefer "aster-perp".)
Orderly: broker = the exchange (= a separate vault)
Orderly is a settlement layer, not an exchange — the broker (WOOFi Pro,
Raydium, …) is the venue. The same wallet under a different broker_id is a
separate account/vault (account_id = keccak256(wallet, keccak256(broker_id))).
So configure each broker as its own instance, orderly-<broker>:
bf.set_credentials("orderly-woofi",
account_id="0x...", orderly_secret="ed25519:...", broker_id="woofi_pro",
testnet=True)
bf.set_credentials("orderly-raydium",
account_id="0x...", orderly_secret="ed25519:...", broker_id="raydium",
testnet=True)
account_id is bound to broker_id at registration — you cannot switch brokers
by changing broker_id alone; register under the new broker and use that
account_id. (CLI: blockfill set-credentials --exchange orderly-raydium --api-key <account_id> --api-secret <ed25519 secret> --api-passphrase <broker_id>.)
Binance Ed25519 keys
Binance Futures testnet issues self-generated Ed25519 keys (no HMAC
secret). They work with the same call — pass the Ed25519 API Key id as
api_key and the PEM private key as api_secret; the daemon auto-detects
the PEM and signs with Ed25519 (REST + WS session.logon):
bf.set_credentials(
"binance-futures",
api_key="<Ed25519 API Key id from Binance>",
api_secret="""-----BEGIN PRIVATE KEY-----
MC4CAQAw...your PKCS#8 ed25519 key...
-----END PRIVATE KEY-----""",
testnet=True,
)
To create one: generate an Ed25519 keypair, register the public key (PEM)
at https://testnet.binancefuture.com → API Management, and Binance returns the
API Key id. Keep the private key for api_secret. HMAC keys keep working
unchanged.
Hyperliquid and Aster are wallet-signed DEXes — there is no api_key/secret.
Configure them via the SDK:
bf.set_credentials(
"hyperliquid-perp",
hl_master_address="0x...",
hl_agent_private_key="0x...",
)
bf.set_credentials(
"aster-perp",
aster_user="0x...",
aster_signer="0x...",
aster_agent_private_key="0x...",
)
or the bundled CLI (blockfill set-credentials --exchange hyperliquid-perp --hl-master-address 0x... --hl-agent-private-key 0x...; Aster:
--aster-user/--aster-signer/--aster-agent-private-key).
Each exchange has its own native symbol format. BlockFill does NOT
cross-translate — bf.place(symbol=...) must match exactly what the
exchange uses:
| Exchange | Format | Example |
|---|
binance-futures | lowercase, concatenated | dogeusdt |
okx-swap | dash-separated, -SWAP suffix | DOGE-USDT-SWAP |
hyperliquid-perp | coin only (perps are vs USDC) | BTC |
aster-perp | UPPERCASE, concatenated | BTCUSDT |
Don't guess — look it up with bf.instruments(<substring>). It scans
all configured exchanges and returns native-format matches:
bf.instruments("doge")
bf.place(exchange="binance-futures", symbol="dogeusdt", target_position=100)
bf.place(exchange="okx-swap", symbol="DOGE-USDT-SWAP", target_position=-100)
Wrong format → ticket auto-cancelled with cancel_reason="rejected"; no
order ever reaches the exchange.
FAQ
What is BlockFill Agent Execution?
BlockFill Agent Execution is an AI-agent-ready Python SDK and local execution
engine for crypto perpetual futures order execution.
Can AI agents use BlockFill?
Yes. AI agents, MCP servers, trading copilots, and strategy systems can call
the BlockFill Python SDK to place and manage execution tickets.
Does BlockFill custody user funds or API keys?
No. Exchange API keys stay on the user's machine. The local daemon signs
orders locally and sends them directly to the exchange.
Which exchanges does BlockFill support?
BlockFill currently supports Binance Futures, OKX Swap, Hyperliquid
(perpetuals), Aster (perpetuals), and Orderly-based perps venues (configured
per broker, e.g. WOOFi Pro / Raydium).
Which execution strategies are supported?
BlockFill currently supports TWAP execution and maker-style execution.
Is BlockFill an exchange?
No. BlockFill is not an exchange. It is an execution SDK and local order
execution engine that connects to supported exchanges through user-owned API
keys.
BlockFill Agent Execution is related to AI agent trading, crypto order
execution, TWAP execution, maker execution, algorithmic trading, perpetual
futures trading, Binance Futures execution, OKX Swap execution, Hyperliquid
execution, Aster execution, MCP trading tools, and self-custodial trading
infrastructure.
Support