MetaMask¶
The MetaMask broker runs inside LumiBot’s Python process and uses MetaMask
Agent Wallet managed signing. It calls MetaMask and Hyperliquid directly. No
Node, Bun, npm, MetaMask CLI or localhost service is required.
What BotSpot MCP adds
Use Claude, ChatGPT, Codex, Cursor, VS Code or another MCP-compatible assistant? Connect the free BotSpot MCP for:
Skills: build LumiBot strategies.
Free data: news, economics and SEC filings.
Backtests: run tests and read charts.
Cloud hosting: low-cost scheduled bots.
Community: share bots and discuss trades.
Marketplace: discover and publish strategies.
Broker linking: connect accounts through BotSpot.
Install and connect¶
The published package includes the native adapter: python -m pip install
'lumibot[metamask]'. Published releases may lag the latest execution and reporting fixes.
These changes are tracked in PR 1262;
check its merge state before relying on them. To install the latest unreleased
source from dev in a clean Python environment:
git clone --branch dev --single-branch https://github.com/Lumiwealth/lumibot.git lumibot-metamask
cd lumibot-metamask
git rev-parse HEAD
python -m pip install '.[metamask]'
Check the printed source commit against the intended revision before testing. Package availability and passing offline checks do not establish production qualification.
Authorize through the official MetaMask Agent Wallet sign-in page. Use the original Google/email method to retain the same wallet identity. The optional Python login function opens that page, accepts the copied browser token through a hidden prompt, verifies its identity, and writes an owner-only session file:
from lumibot.tools.metamask.owner import login
login("<private-directory>/session.json")
Login never creates a wallet, changes policy or funds an account. Select an
existing dedicated managed EVM wallet and review its Guard Mode policy in
MetaMask. Before trading, deliberately authorize its local registry, limits and
expiry using MetaMaskClient.authorize(). Broker startup does not renew or
broaden authority. See the complete binding example in the repository’s
MetaMask setup guide.
from lumibot.brokers import MetaMask
from lumibot.entities import Asset
config = {
"SESSION_FILE": "<private-directory>/session.json",
"STATE_FILE": "<private-directory>/broker.sqlite",
"AGENT_ID": "strategy-wallet",
"WALLET_ADDRESS": "<dedicated-managed-wallet-address>",
"NETWORK": "testnet",
"MODE": "perp",
}
broker = MetaMask(config)
quote_asset = Asset("USDC", asset_type="crypto")
Pass broker and quote_asset to your normal LumiBot strategy. Use
self.create_order() and self.submit_order() for perpetual orders. The
asset type is crypto_future, the quantity is base units and multiplier is 1.
Leverage defaults to 1 and remains bounded by the reviewed binding.
Headless authentication can use explicit PROJECT_ID and ACCESS_TOKEN.
Automatic refresh requires a durable SESSION_FILE. Rotation is locked and
saved before reuse; an uncertain refresh requires reconnect instead of retrying
a potentially consumed token. Keep credentials outside strategy source.
Perpetual execution¶
The runnable example is lumibot/example_strategies/metamask_perpetual.py.
Select TRADING_BROKER=metamask, METAMASK_NETWORK=testnet and
METAMASK_MODE=perp with an existing authorized session and journal:
python -m lumibot.example_strategies.metamask_perpetual
MetaMaskPerpetualRoundTrip uses normal Strategy order, price, position and
cash methods with continuous Trader scheduling. It buys 0.005 ETH at 1x and
closes actual executed quantity through a reduce-only order on a later iteration.
Check current price, minimum notional and lot precision before running. A
rejected or zero-fill entry does not count as a successful round trip.
The same strategy name and parameters resume the journaled cycle without a new entry. A different name intentionally starts another cycle. The example keeps checking late fills and positions after reaching flat. Unknown submission outcomes hold execution; a rejected close requires reconciliation. Older native canceled records recover missing no-release provenance only from intact persisted checkpoints. Missing or conflicting history remains unknown; reconciliation and fee holds stay in force.
Use a dedicated managed wallet, one durable journal owner and a reviewed grant.
The launcher checks venue open orders because journal-backed get_orders()
cannot discover foreign or manual orders. Grant expiry and remaining daily
capacity must cover entry and closing legs. get_cash() is broker-reported USDC cash,
not remaining policy budget. Startup never renews authority. Stop and join
Trader before calling broker.close() to release workers and the native client.
The native candidate supports Hyperliquid’s default USDC perpetual DEX with
market and limit buy/sell orders. reduce_only=True survives shared closing
methods and restored snapshots. Legacy custom_params={"reduce_only": True}
cannot turn off canonical reduce-only intent. Limit orders require gtc,
ioc or alo. Market orders become frozen slippage-bounded IOC limits.
Conditional, bracket, OCO and automatic cancel/replace orders are unsupported.
Duplicate IDs reuse the same journaled operation. A different request under an existing ID is rejected. Uncertain mutations keep their original request IDs and block new execution until reconciliation. Pending signatures are never replayed after restart. Cancellation has a separate lifecycle and cannot erase fills or reject the original live order merely because cancellation failed.
Perpetual receipt fees populate cumulative Order.trade_cost in USDC,
including maker rebates. Partial-fill trade-log rows contain the cumulative cost
observed at that time, not separate fee deltas to sum. Restored orders keep costs
without replaying fills. Fee-only refreshes update the order without a new fill
callback. Unsupported currencies stay in raw receipts with an unavailable
standard cost. Account cash already includes fees and is not debited again.
Standard account cash uses actual withdrawable funds and margin. Unified accounts use pooled HyperCore spot USDC once, without adding perpetual PnL again. Portfolio margin is unsupported. HIP3 writes are held until native collateral-aware valuation and effective DEX fee inputs are qualified.
MetaMaskData provides actual perpetual marks and closed minute/hour/day
candles from the selected network. Public perpetual data needs only an explicit
NETWORK. The venue retains at most 5,000 bars per interval. Spot candles
and historical account equity are not provided.
Uppercase LumiBot asset symbols resolve to unique native venue names, including
kPEPE. Journaled orders retain that name and case-only retries keep their
original identity. Ambiguous names are refused.
Cash activity and history coverage¶
broker.get_cash_event_sync(since=aware_datetime, limit=5000) reads funding
and non-funding ledgers for the verified managed wallet. Its default is the last
60 days, not all-time history. Receipts identify network, wallet, mode and exact
UTC window, with an inclusive start and exclusive end. Pagination preserves
same-millisecond boundary rows and refuses conflicting evidence or stalled
pages. More than 100,000 distinct records requires a smaller window. Stable IDs
include network, wallet, ledger and transaction leg.
Qualified events are signed default-DEX USDC funding, deposits, zero-fee withdrawals and zero-fee USDC account/subaccount transfers with an unambiguous selected-wallet leg. Funding is operating activity; qualified capital transfers are external to this broker portfolio. History collection never changes cash.
Unknown/malformed types, fee-bearing capital movements, non-USDC assets, HIP3
funding, spot transfers and spot/perp account-class transfers keep history
partial. Historical account-mode changes and capital net/gross fee semantics
need separate qualification. Known events remain available without certified
coverage. Limits also make results partial. Provider/identity failures and
unexhausted pagination return unavailable. Onchain spot history is
unsupported. A successful empty read certifies only its checked window.
Normal Strategy cloud collection reads the full requested window without an
event-count cap, then delivers existing 50-event receipt batches. The receiver
must persist every batch before accepting coverage. A seven-day window with
168 hourly funding events uses four batches. Initial history is marked loaded
only after a complete read. Provider pagination bounds and unresolved
classifications still prevent certified coverage. The list-only get_cash_events() raises
CASH_HISTORY_INCOMPLETE for incomplete results. Raw non-funding records
remain readable through client.cash_history(start_ms, end_ms), whose bounds
are inclusive. Reporting does not qualify funded execution.
Upgrading legacy wallet registries¶
Duplicate chain/contract aliases and assets on unapproved token chains remain invalid for new orders, owner authorization and token valuation. Existing perpetual orders can still be reconciled and canceled exactly. Cancellation retains wallet, project, network, provider-policy and matching-live-order checks. Recovery neither rewrites the binding nor releases an entry order.
Testnet and mainnet¶
Choose the network explicitly and preserve separate network bindings and
journals. Startup does not turn testnet authority into mainnet authority.
Market inventories and asset IDs differ, so metadata is resolved on the chosen
network. Perpetual signing uses EIP-712 chain 1337 on both networks, with
source a for mainnet and b for testnet. These are distinct from HyperEVM
chain IDs. See the official signing source.
The adapter validates supported account valuation before reserving a fresh execution and after approval before releasing leverage or order actions. Portfolio margin, unknown modes and unreadable account state block new execution. Cancellation and original-order reconciliation remain available.
Perpetual position inventory covers the default USDC DEX. Unified accounts can share collateral across DEXs, so this does not establish wallet-wide flatness. Use a dedicated managed wallet without manual positions or orders on other DEXs. Cross-DEX inventory and collateral require separate qualification. See account modes and margining.
Fees, funding, liquidity and liquidation depend on actual venue state. A grant or leverage setting is not a maximum-loss guarantee. Venue minimum-notional errors remain explicit rejections; the adapter does not enlarge an order or apply an unverified minimum to reduce-only cleanup. See venue errors.
REST limits are shared across the public IP. Respect the documented request weights across all strategies. There is no global weighted rate scheduler. Read errors are explicit; uncertain writes retain their original identity and are never automatically retransmitted. Research and public metadata reads do not establish funded mainnet execution.
Same-chain swaps¶
MODE="spot" exposes exact-input broker.swap() and
broker.get_swap(identifier). It does not turn an input amount into a claimed
exact-output buy. Assets require explicit chain_id, token_address and
decimals. Register both assets and the native gas asset in the reviewed
binding. Configure CHAIN_RPC_URLS. Explicit per-chain GAS_LIMITS set the
owner ceiling even when the provider estimates less gas; estimates above the
ceiling are rejected. Without that configuration, the quoted gas limit is
retained. A quote without either limit is rejected.
Register each chain/contract once, including token aliases, with one consistent
decimal declaration. Every registered asset must belong to an approved chain.
Native price identities depend on the chain: ETH uses slip44:60, POL
slip44:966, BNB slip44:714 and Avalanche C-Chain AVAX slip44:9005.
The native price registry covers Ethereum, Optimism, BNB Chain, Polygon,
zkSync Era, Base, Arbitrum, Avalanche and Linea, plus explicitly listed testnet
identities. Unknown native identities refuse valuation. Known identities still
require actual provider prices and do not establish funded chain qualification.
Listed testnets use registry identity slip44:1, independently of the parent
mainnet coin type; missing test-token prices still fail explicitly.
The native implementation verifies quote identity, fee-net source amount, slippage, bounded allowances, sequential simulation and durable managed transaction requests. MetaMask signs and broadcasts; Python never rebroadcasts the signed transaction. Completion requires matching mined transaction identity, nonce, bounded gas, RPC-finalized canonical receipt and actual net ERC20 output transfers. Quote estimates are not fill receipts.
After required allowances reach finality, the client journals a fresh quote for the unsubmitted trade. The original exact input, minimum output, authority and total fee reservation remain binding. New allowances, weaker output or higher fees stop execution for owner review. Original approval records remain intact; an already submitted trade resumes by its original request ID after restart.
Prerequisite allowances use the reviewed grant’s expiry rather than the trade quote’s short lifetime. Each new allowance still requires unchanged authority, current Guard policy, frozen transaction/gas limits and the original total fee reservation. Zero-reset and exact-input approvals can therefore settle before the trade is requoted. Restart never releases an unsubmitted remaining allowance; already submitted requests reconcile their original IDs.
The configured RPC must support eth_getBlockByNumber("finalized", false).
One later block does not establish finality. Pending finality retains submitted
state; unsupported finality or conflicting block identity holds reconciliation.
Old filled records without finality provenance are rechecked read-only, retaining
recorded quantities, fees and spending history. Missing evidence cannot release
a new trade or replay the old swap. This is the selected chain/RPC’s finality
contract, not a bridge withdrawal guarantee. See
Ethereum block tags.
Fees may use the exact source or destination asset. Source fees count toward exact input; destination fees are already reflected in quoted net output. Conflicting fee token identities are rejected. Minimum output rounds down only to the output token’s atomic unit; any lower whole-unit minimum is rejected. Completion verifies actual net receipt transfers.
Testnet swap routes, native output without qualified trace proof, gasless or delegated routes, bridges and fees in a third asset are unsupported and refused before execution. Spot account valuation covers the approved registry using real provider USD prices. Missing prices fail explicitly; no test-token peg or synthetic cash balance is invented. Native mainnet swaps remain unqualified.
Migration and recovery¶
Preserve the old complete broker.sqlite and use it as STATE_FILE with
the exact original agent, wallet and network. Stop the retired service through
its runtime owner before migration. Never copy an active database or run
independent journal copies for one wallet.
An explicitly selected LEGACY_SESSION_FILE can import the old session into
a distinct new SESSION_FILE. Its old owner fence remains held during native
use. The original file is retained; subsequent OAuth rotations belong to the
native session. Do not restart the old service with stale credentials.
BROKER_URL and BROKER_TOKEN are retired and raise migration guidance.
The former agent-scoped token is not a MetaMask access token. Known legacy
venue orders retain order/fill recovery. Old unused signatures are never
released. Expired uncertain native leverage is resolved by verified venue reads without
replaying the unsubmitted order. Legacy swaps without sufficient native
transaction evidence remain explicit reconciliation holds.
client.owner_operations() exposes retained policy, gas-funding and
collateral-transfer receipts. These operations are never automatically replayed.
Funding and provider-policy changes belong in MetaMask’s owner surfaces; the
old local funding UI is historical, not a Python runtime prerequisite.
Trust boundary and qualification¶
Funded testnet and installed-wheel results below were recorded before this council review. They have not been rerun for the identity, allowance, fee and cash-history changes. Fresh authenticated and funded qualification remains open.
All three repository qualification harnesses require a fresh evidence path.
They reject existing receipts, symlinks and configuration/session/journal paths,
including recovery sidecars and locks. Evidence is reserved exclusively and
saved as private atomic snapshots. Run native qualification as
python -m scripts.qualify_metamask_native from the repository root after
separate authorization for its funded testnet actions. It requires at least
$75 of remaining rolling reservation room before signing for its resting-order
test, entry and close under the existing $25 per-order cap. Reviewed authority
checks require at least six minutes of remaining grant lifetime. No limits are
raised and prior spending history is preserved.
During failure recovery, receipt-write errors do not block worker settlement, owned-order reconciliation or authorized exact residual cleanup. Reporting is best-effort in that lane and qualification remains unsuccessful. Journal writes, live ownership checks and financial guards stay mandatory; unresolved evidence never authorizes a guessed close. Legacy migration fences and rollback journals are also protected evidence destinations.
Keys stay with MetaMask. Local Python checks are cooperative process controls; strategy code can access its process credentials. Dedicated funding and provider-enforced Guard policy are the actual boundaries. MetaMask’s outflow policy does not make a local notional limit a provider-enforced cap on typed-data signatures.
Native offline regression tests and connected Python wallet, policy, account,
market-data and ordinary strategy-startup checks have passed. Native testnet
opening, reduce-only closing and cancellation have funded receipts. Fresh live
partial-flow remains unqualified. Actual short-lived testnet grants have expired
on both dedicated wallets: new intents returned REVOKED without signing or
changing orders, execution effects or nonces. Active grants still skip the
ordinary connected expiry check. Managed swaps require separate funded proof.
Old JavaScript receipts do not qualify the new path. No production or mainnet
trading qualification is claimed.
The explicit scripts/qualify_metamask_partial.py testnet harness validates
live remaining size against frontendOpenOrders and the persisted native
client order identity. Paired fills, fees, callbacks and exact cleanup remain
required. --daily-caps MAKER TAKER validates separately reviewed existing
grants without changing authority or spending history. Defaults remain 300/150;
each wallet needs $50 reservation room before signing to cover entry and
residual cleanup within the $25 order limit.
Broker reconciliation and qualification require order-status evidence to match
the persisted cloid. Live
frontendOpenOrders records match by oid and may omit cloid; when
supplied, it must agree. Remaining-size and fill checks remain mandatory.
Environment configuration uses TRADING_BROKER=metamask, optional
DATA_SOURCE=metamask, METAMASK_SESSION_FILE, METAMASK_STATE_FILE,
METAMASK_AGENT_ID, METAMASK_PROJECT_ID, METAMASK_ACCESS_TOKEN,
METAMASK_REFRESH_TOKEN, METAMASK_WALLET_ADDRESS, METAMASK_NETWORK and
METAMASK_MODE.
Selecting both TRADING_BROKER=metamask and DATA_SOURCE=metamask shares one
native client, session and durable journal owner in eager and lazy startup.
Selecting only DATA_SOURCE=metamask creates an independent data client;
public perpetual prices and candles require only METAMASK_NETWORK. Close
data_source.client after data-only use. For trading, stop and join Trader,
then close the broker to release its shared client.
Execution and dependency review¶
An IOC order can report venue status filled after executing only part of its
requested quantity. When the original intent, persisted wire action, venue time
in force and exact fills prove this case, LumiBot records the actual execution
and cancels the unfilled remainder. The raw venue status remains available for
audit. A status label or remaining size alone cannot establish a fill;
incomplete or contradictory evidence stays held for reconciliation.
A real testnet IOC partial execution has been recovered through the corrected broker with exact fills and fees, followed by an exact reduce-only close and flat-account verification. This proves that recovery path. Controlled maker partial-cancellation qualification remains inconclusive, and no production readiness is claimed.
Managed Hyperliquid signing uses domain chain ID 1337 on both networks; the signed source binds testnet or mainnet. Bridge chain IDs must not replace the signing domain. Provider validation and Shield failures remain rejected without automatic retry or venue submission. Guard Mode remains enabled.
Owner revocation is checked after remote preparation and serialized with final
handoff. An expired uncertain cancel can retry only after fresh reads confirm
the same order remains live. Expired uncertain leverage reconciles current
venue settings and rejects the unsubmitted intent; a fresh order ID is needed.
Accessor refresh and polling share cumulative fill, callback and terminal-event
handling. Live partial remainders use identity-checked open-order snapshots;
orderStatus may retain the original size. Closed order refresh is read-only,
preserves lifecycle, and emits only new fill deltas. Inconsistent execution
evidence blocks new reservations until reconciliation succeeds.
Polling defaults to 10 seconds and shares fill/live-order reads within a wallet
sweep. Increase POLL_INTERVAL for large histories or multiple brokers sharing
an IP; Hyperliquid limits aggregate weighted requests per IP. Unified-account
cash is unheld USDC collateral, without promising order capacity or valuing
unrelated spot assets.
Atomic quantities remain exact under caller decimal contexts.
Managed swaps cannot be canceled locally. Receipt reconciliation includes gas
spent by reverted transactions and earlier approvals. OP Stack estimates and
actual fees include separate L1-data and operator charges. The execution-gas
ceiling is distinct from estimated rollup charges, which cannot be capped by
the transaction signer. Actual overruns preserve fills and block further spend.
After reviewing the exact recorded overrun, explicitly call
client.acknowledge_fee_overrun(operation_id, expected_overrun). This retains
the adjusted daily charge. Legacy overruns without verified USD valuation stay
held.
Use a clean environment or remove retired polygon-api-client before
upgrading. Its certificate constraint prevents current CA-store fixes. The
maintained Massive SDK preserves existing POLYGON_API_KEY configuration and
Polygon endpoint behavior. The MetaMask extra requires patched urllib3 and
certifi. Private state directories and owner-only regular session locks
remain mandatory. This is not a claim that the entire optional dependency tree
has no advisories.
New managed requests match MetaMask’s high-level wallet-adapter provider origin, while readable intent and durable client provenance identify LumiBot. Recovery validates the originally recorded origin, without alternate-origin retries. Guard Mode and exact policy checks stay enabled.
Actual native testnet ALO placement/cancellation and market opening/reduce-only closing have passed on two dedicated wallets. A real Strategy/Trader ETH round trip delivered unique callbacks and reconciled ending cash exactly, including fees. The installed wheel passed native regression and connected-history tests on Python 3.10 and 3.12 without JavaScript runtimes in PATH; connected checks also denied child processes. That earlier wheel recovered an actual canceled-partial receipt with matching venue fills and fees and no replayed callbacks. Fresh live partial-flow attempts remain inconclusive. This is not production or mainnet-swap qualification. Earlier JavaScript receipts cannot qualify this implementation.
Local cancellation and release evidence¶
Local cancellation needs positive persisted native evidence that the order was
not released. Such orders expose confirmed_not_submitted to generic tools,
with an incomplete, non-retryable submission outcome. Earlier signing and
leverage effects remain in the audit history. Missing legacy evidence remains
unknown and cannot be cleared by local cancellation. A historical canceled label
alone is not acceptance proof; operator reconciliation is required, and this
projection does not recreate a journal hold already lost in the past. Known
venue identities and actual fills remain authoritative.
Cancellation signing and pending-signature release require a matching live venue observation without a reconciliation error. An unresolved or contradictory observation holds the cancellation as well as the entry. If an explicit local cancellation retry later obtains valid no-release proof and settled leverage evidence, it clears the resolved reconciliation hold while retaining prior effects and fee-review flags.
Frequently asked questions¶
Do I need Node or a local MetaMask service?¶
No. Install lumibot[metamask] and configure the native session, wallet and
journal. Managed signing and venue requests run through Python.
Who holds the wallet keys and enforces spending limits?¶
MetaMask retains wallet keys. Guard Mode enforces its reviewed provider policy; local notional limits are cooperative process controls. Use a dedicated wallet with bounded funding, and keep Guard Mode enabled.
Can I preserve the previous integration’s journal?¶
Yes. Retain the exact state file, agent and wallet identity. Known venue orders can reconcile; ambiguous legacy effects remain explicit holds. Old service tokens are not MetaMask access tokens, and startup never renews authority.
What should I do after an approval timeout or unknown outcome?¶
Inspect order.submission_outcome: broker_state_certainty distinguishes
confirmed_submitted, confirmed_rejected, confirmed_not_submitted for
proven pre-release cancellation, and unknown. reconciliation_required
marks unresolved or conflicting evidence. Agent
submission tools preserve this state and return incomplete, non-retryable results
while uncertainty remains. An acknowledgement is not a fill.
Inspect the recorded operation with broker.client.get_order(operation_id).
Reuse that operation’s identity and reconcile the original request before
creating another trade. Do not bypass Guard Mode or increase permissions to clear
a failure.
Does testnet qualification establish production swap readiness?¶
No. Native perps have funded testnet evidence, with the remaining qualification limits recorded above. Mainnet trading and funded native swaps remain unqualified; earlier JavaScript receipts do not establish Python readiness.