felix-mcp

Felix MCP

Non-custodial trading tools for AI agents across Hyperliquid, Polymarket, and Derive. Live execution is the default; paper mode must be selected explicitly.

Install

Let the AI agent run one guided command. It registers the local custody identity, creates an encrypted backup, pins the same reviewed package in Claude Code, and verifies the result:

npx -y --package felix-mcp@2.0.110 felix-keys onboard --accept-terms --client claude

Requires Node.js 20.10 or newer. The command checks the active runtime before writing any credential. If it is too old, it stops with the detected version and leaves local state unchanged.

After the user reviews the linked terms, the AI may run the complete onboarding flow. The owner key, launcher key, and a generated high-entropy backup recovery code are stored directly in macOS Keychain and are never printed or returned to the MCP client. The encrypted backup is created and authenticated automatically.

Restart or reconnect the MCP after onboarding, then call get_status and confirm the client is compatible. Call get_custody_recovery_status and require ready: true before funding; no credential or recovery material is returned.

Claude Code requires one human action: open /permissions and allow the mcp__felix tool namespace. Felix cannot grant that permission itself.

For Claude Desktop:

{
  "mcpServers": {
    "felix": {
      "command": "npx",
      "args": ["-y", "felix-mcp@2.0.110"]
    }
  }
}

Never put an API key, owner key, seed phrase, signature, or signed transaction in a prompt, tool argument, URL, source file, log, or committed configuration.

Create an account

Read felix://getting-started, review https://felix.trade/legal, then call:

create_account(
  accept_terms=true,
  legal_version="2026-08-30",
  idempotency_key="primary-live-account"
)

Account creation is funded-first:

• The first call reserves an isolated account and returns its Polygon deposit address. No wallet is deployed and no chain gas is spent.
• Send at least the returned minimum, currently $5, using one of the exact accepted stablecoins in the response.
• After confirmation, retry create_account with the same idempotency key.
• Felix verifies the owner-controlled account, enables supported venues, stores the least-privilege child credential locally, and activates it.

Activation normally takes 60-120 seconds but can take longer when a venue is settling. Keep the call open. If it is interrupted, retry the exact same request and idempotency key. Do not create a replacement account.

Then verify and trade:

get_status()
get_money_map()
search_markets(q="bitcoin")
preview_order(instrument="crypto:BTC", side="long", size_usd=25, auto_fund=true)
place_order(instrument="crypto:BTC", side="long", size_usd=25, auto_fund=true)
get_situation()

Paper is optional and explicit:

derive_api_key(paper=true, accept_terms=true, legal_version="2026-08-30")

Custody

• The root owner key is created and retained in the local OS credential store.
• Felix receives public addresses and signatures, never the owner private key.
• Each child account has a distinct owner-controlled policy wallet.
• Interactive owner actions are prepared by Felix, verified locally, and signed on the user's device.
• Background agents use venue-scoped execution authority. That authority is limited by the owner-approved mandate and cannot withdraw user funds.
• verify_custody reads the wallet owner, threshold, enabled policy, bindings, ceilings, expiry, and spend state from the chain.

Felix is non-custodial, but non-custodial does not mean risk-free. Venue, contract, wallet, dependency, cloud, strategy, market, and user-device failures can still cause loss. Read the Risk and Custody disclosures before funding.

Back up the owner

Guided onboarding creates and authenticates the encrypted recovery file in the standard local documents folder automatically. The agent does not copy a key, choose a password, or ask the user to run another terminal command. Verify it with get_custody_recovery_status; require ready: true before funding.

The recovery code remains in macOS Keychain and never enters model context. Owner-controlled off-device recovery is optional and separate from normal onboarding. Felix cannot recover a lost owner key and will not replace an existing identity silently.

Account binding and keys

create_account switches the MCP session to that child account. The selected child and credential are stored locally and scoped to the calling client session. A new client process begins on the launcher identity and must select a child explicitly.

If the saved account and credential do not match, tools fail with session_binding_recovery_required; they do not silently show a different account. Use list_accounts and use_child_account to select the intended child. Use reload_launcher_key only when you intentionally want the launcher identity in that process. It rereads the current macOS Keychain identity, authenticates that owner's encrypted money-workflow journal, and changes the session only after both checks pass.

