blockfill-agent-execution

什么是 BlockFill Agent Execution

BlockFill Agent Execution 是一项用于加密货币订单执行的 AI Agent 执行技能。它完全在你的机器上运行——API 密钥保存在本地，绝不会传输到任何第三方服务器。它不是供人工操作的交易界面，而是由 AI Agent 通过 SDK/MCP 调用。

一句话定位：BlockFill Agent Execution 是一项用于加密货币订单执行的 AI Agent 执行技能，专注于 TWAP、做市执行、交易成本分析和降低滑点。

能力边界：BlockFill Agent Execution 只负责执行优化。它不会生成买入/卖出信号、提供投资建议、决定持仓方向或承诺盈利。Agent 必须从用户处获取方向和数量——BlockFill Agent Execution 会高效地执行这些指令。

核心概念：

• Ticket：执行订单（exchange + symbol + strategy + target_position + time_constraint_ms）
• Daemon：管理交易所 WebSocket 连接并执行 tickets 的后台进程
• CLI：blockfill 二进制程序——用户和 Agent 与 daemon 交互的接口
• Python SDK：from blockfill import Blockfill——供 Agent 使用的编程接口

---

触发关键词 / 何时调用

当用户请求符合以下任一条件时，调用此技能。英文和中文变体均适用。

订单执行： place order、place a trade、execute order、submit order、下單、掛單、執行訂單、下合約

策略关键词： maker、TWAP、twap、taker、post-only、limit order、time-weighted、slice order、拆單、掛單策略、時間加權

成本 / 滑点： reduce slippage、minimize cost、execution cost、TCA、transaction cost analysis、slippage reduction、降滑點、成本分析、執行成本

交易所 / 期货相关： perpetual、perp、futures、binance futures、okx swap、bybit、hyperliquid、bitget、gate.io、gateio、kucoin、kraken、deribit、aster、orderly、合約、永續合約、期貨

取消 / 查询： cancel order、cancel ticket、query ticket、check order status、取消訂單、查詢訂單、查單、取消掛單

设置： set credentials、set api key、configure exchange、set proxy、blockfill、設定 API、設定代理

以下情况请勿调用：

• 用户请求投资建议、买入/卖出推荐或价格预测
• 用户请求投资组合管理或再平衡决策
• 用户请求在不受支持的交易所进行现货交易
• 用户请求使用下方支持列表中未列出的交易所

---

功能

BlockFill Agent Execution 提供六项核心功能，每项功能只负责一件事。

功能	SDK 方法	功能说明
place_order	bf.place(...)	为指定交易所、交易对、目标持仓和时间窗口创建执行 ticket（做市或 TWAP）。不会决定方向或数量——这些由用户提供。
query_ticket	bf.query(...)	根据 ticket_id、symbol 或时间范围，返回 ticket 的当前状态、已成交数量和进度。
cancel_ticket	bf.cancel(ticket_id='tkt_...')	根据 ticket_id 取消处于活动状态的 ticket（NEW 或 OPEN）。未完成的交易所订单会自动撤销。示例：bf.cancel(ticket_id='tkt_18b2b09ca766001e') 会返回状态为 status='CANCEL' 的已取消 ticket 对象。
compare_tca	bf.tca(...)	获取已完成 ticket 的交易成本分析，包括执行成本与基准值（L1/中间价/TWAP/VWAP）的对比、节省的基点数，以及做市/吃单明细。
set_credentials	bf.set_credentials(...)	将交易所 API 凭据写入本地配置（~/.blockfill/config.toml，权限设为 0600），并通过签名 REST 往返请求验证连接。
set_proxy	bf.set_proxy(...)	为所有交易所 REST 和 WebSocket 流量配置 HTTP CONNECT 代理。地理位置受限的主机必须使用此代理（例如，美国 IP 无法直接连接 Binance）。

---

何时使用 BlockFill Agent Execution

当用户需要以下操作时，请使用 BlockFill Agent Execution：

