Fair AI Connect

Returns the open and recently-completed orders for the authorized account. The full order book — submit/execute time, side, quantity, price, status — for context before preparing a new order. The per-row `price` is the per-unit order price in minor units. CURRENCY & UNITS — per-unit PRICE fields (buyPrice, sellPrice, and an order/holding `price`) are quoted in MINOR units: agorot for a regular shekel-denominated fund (1 ₪ = 100 agorot), or US cents for a dollar-denominated fund (`isDollarUnits: true`; 1 $ = 100 ¢). To get the real per-unit price in the fund's own currency, divide the price by its `factor` (the currency factor — 100 in the agorot/cents case): e.g. buyPrice 22900 ÷ factor 100 = 229.00 (₪229.00, or $229.00 when isDollarUnits is true). Monetary TOTALS — marketValue, cost, value, amount, gainLoss, availableCash, availableCashForInvestment, totalValue, cashBalance — are ALREADY in whole shekels (₪); never divide those by factor. These rows do not include `factor` / `isDollarUnits`. If you need a row's per-unit `price` in real currency, look the fund up by its fundID with resolve_fund_ids or get_fund — both return `factor` and `isDollarUnits`.

get_open_orders

Returns the status of a pending or completed prepare-* operation by its operationId. Every response carries a `reason` string explaining the status and what to do next — follow it. Statuses: • `pending` — the account holder has not yet confirmed on their phone. Poll again after a short delay. • `approved` — the holder confirmed on their registered device and the Fair app is now submitting the operation to the trading system. NOT final — keep polling until `sent` or `failed`. Do not tell the user the order was placed yet. • `sent` — the trading system ACCEPTED the operation and created an order; the order number is in `result.fmrOrderId` / `result.asmachta`. Accepted does NOT mean executed: the order has its own lifecycle (open / partially filled / executed / cancelled). To report execution state, call `get_open_orders` with that order number — if it no longer appears there, it completed or was cancelled; use `get_transactions` to confirm. • `declined` — the holder declined on their device. Do not retry unless the user explicitly asks. • `expired` — the approval window elapsed unanswered. Prepare a new operation if the user still wants it. • `revoked` — the user revoked this AI client's access grant; the operation was cancelled. • `failed` — submission failed; see `executionError`. If `executionError.code` is `USER_ABORTED`, the holder approved but then backed out of the final in-app confirmation — nothing was submitted; do not prepare it again unless the user explicitly asks. • `unknown` — no operation with that id is visible to this token. When status="failed" the response may include `executionError.outcome` with: `disposition` (one of `user_must_reconfirm`, `ask_schedule_for_next_session`, `ask_consent`, `transient`, `fatal`, `fatal_partial_state`, `fatal_user_action_required`), `userPrompt.he` (and sometimes `userPrompt.en`) — the FMR-localized question the user must answer (surface verbatim, do not paraphrase; the Hebrew string carries interpolated amounts, FX rates, and dates), and `retryWith` — the corrective input shape (either `setFlags` to set on a fresh prepare call, or `echoOrderId` to pass as `previousOrderId`).

get_operation_status

Returns a high-level portfolio snapshot for the authorized account: total value, P&L, cash balance, and per-currency exposure. All amounts here are monetary totals already in whole shekels (₪) — no agorot conversion needed. CURRENCY & UNITS — per-unit PRICE fields (buyPrice, sellPrice, and an order/holding `price`) are quoted in MINOR units: agorot for a regular shekel-denominated fund (1 ₪ = 100 agorot), or US cents for a dollar-denominated fund (`isDollarUnits: true`; 1 $ = 100 ¢). To get the real per-unit price in the fund's own currency, divide the price by its `factor` (the currency factor — 100 in the agorot/cents case): e.g. buyPrice 22900 ÷ factor 100 = 229.00 (₪229.00, or $229.00 when isDollarUnits is true). Monetary TOTALS — marketValue, cost, value, amount, gainLoss, availableCash, availableCashForInvestment, totalValue, cashBalance — are ALREADY in whole shekels (₪); never divide those by factor.

get_portfolio_summary