Money-workflow journals are encrypted and isolated per owner identity. Existing pre-2.0.108 journals migrate only after their authentication tag verifies. If a tool returns operation_state_unavailable, preserve the journal and restore the matching owner backup; never delete local workflow state or retry an unresolved money action with a new idempotency key.

Scopes are least-privilege:

• read: account and market data.
• trade: orders and agent execution.
• manage: accounts, keys, policies, funding preparation, and support setup.
• transfer: owner-authorized withdrawals; not granted to ordinary agent keys.

An existing key cannot increase its own scopes or limits. Revoke it and mint a replacement within the account's owner-approved ceiling.

Fixed account ceilings

The account's operation, daily, and lifetime ceilings are selected and signed when the account is created. They cannot be raised in place by an API key, agent, or Felix. update_wallet_policy supports pause, resume, renew, and lockdown, not higher ceilings.

To use higher ceilings, create a new account with the intended limits and move funds through the normal withdrawal and deposit flows. Lower local limits may be configured with:

export FELIX_MAX_LIVE_ORDER_USD=100
export FELIX_MAX_FUND_USD=100
export FELIX_MAX_FEE_SETTLEMENT_USD=100

Order workflow

Use canonical instruments returned by search_markets. Do not guess slugs or symbol formats.

• Call preview_order. It moves no money and reports executability, venue minimums, collateral, leverage, liquidity, fees, funding requirements, and expected duration.
• Correct every constraint_violation before execution.
• Call place_order with the same intent. Use a stable idempotency key when the tool accepts one.
• Verify the fill, position, fee status, and account state with get_situation, get_positions, and get_fills.

auto_fund:true may fund the venue before placing the order. The preview is the authoritative cost and feasibility check. A successful funding leg is never repeated merely because the later order is rejected.

Leverage is never inferred. Hyperliquid notional above fresh free collateral requires explicit allow_leverage:true. Batch orders require one top-level mode. Each live item has independent replay protection; execution stops after the first failure, so a batch is not an atomic exposure basket.

Filled orders return position_id. Use it with close_position. Use cancel_order only for an open resting order.

Money movement and recovery

get_money_map is the canonical money view. It labels scope, completeness, freshness, unavailable sources, reserved balances, and whether the total is partial. Never interpret unavailable as zero.

Use:

• fund_market or start_fund_market: owner wallet to a venue.
• bring_home or start_bring_home: venue back to the owner wallet.
• get_money_operation: inspect an asynchronous money workflow.
• wait_for_operation: wait without repeated polling.
• list_recent_operations: recover locally journaled operations after restart.
• withdraw: move funds to an owner-approved external address.

Cross-chain movement can take several minutes. Prefer the asynchronous tools, persist the returned operation ID, and follow these rules:

• Reuse the original idempotency key after a timeout or unknown result.
• Inspect the existing operation before retrying.
• Never start a second workflow while the original is pending.
• Follow the returned recovery_tool and exact arguments.
• Treat money_moved:null as unknown and reconcile before resuming.
• A pre-submit failure with money_moved:false is safe to retry as directed.

Withdrawal destinations require a local owner signature. There is no activation delay. source:"auto" selects a sufficiently funded policy wallet and then the owner wallet. Withdrawals remain bounded by available balance, destination authorization, replay protection, receipt verification, and local signing.

USDC.e withdrawals deliver bridged USDC.e on Polygon at contract 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174. Many centralized exchanges do not accept that exact token. Unless the exchange explicitly confirms Polygon USDC.e support, withdraw to a self-custody Polygon wallet first and convert to native Polygon USDC before depositing to the exchange.

Venue notes

Hyperliquid

• Live minimums and free collateral come from preview_order.
• Agent leverage is disabled unless explicitly enabled at deployment.
• Bring-home preserves collateral required by unleveraged agent positions.
• Venue withdrawal fees and settlement time are disclosed before execution.

Derive

• Options require an owner-bound venue session.
• Fixed venue fees can make small orders uneconomical even when collateral is sufficient. Use the preview's minimum economical notional.
• Closes and returns may be asynchronous. Reuse the same operation identity.

Polymarket

