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.

Connect your AI assistant

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.