Returns settled transactions for the authorized account. Accepts a date-range filter; omitted dates fall back to the account-svc default window. The `amount` per row is a monetary total already in whole shekels (₪). CURRENCY & UNITS — per-unit PRICE fields (buyPrice, sellPrice, and an order/holding `price`) are quoted in MINOR units: agorot for a regular shekel-denominated fund (1 ₪ = 100 agorot), or US cents for a dollar-denominated fund (`isDollarUnits: true`; 1 $ = 100 ¢). To get the real per-unit price in the fund's own currency, divide the price by its `factor` (the currency factor — 100 in the agorot/cents case): e.g. buyPrice 22900 ÷ factor 100 = 229.00 (₪229.00, or $229.00 when isDollarUnits is true). Monetary TOTALS — marketValue, cost, value, amount, gainLoss, availableCash, availableCashForInvestment, totalValue, cashBalance — are ALREADY in whole shekels (₪); never divide those by factor. These rows do not include `factor` / `isDollarUnits`. If you need a row's per-unit `price` in real currency, look the fund up by its fundID with resolve_fund_ids or get_fund — both return `factor` and `isDollarUnits`.

get_transactions

IMPORTANT — THIS TOOL ONLY PREPARES A DRAFT REQUEST. Calling it does NOT send, place, submit, modify, or cancel anything: nothing reaches the market or the account from this call. The draft does nothing unless the account holder personally reviews and approves it in the Fair mobile app on their own device — the AI cannot send, approve, or execute it, and no parameter, scope, or follow-up call changes that. If the user asks you to SEND, PLACE, SUBMIT, or EXECUTE an order (or transfer/deposit/withdrawal), do NOT present this tool as fulfilling that: tell the user plainly that you cannot send orders — you can only prepare a request that they must approve themselves on their phone. Only call this tool when the user asks to prepare such a request for their own approval. If the user does not approve within 5 minutes the request simply expires and nothing happens. After calling this, never claim the action is done or sent — tell the user to open the Fair app to review and approve. Track the outcome with get_operation_status. Stages a draft buy request for the authorized account, for the account holder to review and approve themselves in the Fair mobile app (see the disclosure above) — the AI never sends or executes it. Call get_holdings / get_margins first to size the draft against available cash, and confirm the instrument via get_fund / search_funds before naming it. Quantity is in units of the security (not shekels) — for a fund priced at ₪100, qty=10 reserves ₪1000 worth. PRE-FLIGHT — call trade_market_status before preparing. It gives you: (1) `market.isOpen` — when the market is closed the order cannot dispatch now; expect the server to prompt for scheduling to the next session (the `isCont` flow below) and tell the user up front, using `market.nextTradingDay`; (2) `consent.hasActiveConsent` — whether an active bank-debit consent exists, useful context when available cash is short and before an `autoDepositApprove` consent prompt appears; (3) `messages` — active platform notices (e.g. a holiday-eve early close) to relay to the user before they approve. WHAT THIS CALL RETURNS: it always returns immediately with `status: "pending"` and an `operationId` — never the outcome. Track the draft by polling `get_operation_status` with that id. Status meanings: `pending` = waiting for the account holder on their phone; `approved` = the holder confirmed and the Fair app is submitting — NOT done yet, keep polling; `sent` = the trading system ACCEPTED the order and created it (order number in `result.fmrOrderId` / `asmachta`) — accepted does not mean executed; check execution via `get_open_orders` with that order number; `failed` / `declined` / `expired` / `revoked` = terminal, nothing was placed (except see `executionError` on failed). SIZING — do NOT compute the quantity or cost yourself. When the user expresses intent in money ("buy ₪1000 worth"), call calculate_order with `sum` to get the exact whole-unit `qty`, then pass that `qty` here as `orderQty`. When the user names units, call calculate_order with `qty` to get the exact `sum` (price + margin + commission) to confirm with them before preparing. calculate_order is the authoritative source for the live price, buy margin, commission, and minimum-quantity (`belowMinQty`) check — your own arithmetic from a per-unit price will be wrong. On the FIRST call: omit `isCont`, `forexApproval`, `autoDepositApprove`, `previousOrderId`. These flags exist only as opt-in responses to a server-issued prompt. If a prior PendingOp on this fund returned `status: "failed"` with an `executionError.outcome.disposition`, follow it: • `"user_must_reconfirm"` — show `userPrompt.he` verbatim. If the user agrees, re-call this tool with the same fields **plus** `previousOrderId: <retryWith.echoOrderId>`. • `"ask_schedule_for_next_session"` — show the Hebrew prompt; if the user agrees, re-call with `isCont: true`. • `"ask_consent"` — show the Hebrew prompt (the FMR-formatted amount / FX rate is in it). If the user consents, re-call with the flag(s) named in `retryWith.setFlags`. • `"transient"` — retry the same inputs in a few minutes; do NOT change any field. • `"fatal"`, `"fatal_partial_state"`, `"fatal_user_action_required"` — surface `userPrompt.he` verbatim and stop; do not auto-retry.