• 执行大额订单，同时降低市场影响（TWAP 分片或挂出 Maker 订单）
• 尽量降低执行成本——获取 Maker 返佣，相比市价单减少滑点
• 在 AI Agent 交易工作流中自动执行订单
• 分析执行质量——将实际成交价格与 L1／中间价／TWAP／VWAP 基准进行比较
• 通过单次 Agent 调用将订单路由至多个交易所
• 通过代理在受地理限制的交易所（从美国／中国访问 Binance）执行交易

典型触发条件：用户已指定方向和数量，并希望高效执行。BlockFill Agent Execution 负责处理如何执行，而不负责决定交易什么或为什么交易。

---

何时不使用 BlockFill Agent Execution

以下情况请勿使用 BlockFill Agent Execution：

• 用户尚未指定交易所、交易对、方向或数量——先询问，不要猜测
• 用户在询问买入／卖出建议或目标价格——BlockFill Agent Execution 不提供投资建议；请转用合适的研究工具
• 目标市场是不受支持的交易所上的现货市场——请检查受支持的交易所列表
• 用户想交易股票、外汇或非加密资产——不在适用范围内
• 环境尚未配置（没有 API 凭据，或访问受地理限制的主机时没有代理）——先完成配置，再进行交易
• 用户要求的仓位超过其声明的风险承受能力——继续操作前请向用户确认
• 用户尚未确认使用 mainnet 还是 testnet——默认使用 testnet，实盘交易前先询问

---

下单前——Agent 检查清单

调用 place_order 前，请确认已获取所有必需信息。如有缺失，请询问用户——不要擅自假定交易方向、数量或环境。

项目	必需	缺失时
交易所	✅	询问：“使用哪个交易所？（例如 binance-futures、okx-swap）”
交易对	✅	询问：“使用哪个交易对？请采用原生格式（例如 Binance 使用 btcusdt）”
方向（做多／做空／平仓）	✅	询问：“买入还是卖出？目标仓位是多少？”
数量／目标仓位	✅	询问：“数量是多少？以基础资产单位计。”
环境（testnet／mainnet）	✅	默认使用 testnet。使用 mainnet 前请确认。
策略	✗	默认值：maker。请告知用户。
时间窗口	✗	默认值：300,000 ms（5 分钟）。请告知用户。
代理（受地理限制时）	✗	如果是 Binance 且所在地区不在白名单中，请发出警告。可提供 sc-vpn。

Binance TradFi 交易对

binance-futures 还列出了 157 个 TradFi 永续合约，包括股票（tslausdt、 nvdausdt、skhynixusdt）、大宗商品（xauusdt、xagusdt、clusdt）和 IPO 前标的（openaiusdt、anthropicusdt）。Binance 会要求用户一次性 签署账户协议；若未签署，所有订单都会被拒绝，错误码为 -4411，订单会一直 显示 0% 成交，直到过期。

set_credentials / check_credentials 会在 mainnet 上签署该协议，并 报告 "tradfi_perps": "signed"，因此这些交易对无需额外设置。如果 TradFi 订单一直无法成交，请先运行 check_credentials() 并查看该字段。

请告知用户你已代其接受的内容：与 Binance 受 ADGM 监管的实体签订具有约束力的协议，涵盖现金市场交易时段以外的全天候交易、不拥有标的资产，以及最高 ±2.00% 的资金费率（btcusdt 为 ±0.30%）。Binance 不提供撤销该协议的 API。

请注意，paxgusdt / xautusdt 不是 TradFi 标的，而是普通的黄金支持型代币，合约类型为 PERPETUAL，无需签署协议。

Hyperliquid / Aster 构建者费用授权

两个 DEX 交易场所都会拒绝任何携带未获授权构建者代码的订单—— Hyperliquid 会显示 Builder fee has not been approved——随后该订单会一直处于 0% 成交状态，直到订单窗口过期。用户必须通过 MAIN 钱包签名，在链上授权一次：

交易场所	构建者地址	授权费率
Hyperliquid（永续合约 + 现货）	0xB972e5151b20863380A3E7354dd93F1b888E3352	≥ 0.015%（1.5 bp）
Aster（仅永续合约）	0xB972e5151b20863380A3E7354dd93F1b888E3352	≥ 0.015%（1.5 bp）