• Direct orders are signed locally.
• Regional availability rules apply to the MCP host; Felix does not bypass a venue restriction.
• Autonomous agents use a separate venue-scoped execution wallet. Inspect both wallet roles with get_polymarket_wallet and fund the autonomous wallet once with fund_polymarket_agent_wallet before deployment.
• Felix sets the required exchange permissions during setup. Callers never construct approval transactions.
• Resolved agent positions redeem back to the autonomous wallet so its working balance can continue trading.
• Server-monitored exit plans are unavailable. Strategy decisions, explicit closes, or market resolution manage the exit.

Agents and strategies

Read these resources before authoring:

• felix://strategy/ctx-api: complete restricted think(ctx) contract.
• felix://strategy/examples: executable examples.
• felix://operations/recovery: runtime and recovery rules.
• felix://market-data/websocket: real-time market data.

The normal sequence is:

write strategy -> backtest -> inspect validity and costs -> deploy -> monitor

generate_strategy is optional. Strategy authoring does not depend on a model quota. Hand-written code can go directly to backtest and deploy_agent.

Backtesting never deploys an agent or moves money. Results identify data source, methodology, cost assumptions, and historical validity. A degraded result is not evidence of live performance.

deploy_agent requires an explicit budget and one to four authorized markets. Paper mode must be explicit. Use get_situation, agent_status, get_agent_log, and wait_for_events to operate the fleet. Stop an agent before changing it with update_agent; review current positions before resuming. Stopping an agent does not close positions.

Stop loss, take profit, trailing stop, break-even, and maximum-hold rules are optional. Where supported, they are server-monitored reduce-only market exits, not guaranteed-price venue orders. Gaps, outages, and unavailable liquidity can delay execution or add slippage.

Market-data WebSocket

The authenticated WebSocket streams quotes, books, and trades. Create a one-time ticket with /v1/stream/tickets, authenticate within five seconds, and subscribe only with canonical instruments returned by search_markets.

Treat sequence gaps, reconnects, and resync_required as instructions to fetch a fresh snapshot before making a stateful decision. Orders still use the normal preview and idempotent execution tools. See felix://market-data/websocket for the complete protocol.

Fees and small accounts

preview_order is the authoritative all-in cost view. Cross-chain fixed costs and venue minimums can dominate small accounts. Do not infer economics from a different instrument or venue.

Polymarket and Derive live execution fees use prepaid fee credit. Read it with get_fee_balance, preview with preview_fee_top_up, and fund it with top_up_fee_balance. The fee is reserved before submission, captured only after a confirmed fill, and released after a confirmed no-fill. Withdrawals do not collect trading fees and Felix does not create fee debt.

upgrade_subscription(plan="pro", idempotency_key="...") prepares an exact owner-signed 30-day Pro payment. Auto-renew is off; every renewal requires a new owner-authorized workflow.

Emergency actions

• update_wallet_policy(action="lockdown"): owner-controlled account stop.
• panic(confirm=true): blocks new exposure, attempts to cancel and flatten, and revokes active account API keys.
• archive_account: locks and archives only a completely flat child account.

Emergency actions are idempotent and fail closed. Verify positions and money state after every emergency workflow.

Support

Agents can use create_support_ticket, reply_support_ticket, list_support_tickets, get_support_ticket, and close_support_ticket. Include request IDs, operation IDs, tool names, position/agent IDs, client version, and error code. Never include credentials or raw signatures.

Support writes are account-scoped, rate-limited, and idempotent. Retry an interrupted message with the same key.

Tool map

• Markets: search_markets, get_quote, get_orderbook, get_option_chain, get_funding, research and screening tools.
• Trading: preview_order, place_order, place_batch_orders, cancel_order, close_position, exit-plan tools, make_market.
• Portfolio: get_situation, get_positions, get_fills, get_pnl, get_money_map, verify_custody.
• Money: funding, bring-home, fee-credit, withdrawal, and venue onboarding tools.
• Agents: strategy guide, backtest, deploy, status, logs, events, update, stop.
• Account: keys, children, policy, webhooks, subscription, support, and archive.

Tool schemas are authoritative for required arguments, bounds, and enums.

Examples

Create my Felix account with idempotency key "my-primary-account". After it
returns a deposit address, stop and show me the accepted token and minimum.

Find a liquid Bitcoin market, preview a $25 order with auto-funding, explain the
all-in cost and constraints, and place it only if the preview is executable.

Read felix://strategy/examples, write a BTC strategy, backtest it, and show me
the validity and cost assumptions before asking whether to deploy it live.

Full integration guide: https://felix.trade/docs

Not financial advice.