KYROX
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
KYROX (kyrox-mcp)
Status: v0.1 Active Development (VERIFIED: Python 3.13 environment, FastMCP server, hello_kyrox, get_stock_info, list_stocks, centralized error handling, redacted JSONL audit logging, standalone transaction safety policy module tools/policy.py & STDIO protocol framing; IN PROGRESS: get_wallet_balances, get_portfolio, prepare_transaction & simulate_transaction — code & 394 offline/MCP/mock-provider tests verified, awaiting live Base Sepolia MockStock.sol deployment)
Target Network: Base Sepolia Testnet (chainId: 84532) · Labelled Mock Token Fixtures (mock)
Runtime Stack: Python 3.11+ (3.13 x64 baseline) · MCP Python SDK v1 (FastMCP, mcp[cli]>=1.28,<2) · web3.py (web3>=8.0,<9)
License: Apache-2.0
1. What KYROX Is
KYROX (kyrox-mcp) is an open-source, non-custodial Model Context Protocol (MCP) server for AI agents working with tokenized stocks on Base. It is designed to give an AI client structured tools to read tokenized-stock metadata and wallet balances, prepare an unsigned transaction intent (signed: false), and run pre-execution simulation and policy checks—while leaving transaction review and cryptographic signing strictly to the human user in their own external wallet.
Related MCP server: WETH
2. The Problem KYROX Solves
As tokenized equities and real-world assets move on-chain, users want AI agents to help inspect instruments, analyze portfolio exposure, and draft transactions. However, connecting an LLM agent to on-chain financial workflows introduces three major failure modes:
Custody & Key-Exposure Risk: Giving an AI agent raw private keys or autonomous signing authority creates an unacceptable risk of prompt injection, hallucinated parameters, or unauthorized fund movement.
Unverified Reference Data: Agents frequently confuse mock fixtures, stale off-hours reference values, or total-return trackers with live executable share prices, or falsely assume a
1:1token-to-share ratio without checking contract decimals and corporate-action multipliers.Unchecked Transaction Construction: Without deterministic server-side validation, an agent can target the wrong chain ID, interact with an unverified contract address, or suffer floating-point rounding errors when converting human-readable amounts into base units.
KYROX addresses these risks by enforcing a strict Read $\rightarrow$ Prepare $\rightarrow$ Simulate/Check $\rightarrow$ Human Signs Externally boundary.
3. Why MCP Is Useful for AI Agents in Finance
The Model Context Protocol (MCP) provides a standardized JSON-RPC interface over stdio between an AI host (such as MCP Inspector or Claude Desktop) and domain-specific tool servers:
Deterministic Boundary Validation: Instead of trusting an LLM to format raw RPC payloads or ABI calldata in free text, MCP tools validate schemas, checksummed EVM addresses, chain IDs, and
Decimalquantities inside the Python server before any RPC call is made.Explicit Provenance Envelopes: Every tool response can return structured metadata—environment label (
mockvs.base-sepolia), data source, observation timestamp, staleness flag, and token decimals—so the agent and user can see the exact provenance of every number.Process & Credential Isolation: The MCP server runs in an isolated local environment with read-only public RPC configuration, while private keys remain completely outside the server and model context.
4. High-Level System Architecture (v0.1)
AI Host / MCP Client (MCP Inspector / Claude Desktop)
|
| MCP stdio transport (JSON-RPC on stdout; diagnostics on stderr)
v
KYROX Python MCP Server (FastMCP) [VERIFIED]
|
+--> Stock Data Adapter ------> Labelled mock fixtures (data/stocks.json / KYROX_STOCKS_FILE) [VERIFIED]
+--> Wallet Reader -----------> Base Sepolia RPC (ERC-20 read calls, chainId 84532) [IN PROGRESS]
+--> Portfolio Calculator ----> Token balances + qualified reference values (100-digit Decimal) [IN PROGRESS]
+--> Transaction Builder -----> Unsigned transaction payload only (signed: false) [IN PROGRESS]
+--> Simulator ---------------> eth_call + gas estimate + policy checks on exact intent [IN PROGRESS]
+--> Audit Logger & Errors ---> Redacted JSONL call logs & error classification [VERIFIED]
+--> Transaction Policy Gate -> 50-token max, ticker allowlist & human approval (tools/policy.py) [VERIFIED]
Human reviews and signs outside KYROX in their own external wallet.
KYROX v0.1 never receives private keys, never signs, and never broadcasts.5. Current Implementation Status (VERIFIED, IN PROGRESS, PLANNED)
KYROX follows a strict evidence-first policy: every component is labelled by its actual implementation and verification state in this repository.
Component | Status | Notes |
Python 3.11+ / 3.13 virtual environment & dependency lock |
| requirements.txt (cross-platform) and requirements-lock.txt (73 pinned packages). |
Environment & security hygiene smoke tests |
| tests/test_environment_smoke.py ( |
Public configuration template & ignore rules |
| .env.example (placeholders only) and .gitignore. |
Package directory scaffolds ( |
| |
FastMCP server entrypoint ( |
| server.py ( |
Stock catalogue tools ( |
| tools/stocks.py, data/stocks.json, and tests/test_stocks.py ( |
Mock ERC-20 stock contract ( |
| contracts/MockStock.sol (OpenZeppelin ERC-20, 18 decimals, mints |
Base Sepolia wallet balance & portfolio reader ( |
| tools/wallet.py, tests/test_wallet.py, tests/test_portfolio.py, and tests/test_stdio.py ( |
Structured JSONL audit logging & centralized error handling ( |
| tools/log.py, tools/errors.py, and tests/test_logging_and_errors.py ( |
Unsigned ERC-20 transaction builder & EVM simulator ( |
| tools/tx.py and tests/test_tx.py ( |
Transaction safety policy module ( |
| tools/policy.py and tests/test_policy.py ( |
6. The Six MCP Tools (v0.1 Scope)
All v0.1 demonstrations operate exclusively on Base Sepolia testnet (chainId: 84532) and clearly labelled mock ERC-20 stock tokens:
Tool | Category | Status | Behavior |
| Read-only |
| Return mock tokenized-stock record ( |
| Read-only |
| Return all configured stock summaries ( |
| Read-only |
| Validate a public EVM address, verify Base Sepolia ( |
| Read-only |
| Combine Base Sepolia ERC-20 token balances with qualified reference values using 100-digit |
| Unsigned Intent |
| Validate sender/recipient addresses, Base Sepolia ( |
| Dry-Run & Policy |
| Reuse |
(A hello_kyrox(name) connectivity tool is also VERIFIED in server.py.)
How prepare_transaction Works (tools/tx.py)
Input Parameters:
from_wallet(str): Public EIP-55 checksummed or hex sender wallet address on Base Sepolia.ticker(str): Approved tokenized-stock ticker symbol from the configured stock catalogue (e.g.,tAAPL,tTSLA,tNVDA).to(str): Public EIP-55 checksummed or hex recipient wallet address on Base Sepolia.amount(int | float | str): Positive finite token quantity to transfer.
Exact ERC-20 Amount Conversion:
prepare_transactionreadsdecimals()from the verified token contract (and cross-checks datasetdecimalswhen configured; it never blindly assumes 18 decimals). User-facing token amounts are validated viaDecimal(rejecting booleans,NaN,Infinity,<= 0, and fractional precision exceeding tokendecimals) and converted into exact integer base units (amount * 10**decimals) with zero binary floating-point rounding or truncation.Contract Target vs. Recipient Separation: In the returned
unsigned_txenvelope,unsigned_tx["to"]always points to the ERC-20 token contract address, while the recipient wallet (to) andamount_base_unitsare ABI-encoded insideunsigned_tx["data"](transfer(address,uint256)selector0xa9059cbb).Pending Nonce Snapshot: The sender
nonceis queried usingeth_getTransactionCount(from_wallet, "pending"). A prepared nonce is a point-in-time snapshot and is not reserved on-chain.Unsigned & Non-Custodial (
signed: false): KYROX never accepts, stores, or accesses private keys or seed phrases, and contains nosign_transactionorsend_raw_transactioncode paths. Every prepared intent returnssigned: falseandbroadcast: falseso the human user can inspect, simulate, and sign externally in their own wallet on Base Sepolia (chainId: 84532/0x14a34) only.Missing Deployment Configuration & Mock Provider Testing: Packaged
data/stocks.jsonkeepstoken_address: ""in version control until live Base SepoliaMockStock.solcontracts are deployed and supplied viaKYROX_STOCKS_FILE. Whentoken_addressis blank,prepare_transactionsafely rejects withMISSING_CONFIGURATION. All positive automated tests intests/test_tx.pyuse a deterministic mocked Web3 provider fixture (MOCK PROVIDER · TEST FIXTURE) rather than live on-chain transactions.
How simulate_transaction Works (tools/tx.py)
Shared Preparation & Policy Gate Before RPC:
simulate_transaction(from_wallet, ticker, to, amount)reusesprepare_transactionandverify_prepared_transaction_intentrather than duplicating transfer construction. Policy limits (KYROX_MAX_TX_AMOUNT,DEFAULT_MAX_TOKEN_AMOUNT,KYROX_APPROVED_TICKERS,KYROX_ALLOWED_RECIPIENTS, and token-contract self-transfer prevention) execute before any simulation RPC call. Requests exceeding the configured policy limit are blocked immediately withPOLICY_REJECTED.eth_callvs.eth_estimateGason Base Sepolia (chainId: 84532, Pinned Canonical Block Snapshot):Single Canonical Block Snapshot: After verifying Base Sepolia (
chainId == 84532) and contract bytecode, KYROX querieseth_blockNumberonce, validates it as a non-negative integer, and passes that exact block number to botheth_callandeth_estimateGasso the two RPC calls cannot evaluate different block heights.Allowlisted EIP-1474 Call Object (
build_simulation_call_object): Rather than forwarding internal intent metadata or transaction-signing fields (chainId,nonce,intent_hash,expires_at,signed,broadcast), KYROX constructs a dedicated execution-call dictionary containing only the allowlisted EIP-1474 fields (from,to,data,value: 0).eth_call(Execution Dry-Run): Executes the exact prepared message call (from: from_wallet,to: token_address,data: calldata,value: 0) against the captured canonical block number without creating, signing, or broadcasting a transaction. KYROX ABI-decodes the 32-byteboolreturn word fromtransfer(address,uint256)so an explicitfalsereturn (0x00...00) is classified as a failed simulation (would_succeed: false,ERC20_TRANSFER_FALSE) rather than a false positive.eth_estimateGas(Gas Unit Estimation): Only aftereth_callsucceeds and returnstrue, KYROX callseth_estimateGaswith the identical execution-call dictionary and pinned block number.estimated_gasis returned strictly in gas units (gas_units: "gas"), never as an ETH or currency fee, and KYROX never invents a fallback gas number if estimation fails.
Error Taxonomy & Provider Outage Separation: KYROX distinguishes (1) successful simulation (
would_succeed: true), (2) insufficient token balance reverts (INSUFFICIENT_TOKEN_BALANCE, including OpenZeppelin v5ERC20InsufficientBalanceselector0xe450d38cand v4transfer amount exceeds balance), (3) other contract-level reverts (SIMULATION_REVERTED), (4) ERC-20falsereturns (ERC20_TRANSFER_FALSE), (5) policy rejections (POLICY_REJECTED), (6) expired/tampered intents (INTENT_EXPIRED,INTENT_TAMPERED), (7) address/amount/chain/configuration errors, and (8) RPC timeouts (RPC_TIMEOUT), connection failures (RPC_CONNECTION_FAILED), and malformed provider responses (MALFORMED_PROVIDER_RESPONSE). An RPC outage is never misrepresented as an insufficient-balance revert.Why Simulation Does Not Guarantee Later Execution: Both
eth_callandeth_estimateGasevaluate blockchain state at a single point in time ("latest"). Between simulation and external human wallet signing, balances, allowances, contract pause states, nonces, or gas conditions can change. Human review and external wallet verification remain mandatory.
How the Transaction Safety Policy Works (tools/policy.py)
50-Token Default Transaction Maximum:
DEFAULT_MAX_TOKEN_AMOUNTis50tokens per transaction (amount <= 50inclusive boundary:10,49, and50are allowed by the amount policy;50.01and100are denied withPOLICY_REJECTED). Operators can tighten the limit below50viaKYROX_MAX_TOKEN_AMOUNTorKYROX_MAX_TX_AMOUNT, while values above the50-token safety ceiling (HARD_MAX_TOKEN_AMOUNT = 50) are rejected asINVALID_CONFIGURATION.Three Approved Tickers (
tAAPL,tTSLA,tNVDA): OnlytAAPL,tTSLA, andtNVDAare permitted by the canonical ticker allowlist (CANONICAL_APPROVED_TICKERS). Unknown tickers (and arbitrary extra entries injected into a custom dataset file orKYROX_APPROVED_TICKERS) are rejected before any RPC call.Strictly Positive, Finite
DecimalAmounts & Token Precision: Zero, negative values,NaN,+Infinity,-Infinity, booleans (True/False), non-numeric strings, and fractional amounts exceeding the token's supported decimal precision are deterministically rejected usingDecimalarithmetic (never binary floating-point conversion).Mandatory Human Approval (
requires_human_approval = True): Every policy decision and transaction tool response—whether allowed or denied—retainsrequires_human_approval: true,signed: false, andbroadcast: false. Passing the policy check is not human approval and not transaction execution authorization; any attempt to pass override flags (requires_human_approval=Falseorhuman_approved=True) is rejected.Independent Enforcement in Both Transaction Tools: Both
prepare_transactionandsimulate_transactionindependently invoke the central policy gate (_enforce_pre_rpc_transaction_policy/evaluate_transaction_policy) before any unsigned transaction construction, calldata encoding,eth_call, oreth_estimateGasexecution.Fail-Closed Policy Decision Audit Logging: Every allowed and denied policy decision is recorded in
logs/audit.jsonlviatools/log.pywith structured metadata (event,tool,ticker,normalized_amount,effective_max_amount,allowed,decision,reasons,requires_human_approval,policy_version) and recursive secret redaction. If writing to the audit log fails during an allowed transaction or policy decision, KYROX fails closed and rejects the operation.
7. Technology Stack
Language & Runtime: Python 3.11+ (verified on Python 3.13.7 x64)
MCP Framework: Official MCP Python SDK v1 compatibility line (
mcp[cli]>=1.28,<2,FastMCP)Blockchain / EVM Client:
web3.py(web3>=8.0,<9) targeting Base Sepolia (chainId: 84532)HTTP & Configuration:
requests(>=2.32,<3),python-dotenv(>=1.0,<2)Testing:
pytest(>=8.0,<10)Optional Developer Tooling: Node.js LTS &
npm/npx(used only when launching MCP Inspector UI viamcp dev)
8. Installation & Local Verification
Prerequisites
Python 3.11+ (Python 3.13 recommended)
Git
Node.js LTS & npm (optional — required only for the browser-based MCP Inspector UI)
Windows (PowerShell)
# 1. Create and activate a project-local virtual environment
py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
# 2. Install cross-platform dependencies (or use requirements-lock.txt for exact pinned versions)
python -m pip install -r requirements.txt
python -m pip check
# 3. Copy placeholder configuration (never put private keys or secrets in .env)
Copy-Item .env.example .env
# 4. Run the test suite (394 automated checks)
python -m pytest -v
# 5. Execute a portfolio query (uses KYROX_STOCKS_FILE if set, or data/stocks.json)
python -c "import json; from server import get_portfolio; print(json.dumps(get_portfolio('0x71C7656EC7ab88b098defB751B7401B5f6d8976F'), indent=2))"macOS & Linux (bash / zsh)
# 1. Create and activate a project-local virtual environment
python3 -m venv .venv
source .venv/bin/activate
# 2. Install cross-platform dependencies (or use requirements-lock.txt for exact pinned versions)
python -m pip install -r requirements.txt
python -m pip check
# 3. Copy placeholder configuration (never put private keys or secrets in .env)
cp .env.example .env
# 4. Run the test suite (394 automated checks)
python -m pytest -v
# 5. Execute a portfolio query (uses KYROX_STOCKS_FILE if set, or data/stocks.json)
python -c "import json; from server import get_portfolio; print(json.dumps(get_portfolio('0x71C7656EC7ab88b098defB751B7401B5f6d8976F'), indent=2))"9. Security Principles
Please read SECURITY.md before using or contributing to KYROX. Core invariants include:
No Private Keys or Seed Phrases: KYROX never asks for, accepts, stores, logs, or transmits private keys, seed phrases, recovery codes, or API secrets.
No Signing or Broadcasting:
v0.1contains zero transaction-signing or transaction-broadcasting code paths. Every prepared transaction is returned unsigned (signed: false) for external human wallet review.Policy Verdict $\neq$ Human Approval: Passing a server-side policy check or
eth_calldry run only means the proposed parameters passed automated pre-checks at a point in time; it is not a signature, a guarantee of future on-chain execution, or a substitute for human wallet verification.Exact Financial Arithmetic: Token quantities and valuations must use integer base units and Python
Decimal—never binary floating-point numbers.Untrusted Input Validation: All LLM-supplied tool arguments (tickers, EVM addresses, chain IDs, amounts) and external RPC/API responses are treated as untrusted input and validated at the server boundary.
Clean
stdioProtocol Output: Server diagnostics and structured logs belong onstderror in local log files (ignored by Git) so MCPstdioJSON-RPC frames remain uncorrupted.
10. Base Sepolia & Mock-Data Limitations
Testnet & Mock Fixtures Only: KYROX
v0.1is restricted to Base Sepolia testnet (chainId: 84532) and local mock stock fixtures (mock). It does not connect to mainnet execution venues or trade real equities.Mock ERC-20 Tokens $\neq$ Regulated Securities: Testnet mock tokens do not model regulated issuance, corporate actions, dividend/split multipliers, off-hours market halts, or live order-book liquidity.
Reference Values Are Not Live Quotes: Any
reference_valuein mock fixtures is static test data for development and must never be treated as a live market price or executable quote.Point-in-Time Simulation Caveat: An
eth_callsimulation or gas estimate reflects RPC state at a single block height and does not guarantee that a transaction signed later will succeed on-chain.Not Audited / Not Financial Advice: KYROX is an experimental open-source technical prototype and has not undergone an independent security audit. Nothing in this repository constitutes financial, investment, legal, or tax advice. KYROX has no token, no token sale, and no airdrop or yield program.
11. License
Licensed under the Apache License, Version 2.0 (Apache-2.0). See the LICENSE file for the full license text.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Provide AI agents and automation tools with contextual access to blockchain data including balance…
EVM wallet reads, simulation, and transaction execution under user-defined authorization policies.
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Connect AI agents to bank accounts, transactions, balances, and investments.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to check balances and send transactions across multiple blockchains with automatic spending limit protection and policy enforcement.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to analyze Ethereum wallets, simulate transactions, and draft transfers with deterministic policy and risk scoring, requiring human approval before on-chain execution.12 npmISC
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to safely interact with Ethereum by providing structured tools for reading blockchain state, simulating transactions, and drafting transactions that require human-in-the-loop approval.1-

Stocklayer MCPofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to discover tokenized Stock Tokens, read reference prices and wallet balances on Robinhood Chain, create quotes, simulate transactions, and build policy-checked trade plans that return an explainable verdict plus unsigned transactions for a wallet to sign.MIT