BlockFill 会代用户签署此授权。 这些交易场所使用账户所有者钱包的 private_key（而非委托 Agent 密钥），正是为了能够执行以下操作： check_credentials() 会读取当前授权状态；如果缺少授权或费率低于要求，就会签署 approveBuilderFee / approveBuilder，并报告 "builder_fee": "approved just now at 0.015%"。只有签署失败时，检查才会失败。Aster 现货无需授权；Aster Code 仅适用于永续合约。

请告知用户该密钥可以执行的操作：它可用于签署订单以及这项费用授权，而且也可以用于提现——交易所不再阻止提现，唯一的限制是引擎中没有提现代码。完整的可签名操作列表请参见 docs/security/trade-only-permissions.md。

⚠️ 测试网不会附带构建者代码，因此不会出现此问题。 测试网运行可能完全通过，但第一笔主网订单仍可能失败。将用户从测试网切换到这些交易场所的主网时，请在下单前重新运行 check_credentials()。

---

安装

pip install blockfill                    # latest
pip install -U blockfill                 # upgrade

Wheel 包内已捆绑执行器二进制文件（无需单独下载）。PyPI 仅发布特定平台的 Wheel 包。目前支持：manylinux2014_x86_64（Linux x86_64）。

blockfill-server 端点和 API 密钥在发布时硬编码到二进制文件中，用户无需设置。

---

支持的交易所

每个交易场所都通过一个守护进程运行永续合约／期货 + 现货。交易所 ID 格式为 <venue>-<product>（例如 binance-futures、okx-swap、bybit-perp、<venue>-spot）。

交易所	交易所 ID（永续合约／期货 · 现货）	凭据	类别
Binance	binance-futures · binance-spot	api_key、api_secret（HMAC 或 Ed25519 PEM）、testnet	CEX
OKX	okx-swap · okx-spot	api_key、api_secret、api_passphrase、testnet	CEX
Bybit	bybit-perp · bybit-spot	api_key、api_secret、testnet	CEX
Bitget	bitget-futures · bitget-spot	api_key、api_secret、api_passphrase、testnet	CEX
Gate.io	gateio-futures · gateio-spot	api_key、api_secret、testnet	CEX
KuCoin	kucoin-futures · kucoin-spot	api_key、api_secret、api_passphrase、testnet	CEX
Kraken	kraken-futures · kraken-spot	api_key、api_secret、testnet	CEX
Deribit	deribit-perp · deribit-spot	api_key、api_secret、testnet	CEX
Hyperliquid	hyperliquid-perp · hyperliquid-spot	private_key（账户钱包，EIP-712）	DEX
Aster	aster-perp · aster-spot	private_key（账户钱包，EIP-712）	DEX
Orderly	orderly-<broker>	account_id、orderly_secret、broker_id（Ed25519；见下文）	DEX

单个守护进程可以同时运行所有交易所。CEX 按 x402 配额计费（见“支付”）；DEX（Hyperliquid / Aster / Orderly）支付构建者代码执行费，且不设配额。

Hyperliquid / Aster — 钱包签名的 DEX：

bf.set_credentials("hyperliquid-perp",
                   private_key="0x...")
bf.set_credentials("aster-perp",
                   private_key="0x...")

Binance Ed25519 密钥——Binance Futures 测试网会发放 Ed25519 密钥（没有 HMAC 密钥）。设置 api_key = Ed25519 API Key ID，api_secret = PEM 私钥。守护进程会自动检测并使用 Ed25519 签名。

bf.set_credentials("binance-futures",
    api_key="<Ed25519 API Key id>",
    api_secret="-----BEGIN PRIVATE KEY-----\nMC4CAQAw...\n-----END PRIVATE KEY-----",
    testnet=True)

Orderly——将每个经纪商建模为独立的交易所实例，名称为 orderly-<broker>：