prepare_buy_order

IMPORTANT — THIS TOOL ONLY PREPARES A DRAFT REQUEST. Calling it does NOT send, place, submit, modify, or cancel anything: nothing reaches the market or the account from this call. The draft does nothing unless the account holder personally reviews and approves it in the Fair mobile app on their own device — the AI cannot send, approve, or execute it, and no parameter, scope, or follow-up call changes that. If the user asks you to SEND, PLACE, SUBMIT, or EXECUTE an order (or transfer/deposit/withdrawal), do NOT present this tool as fulfilling that: tell the user plainly that you cannot send orders — you can only prepare a request that they must approve themselves on their phone. Only call this tool when the user asks to prepare such a request for their own approval. If the user does not approve within 5 minutes the request simply expires and nothing happens. After calling this, never claim the action is done or sent — tell the user to open the Fair app to review and approve. Track the outcome with get_operation_status. Stages a draft request to cancel an open order on the authorized account, for the account holder to review and approve themselves in the Fair mobile app (see the disclosure above) — the AI never sends or executes the cancellation. Call get_open_orders first to find the `fmrOrderId` of the order to cancel. PRE-FLIGHT — call trade_market_status for context: `market.isOpen` tells you whether the order could be filling right now (fills only happen during trade hours, so urgency differs), and `messages` may carry notices (e.g. shortened trading day) worth relaying before the user approves the cancellation. Cancellation is best-effort: an order that has already started filling at the exchange may continue to execute even after the cancel request lands. WHAT THIS CALL RETURNS: always an immediate `status: "pending"` + `operationId` — never the outcome. Poll `get_operation_status`: `approved` = the holder confirmed and the app is submitting the cancel (not done yet); `sent` = the trading system accepted the cancel request — confirm the order actually left the book via `get_open_orders`.

prepare_cancel_order

IMPORTANT — THIS TOOL ONLY PREPARES A DRAFT REQUEST. Calling it does NOT send, place, submit, modify, or cancel anything: nothing reaches the market or the account from this call. The draft does nothing unless the account holder personally reviews and approves it in the Fair mobile app on their own device — the AI cannot send, approve, or execute it, and no parameter, scope, or follow-up call changes that. If the user asks you to SEND, PLACE, SUBMIT, or EXECUTE an order (or transfer/deposit/withdrawal), do NOT present this tool as fulfilling that: tell the user plainly that you cannot send orders — you can only prepare a request that they must approve themselves on their phone. Only call this tool when the user asks to prepare such a request for their own approval. If the user does not approve within 5 minutes the request simply expires and nothing happens. After calling this, never claim the action is done or sent — tell the user to open the Fair app to review and approve. Track the outcome with get_operation_status. Stages a draft sell request for the authorized account, for the account holder to review and approve themselves in the Fair mobile app (see the disclosure above) — the AI never sends or executes it. Call get_holdings first to confirm the user owns at least the requested quantity; partial fills are not supported. Quantity is in units of the security (not shekels). Sell proceeds settle into the account cash balance on the upstream settlement schedule. PRE-FLIGHT — call trade_market_status before preparing: if `market.isOpen` is false the order cannot dispatch now (expect the next-session `isCont` prompt; set expectations with `market.nextTradingDay`), and relay any active `messages` (e.g. a holiday-eve early close) to the user before they approve. WHAT THIS CALL RETURNS: always an immediate `status: "pending"` + `operationId` — never the outcome. Poll `get_operation_status`; status meanings are identical to `prepare_buy_order` (`approved` = still submitting, `sent` = accepted by the trading system but not necessarily executed — verify via `get_open_orders` with `result.fmrOrderId`). SIZING — do NOT compute the quantity or proceeds yourself. When the user expresses intent in money ("sell ₪1000 worth"), call calculate_order with `orderAction: "Sell"` and `sum` to get the exact whole-unit `qty`, then pass it here as `orderQty`. When the user names units, call calculate_order with `qty` to quote the exact `sum` (proceeds net of commission) to confirm with them. calculate_order is the authoritative source for the live sell price and commission; do not estimate from a per-unit price. On the FIRST call: omit `isCont`, `forexApproval`, `autoDepositApprove`, `previousOrderId`. These flags exist only as opt-in responses to a server-issued prompt. `autoDepositApprove` in particular is rarely relevant on a sell. Disposition handling is identical to `prepare_buy_order` — see that tool for the disposition table.