bf.set_credentials("orderly-woofi",
    account_id="0x...", orderly_secret="ed25519:...", broker_id="woofi_pro", testnet=True)

---

支持的交易对符号

每个交易所使用自己的原生符号格式。

交易所	格式	示例
binance-futures	小写，直接拼接	btcusdt、ethusdt、solusdt
okx-swap	用连字符分隔 + SWAP 后缀	BTC-USDT-SWAP、ETH-USDT-SWAP
bybit-perp	大写，直接拼接	BTCUSDT、ETHUSDT
bitget-futures	大写，直接拼接	BTCUSDT、ETHUSDT
gateio-futures	用下划线分隔	BTC_USDT、ETH_USDT
kucoin-futures	合约代码	XBTUSDTM、ETHUSDTM
kraken-futures	PF_ 前缀 + 基础货币/计价货币	PF_XBTUSD、PF_ETHUSD
deribit-perp	用连字符分隔 + PERPETUAL 后缀	BTC-PERPETUAL、ETH-PERPETUAL
hyperliquid-perp	仅币种	BTC、ETH、SOL
aster-perp	大写，直接拼接	BTCUSDT、ETHUSDT
orderly-<broker>	通过 broker 确定，因交易所而异	使用 bf.instruments(substring) 进行查询

请使用目标交易所要求的精确格式——BlockFill Agent Execution 不会跨格式转换。查询任何交易场所的精确字符串：

blockfill check instrument --symbol btc

---

执行策略

策略	行为	适用场景
maker	下达 PostOnly 限价单；赚取做市返佣。窗口结束时，对任何未成交部分改用 IOC。	默认。 对成交速度要求不高时，成本最优。
twap	在整个窗口内按 TWAP 计划下达 IOC 订单——始终主动跨越价差。	需要确保完成且接受吃单成本时。

默认策略：maker。

---

票据参数

参数	类型	必填	默认值	描述
exchange	string	✅	—	支持的交易所 ID，例如 binance-futures、okx-swap
symbol	string	✅	—	交易所原生格式，例如 btcusdt（Binance）、BTC-USDT-SWAP（OKX）
target_position	float	✅	—	基础资产的目标仓位。正数 = 做多，负数 = 做空（永续合约）。现货：最终持有的基础资产绝对数量。
strategy	string		maker	maker | twap
time_constraint_ms	int		300000	执行窗口，单位为毫秒。范围：60,000–86,400,000（1 分钟至 24 小时）。窗口结束时，执行器会对任何未成交部分改用吃单成交。

自动替换：为相同的 exchange+symbol 下达新票据时，会自动取消该交易对已有的 NEW 和 OPEN 票据。

现货与永续合约的 target_position：永续合约 = 净方向仓位（正数 = 做多，负数 = 做空）。现货 = 最终持有的基础资产绝对数量（在 1.0 BTC 余额上设置 target=0.001，会卖出 0.999；若要增加持仓，请设置 target = current_holding + delta）。

---

票据架构

{
    "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
}

字段	类型	描述
ticket_id	string	tkt_<hex>
status	string	NEW | OPEN | COMPLETE | CANCEL
exchange	string	使用的交易所 ID
symbol	string	原生符号格式
strategy	string	maker | twap
target_position	float	请求的净仓位
init_position	float | null	激活时的仓位（处于 NEW 状态时为 null）
executed_position	float	目前已成交的净变动
time_constraint_ms	int	执行窗口，单位为毫秒
start_time_ms	int | null	执行器激活时设置（NEW → OPEN）
last_update_time_ms	int | null	每次状态变更时刷新
is_expired	bool	窗口已结束时为 True；状态会保持 OPEN，直到被取消
cancel_reason	string | null	external | superseded | stale | rejected | min_notional | risk_breach | insufficient_margin | paused

注意：票据没有 avg_price 或 cost 字段。如需查询执行成本、机会成本和基准对比，请调用 compare_tca（bf.tca(...)）——它会返回每张票据的 execution_cost_usd、opportunity_cost_usd 和基准（l1/mid/twap/vwap）。

---

快速入门（测试网）

from blockfill import Blockfill

bf = Blockfill()

# Step 1: Set credentials (SDK default is testnet=False/MAINNET — agents MUST pass testnet=True explicitly for sandboxed testing)
bf.set_credentials(
    exchange="binance-futures",
    api_key="...",
    api_secret="...",
    testnet=True,      # ALWAYS start with testnet
)

# Step 2: Start daemon (~50s warmup while it fetches market data)
bf.start()
bf.status()  # DaemonStatus(running=True, ready_exchanges=['binance-futures'], ...)

# Step 3: Place a ticket
ticket = bf.place(
    exchange="binance-futures",
    symbol="btcusdt",
    target_position=0.1,      # base asset units (BTC)
    strategy="maker",         # default
    time_constraint_ms=60_000,  # 60 seconds
)
print(ticket.ticket_id, ticket.status)

---

诊断

bf.check_credentials() -> None
# Hits a SIGNED REST endpoint per configured exchange; prints one line each:
# ✓ <name> / ✗ <name> <reason>.
# Detects: wrong key/secret, IP whitelist mismatch, testnet/mainnet mix-up,
# network/proxy/geo block. Auto-invoked at end of set_credentials().

bf.positions() -> list[dict]
# Aggregated positions from each running executor.
# Each entry: {exchange, symbol, size, entry_price, update_ts_ms}

bf.open_orders() -> list[dict]
# Active orders on each configured exchange right now.

bf.nav() -> dict
# Net Asset Value across all running executors.
# {exchanges: [{exchange, nav, wallet_balance, margin_value, unrealized_pnl}],
#  total_nav, exchanges_queried}

bf.tca(ticket_id=None, symbol=None, from_ms=None, to_ms=None, limit=100,
       history=False) -> list[dict]
# Transaction cost analysis for completed tickets.
# history=False: active session (in-memory).
# history=True:  persistent across all sessions (blockfill-server).
# Each entry: benchmarks (l1/mid/twap/vwap), fills, maker/taker breakdown,
# execution_cost_usd, opportunity_cost_usd, duration_ms.

bf.instruments(substring) -> list[dict]
# Per-exchange instrument lookup — returns native-format symbols matching
# substring. Use this to find the exact symbol string before placing.

---

代理 / 地理限制绕过

对于无法直接访问 Binance 的主机（美国 IP 会返回 HTTP 451），请通过 HTTP CONNECT 代理转发交易所的 REST 和 WebSocket 流量。

Starchild 用户 — 免费的 sc-vpn skill，覆盖 18 个国家/地区，每月 500 GB：

bf.set_proxy("http://jp:[email protected]:8080")   # Japan (lowest latency for Binance)
bf.set_proxy("http://sg:[email protected]:8080")   # Singapore
bf.set_proxy("http://hk:[email protected]:8080")   # Hong Kong
bf.set_proxy()                                      # clear proxy

亚太地区	欧洲	美洲
jp 日本	uk 英国	ca 加拿大
sg 新加坡	de 德国	br 巴西
hk 中国香港	fr 法国	mx 墨西哥
kr 韩国	nl 荷兰
tw 中国台湾	ch 瑞士
au 澳大利亚	it 意大利
in 印度	es 西班牙
	se 瑞典

任何 HTTP CONNECT 代理也都可以：

bf.set_proxy("http://user:[email protected]:8080")

set_proxy 会重启守护进程，使新设置生效。代理会覆盖 REST 和 WebSocket — 每个交易所 WebSocket 连接都会通过隧道传输。

下真实订单前，请先验证连接是否可达：

bf.set_proxy("http://jp:[email protected]:8080")
bf.set_credentials("binance-futures", api_key=..., api_secret=...)
# set_credentials auto-runs check_credentials() — a ✓ proves both proxy + auth work.

---

故障模式

出现故障时，请按以下顺序排查：凭据 → 代理 → 环境 → 交易对 → 保证金。