prepare_sell_order

Batch id → name resolver. Pass a list of numeric fund ids; returns one record per fund with fundID, fundName, fundEnglishName, isHedgeFund, plus the currency fields (`factor`, `isDollarUnits`, `rate`, `buyPrice`). Use this when you already have a numeric id (e.g. from get_holdings or get_open_orders) and need the human-readable name OR the `factor` needed to read a per-unit price correctly. For discovery (the user said a category or theme, not a number), use search_funds. CURRENCY & UNITS — per-unit PRICE fields (buyPrice, sellPrice, and an order/holding `price`) are quoted in MINOR units: agorot for a regular shekel-denominated fund (1 ₪ = 100 agorot), or US cents for a dollar-denominated fund (`isDollarUnits: true`; 1 $ = 100 ¢). To get the real per-unit price in the fund's own currency, divide the price by its `factor` (the currency factor — 100 in the agorot/cents case): e.g. buyPrice 22900 ÷ factor 100 = 229.00 (₪229.00, or $229.00 when isDollarUnits is true). Monetary TOTALS — marketValue, cost, value, amount, gainLoss, availableCash, availableCashForInvestment, totalValue, cashBalance — are ALREADY in whole shekels (₪); never divide those by factor.

resolve_fund_ids

Filterable fund screener. Returns a slim projection of matching funds plus the total matching count. Filter keys (categories / managers / fundType / taxStatus / tags) are the raw upstream `key` strings — usually numeric ids. Always call `get_fund_filters` first to learn the allowed keys and their Hebrew/English labels; never invent values. For example, the user saying "show me ksm money-market funds" maps to `{ managers: ["17"], categories: ["7"] }` only after you read those keys from `get_fund_filters`. Free-text search (`text`) takes precedence and runs an Elasticsearch full-text query over the fund name; when set, other taxonomy filters are ignored upstream and `totalMatching` equals `funds.length`. Results are a neutral factual match set, not a recommendation or ranking. Always read `disclaimer` and `ordering` from the response: tell the user how the list is ordered, do not re-sort it yourself, and if they want a different order offer to re-run the search with a `sort` of their choosing. CURRENCY & UNITS — per-unit PRICE fields (buyPrice, sellPrice, and an order/holding `price`) are quoted in MINOR units: agorot for a regular shekel-denominated fund (1 ₪ = 100 agorot), or US cents for a dollar-denominated fund (`isDollarUnits: true`; 1 $ = 100 ¢). To get the real per-unit price in the fund's own currency, divide the price by its `factor` (the currency factor — 100 in the agorot/cents case): e.g. buyPrice 22900 ÷ factor 100 = 229.00 (₪229.00, or $229.00 when isDollarUnits is true). Monetary TOTALS — marketValue, cost, value, amount, gainLoss, availableCash, availableCashForInvestment, totalValue, cashBalance — are ALREADY in whole shekels (₪); never divide those by factor.

search_funds

Returns pre-trade context for the authorized account in one call: (1) `consent` — whether the user currently holds an ACTIVE consent to debit their bank account (`hasActiveConsent`), its status and min/max debit sums; (2) `market` — whether the market is open for trading right now (`isOpen`, per the trading calendar and hours Fair operates on), and `nextTradingDay` when closed; (3) `messages` — active special notices from Fair (e.g. holiday-eve early close), usually in Hebrew — relay them to the user, do not act on them. A null `consent` or `market` section means that status could not be determined right now — say it is unknown; never present null as "no consent" or "market closed". Call this before discussing deposits or order timing instead of guessing from the clock, and as a pre-flight before any prepare_* draft — it tells you whether the draft can dispatch now or will wait for the next session, and which notices to relay before the user approves.

trade_market_status

Echoes the identity, AI-client, grant, and granted scopes the trade-mcp-svc resolved from the bearer token. Use this to verify connectivity.

whoami