症状	可能原因	解决方法
check_credentials 输出 ✗ <exchange> IP not whitelisted	API 密钥绑定的 IP 与当前出站 IP 不同	将出站 IP（或代理 IP）添加到交易所 API 密钥白名单
check_credentials 输出 ✗ <exchange> connection refused / HTTP 451	地理限制（例如，美国 IP → Binance）	设置代理：bf.set_proxy("http://jp:[email protected]:8080")
check_credentials 输出 ✗ <exchange> invalid signature	api_secret 错误，或密钥类型错误（HMAC 与 Ed25519 不匹配）	重新检查凭据；Binance 测试网使用 Ed25519，而非 HMAC
Ticket 在 NEW 状态停留超过 30 秒	交易所未包含在 ready_exchanges 中（执行器仍在预热，或初始化失败）	检查 bf.status() → ready_exchanges；检查 blockfill logs 中的初始化错误
Ticket 的 cancel_reason: min_notional	订单数量 × 价格低于交易所最低名义金额	增加数量或使用更大的名义金额
Ticket 的 cancel_reason: insufficient_margin	仓位保证金不足	减少数量或增加保证金
Ticket 的 cancel_reason: rejected	交易所拒绝了订单（交易对已暂停、参数无效）	使用 bf.instruments(substring) 检查交易对；验证交易对格式
status 在超过 90 秒后仍显示 ready_exchanges: []	守护进程未能初始化一个或多个交易所	运行 blockfill stop && blockfill start；检查日志中的错误
Binance 现货（测试网）的 NAV = 0	测试网不支持 getUserAsset 端点	这是预期情况 — 测试网 NAV 使用 market-ticker 路由

如问题持续存在，请查看 GitLab Issues 或联系 Telegram 支持。完整知识库请参阅 docs/troubleshooting.md。

---

付款 — x402 配额

配额按 （账户，交易所） 对跟踪。每个账户与交易所组合都有 免费额度；每张 ticket 的 TCA 完成结算时会扣除配额。免费额度用尽后，可通过 x402 使用 Base 上的 USDC 付款购买更多额度 — 免 gas 的 EIP-3009 transferWithAuthorization。守护进程持有钱包密钥并在本地签名；只有签名会离开设备，密钥绝不会离开。

bf.set_payment("0x<64-hex private key>")     # store EVM wallet key
bf.topup("binance-futures", usdc=1.0)        # → {exchange, usdc, quota_balance, tx_hash}

CEX 交易所（Binance、OKX、Bybit、Bitget、Gate.io、KuCoin、Kraken、Deribit）使用配额。DEX（Hyperliquid、Aster、Orderly）直接支付构建者代码执行费用 — 不使用配额。

blockfill-server 只会看到签名和去标识化（经 SHA-256 哈希处理）的账户 ID，绝不会看到你的交易所 API 密钥或钱包密钥。

---

Agent 典型工作流

from blockfill import Blockfill
import os

bf = Blockfill()

# (Optional) configure proxy first if in a geo-blocked region
# bf.set_proxy("http://jp:[email protected]:8080")

# Set creds — SDK automatically verifies via signed REST
bf.set_credentials(
    "binance-futures",
    api_key=os.environ["BINANCE_API_KEY"],
    api_secret=os.environ["BINANCE_API_SECRET"],
    testnet=True,           # always confirm testnet vs mainnet with user
)

# Start daemon
bf.start()  # auto-waits ~50s for warmup

# Place ticket
ticket = bf.place(
    exchange="binance-futures",
    symbol="btcusdt",
    target_position=0.1,   # +0.1 BTC long
    strategy="maker",
    time_constraint_ms=300_000,
)

# Monitor
import time
while ticket.status in ("NEW", "OPEN"):
    time.sleep(5)
    ticket = bf.query(ticket_id=ticket.ticket_id)[0]
    print(f"filled: {ticket.executed_position} / {ticket.target_position}")

# TCA
tca = bf.tca(ticket_id=ticket.ticket_id)
print(tca)

bf.stop()

---

支持

• GitLab Issues：https://gitlab.com/quantech-services-group/blockfill-agent-execution/-/issues
• Telegram： @blockfill_support