{"id":51025383,"url":"https://github.com/edycutjong/bourse","last_synced_at":"2026-06-21T19:01:53.211Z","repository":{"id":365163397,"uuid":"1270756557","full_name":"edycutjong/bourse","owner":"edycutjong","description":"🌈 A CoinMarketCap Skill that turns crowd-vs-smart-money divergence into a backtestable strategy — and sells it on-chain to   other agents via ERC-8183.","archived":false,"fork":false,"pushed_at":"2026-06-16T07:32:28.000Z","size":1205,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T07:48:04.621Z","etag":null,"topics":["ai-agents","bnb-chain","coinmarketcap","defi","erc-8183","hackathon","trading"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edycutjong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T02:52:06.000Z","updated_at":"2026-06-16T07:32:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/edycutjong/bourse","commit_stats":null,"previous_names":["edycutjong/bourse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/edycutjong/bourse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fbourse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fbourse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fbourse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fbourse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edycutjong","download_url":"https://codeload.github.com/edycutjong/bourse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edycutjong%2Fbourse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34622271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bnb-chain","coinmarketcap","defi","erc-8183","hackathon","trading"],"created_at":"2026-06-21T19:01:51.571Z","updated_at":"2026-06-21T19:01:53.205Z","avatar_url":"https://github.com/edycutjong.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/icon.svg\" width=\"140\" alt=\"Bourse Icon\"\u003e\n\n  \u003ch1\u003eBourse 🌈\u003c/h1\u003e\n  \u003cp\u003e\u003cem\u003eThe exchange for strategy intelligence — fading the crowd, funded by whales.\u003c/em\u003e\u003c/p\u003e\n  \u003cimg src=\"docs/readme-hero.svg\" alt=\"Bourse README\" width=\"100%\"\u003e\n  \n  [![YouTube Video](https://img.shields.io/badge/▶_Demo-Video-EF4444?style=for-the-badge)](https://youtu.be/Y5YgTCEqJqw)\n  [![Strategy Skill](https://img.shields.io/badge/🎯_SKILL.md-Track_2-22c55e?style=for-the-badge)](./skill/bourse/SKILL.md)\n  [![Built for BNB Hackathon](https://img.shields.io/badge/DoraHacks-BNB_Hackathon_2026-F97631?style=for-the-badge)](https://dorahacks.io/hackathon/bnbhack-twt-cmc/detail)\n  \n  \u003cbr/\u003e\n\n  [![MCP](https://img.shields.io/badge/-MCP-D4A27F?logo=modelcontextprotocol)](https://mcpx.dev)\n  [![Tests](https://img.shields.io/badge/pytest-225_passing-22c55e?style=flat)](./Makefile#L63)\n  ![Python](https://img.shields.io/badge/Python_3.11+-3776AB?style=flat\u0026logo=python\u0026logoColor=white)\n  ![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat\u0026logo=fastapi\u0026logoColor=white)\n  ![BNB Chain](https://img.shields.io/badge/BNB_Chain-F3BA2F?style=flat\u0026logo=binance\u0026logoColor=white)\n  ![CoinMarketCap](https://img.shields.io/badge/CoinMarketCap-174AFF?style=flat\u0026logo=coinmarketcap\u0026logoColor=white)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-f59e0b?style=flat)](./LICENSE)\n  [![CI](https://github.com/edycutjong/bourse/actions/workflows/ci.yml/badge.svg)](https://github.com/edycutjong/bourse/actions/workflows/ci.yml)\n\u003c/div\u003e\n\n---\n\n## 📸 See it in Action\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003cstrong\u003e1. Interactive Web3 Dashboard \u0026 Strategy Terminal\u003c/strong\u003e\u003c/p\u003e\n  \u003cimg width=\"800\" height=\"450\" alt=\"Dashboard Overview\" src=\"https://github.com/user-attachments/assets/9c7c64af-d7cd-4424-9a2a-96ac45aeabf5\" /\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cp\u003e\u003cstrong\u003e2. On-Chain Buyer Agent Simulation\u003c/strong\u003e\u003c/p\u003e\n  \u003cimg width=\"800\" height=\"450\" alt=\"On Chain Simulator Buyer\" src=\"https://github.com/user-attachments/assets/b9d9a72d-31e7-4361-836d-b3930a6b2df1\" /\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cp\u003e\u003cstrong\u003e3. Live Claude Desktop MCP Session\u003c/strong\u003e\u003c/p\u003e\n  \u003cimg width=\"720\" height=\"500\" alt=\"Claude Desktop MCP Session\" src=\"https://github.com/user-attachments/assets/6883afc7-7349-478d-b1b6-2cbd3b219a12\" /\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cp\u003e\u003cstrong\u003e4. YouTube Walkthrough Presentation:\u003c/strong\u003e\u003c/p\u003e\n  \u003ca href=\"https://youtu.be/Y5YgTCEqJqw\" target=\"_blank\"\u003e\n    \u003cimg src=\"docs/og-image.png\" alt=\"Bourse Demo Video (Click to Watch)\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003e **A retail trader apes a KOL-pumped token at the top — while the whales who funded those KOLs quietly sell into his bid.** Bourse is the signal that screams *fade, don't follow* — and sells it to any agent by the cent.\n\n---\n\n## 💡 The Problem \u0026 Solution\n\n*   **The Problem:** Retail traders and AI agents are systematically harvested by smart money using on-chain manipulation and narrative control. Trading purely on price action or basic TA leads agents directly into the same retail liquidity traps.\n*   **The Solution:** **Bourse** fuses four distinct data planes (derivatives positioning, on-chain whale flow, social/narrative heat, and market regime) into a single, real-time **Divergence score** and emits a backtestable, standardized strategy specification.\n*   **The Delivery:** Built as a fully autonomous agentic skill on the **CoinMarketCap Agent Hub (MCP)** and wrapped as a hireable on-chain service using the **BNB AI Agent SDK (ERC-8183)**.\n\n---\n\n## 🏗️ Architecture \u0026 Tech Stack\n\nBourse separates concerns into a high-performance compute engine (Python), an on-chain commerce gateway (BNB SDK), and a unified data client (CMC MCP).\n\n| Layer | Technology | Purpose |\n| :--- | :--- | :--- |\n| **Core Engine** | Python 3.11+, NumPy | Divergence engine, regime rules, walk-forward backtest + optimizer math |\n| **API / Server** | FastAPI, Uvicorn | ERC-8183 provider hosting, demo UI gateway |\n| **Agent Hub** | CoinMarketCap Agent Hub Skill | Live signal retrieval across 4 distinct data planes |\n| **Commerce / Escrow** | BNB AI Agent SDK (ERC-8183, ERC-8004, X402Signer) | On-chain registration, escrowed jobs, settlement |\n\n### System Diagram\n```mermaid\nflowchart TD\n    subgraph CMC[\"CoinMarketCap Agent Hub (MCP)\"]\n        D[Derivatives Data\\nfunding/OI/liq]\n        O[On-Chain Metrics\\nwhale vs retail flow]\n        N[Trending Narratives\\n+ Latest News]\n        T[Crypto Technical Analysis\\n+ Global Metrics / F\u0026G]\n    end\n\n    subgraph BOURSE[\"Bourse core (Python)\"]\n        ING[Plane ingestor\\nMCP client] --\u003e ENG[Divergence + Regime engine\\nz-scores, rule set]\n        ENG --\u003e SPEC[Strategy-spec generator\\nYAML/JSON]\n        SPEC --\u003e BT[Backtest harness\\nSharpe/maxDD/winrate]\n    end\n\n    subgraph SDK[\"BNB AI Agent SDK\"]\n        ID[ERC-8004 identity]\n        PROV[\"ERC-8183 provider\\ncreate_erc8183_app(on_job=run_divergence)\"]\n        X4[X402Signer\\nEIP-3009]\n    end\n\n    D \u0026 O \u0026 N \u0026 T --\u003e|MCP tools| ING\n    X4 -.pay USDC/Base.-\u003e CMC\n    SPEC --\u003e SKILL[[SKILL.md\\nTrack-2 deliverable]]\n    SPEC --\u003e PROV\n    BUYER[Buyer agent] --\u003e|negotiate→fund USDC| PROV\n    PROV --\u003e|signed signal payload| BUYER\n    PROV --\u003e|router.settle jobId| BSC[(BSC: AgenticCommerce\\n+ EvaluatorRouter\\n+ OptimisticPolicy)]\n    ID --- PROV\n```\n\n---\n\n## 🏆 Sponsor Tracks \u0026 Integrations\n\nBourse targets **Track 2 — Strategy Skills** (Best Use of Agent Hub, Best Use of BNB AI Agent SDK) with deep, production-grade integrations:\n\n### 📊 1. CoinMarketCap Agent Hub (MCP)\nBourse computes its core divergence metric by querying **5 tools** across 4 distinct data planes from the CMC MCP:\n*   **Derivatives Data:** Queries funding rates and Open Interest delta via the MCP.\n*   **On-Chain Metrics:** Evaluates net whale flow vs retail accumulation.\n*   **Trending Narratives:** Scrapes social hype heat and news sentiment scores.\n*   **Crypto Technical Analysis:** Gathers price EMAs, RSIs, and global Fear \u0026 Greed index gates.\n*   **Code Location:** Configured inside [bourse/ingest.py](file:///Users/edycu/Projects/Hackathon/dorahacks-bnbhack-bourse/bourse/ingest.py).\n\n### ⚡ 2. BNB AI Agent SDK\nBourse leverages the BNB SDK to enable machine-to-machine commerce:\n*   **ERC-8004 Identity:** Registers Bourse as a discoverable agent on BSC Testnet (gas-free via MegaFuel). Implementation in [server/identity.py](file:///Users/edycu/Projects/Hackathon/dorahacks-bnbhack-bourse/server/identity.py).\n*   **ERC-8183 Provider App:** Mounts the FastAPI provider to handle the negotiate-fund-settle job lifecycle. Implementation in [server/app.py](file:///Users/edycu/Projects/Hackathon/dorahacks-bnbhack-bourse/server/app.py).\n*   **Agentic Commerce \u0026 Settlement:** Uses the SDK's `AgenticCommerce`, `EvaluatorRouter`, and `OptimisticPolicy` to manage escrows on BSC Testnet. Buyer script in [clients/buyer.py](file:///Users/edycu/Projects/Hackathon/dorahacks-bnbhack-bourse/clients/buyer.py) and settlement in [scripts/settle.py](file:///Users/edycu/Projects/Hackathon/dorahacks-bnbhack-bourse/scripts/settle.py).\n*   **X402 Signer:** Enforces micropayment spend caps per call (EIP-3009).\n\n---\n\n## 🧩 Why ONLY this stack\n\n**Why ONLY CoinMarketCap Agent Hub.** Bourse's thesis — *divergence between crowd and smart money* — is only computable because CMC unifies four normally-siloed planes behind one MCP: **Derivatives Data** (funding/OI → overcrowded-longs), **On-Chain Metrics** (whale net-flow → smart money leaving), **Trending Narratives** (social heat → crowd euphoric), **Crypto Technical Analysis** (entry/exit triggers), and **Global Market Metrics** (Fear \u0026 Greed → regime gate). Take CMC out and you'd need 4+ vendors (a derivatives API + an on-chain analytics provider + a social feed + a TA library) and a custom normalization layer — exactly the plumbing this hackathon exists to delete.\n*Honest limitation:* CMC's on-chain flow is aggregated, so Bourse detects distribution *pressure*, not the seller's identity.\n\n**Why ONLY BNB AI Agent SDK.** The SDK *is* the marketplace, not a mention: `ERC8004Agent` gives Bourse a discoverable on-chain identity (gas-free testnet reg via MegaFuel); `create_erc8183_app(on_job=…)` turns the engine into a hireable provider; `AgenticCommerce` + `EvaluatorRouter` + `OptimisticPolicy` handle escrow, optimistic settlement, and dispute quorum; `X402Signer` (EIP-3009) caps per-call spend. Take the SDK out and you'd be rebuilding ERC-8183 from scratch.\n*Honest limitation:* optimistic settlement leans on a whitelisted-voter quorum, not a fully trustless oracle.\n\n**Two-sided x402 (real, not a README line).** Bourse *pays* CMC per premium pull (USDC on Base 8453) and *earns* from buyers per signal (USDC on BSC). It spends to think and earns to deliver — a literal *bourse* for strategy intelligence.\n\n---\n\n## 🚀 Getting Started \u0026 Judge Verification\n\nWe have made Bourse fully **reproducible and testable offline**. Judges can run the entire backtest, CLI signal generation, and mock commerce flows without configuring live keys or real wallets.\n\n### Prerequisites\n*   Python ≥ 3.11\n*   pip\n\n### Installation\n1.  **Clone the Repository:**\n    ```bash\n    git clone https://github.com/edycutjong/bourse.git\n    cd bourse\n    ```\n2.  **Install Dependencies:**\n    ```bash\n    pip install -r requirements.txt\n    pip install -e .\n    ```\n3.  **Setup Environment Variables:**\n    ```bash\n    cp .env.example .env\n    ```\n    *(For offline demo runs, the default dummy values in `.env` are sufficient. For live runs, populate your `CMC_PRO_API_KEY` or `CMC_MCP_API_KEY` and a BSC-testnet private key).*\n\n### 🔌 Expose Bourse to Claude Desktop (MCP Server Setup)\n\nBourse can run as a local stdio Model Context Protocol (MCP) server. This allows **Claude Desktop** to directly call Bourse tools (Divergence board, Token signals, and Backtests) in chat.\n\nAdd the following config to your `claude_desktop_config.json` (on macOS, located at `~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"bourse\": {\n      \"command\": \"/absolute/path/to/bourse/.venv/bin/python3\",\n      \"args\": [\n        \"/absolute/path/to/bourse/scripts/mcp_server.py\"\n      ]\n    }\n  }\n}\n```\n\nOnce added, restart Claude Desktop and you can query:\n* *\"Show me the Bourse divergence board\"*\n* *\"Bourse, where is social hype most disconnected from smart money right now?\"*\n* *\"Run a backtest for CAKE\"*\n\n### Verification Commands\n\n```bash\nmake seed            # Write deterministic demo fixtures (offline execution prep)\nmake signal          # View the ranked divergence board (offline, mock mode)\nmake signal-cake     # Generate 4-plane \"why\" details + spec + backtest for CAKE\nmake backtest        # Run walk-forward backtest and view ASCII equity curve\npython scripts/optimize_weights.py   # Walk-forward optimizer: fits weights on a train window, reports OUT-OF-SAMPLE Sharpe on the next unseen window, across tokens (in-sample vs OOS shown side by side)\npython scripts/execute_strategy.py   # PancakeSwap V3 Strategy Execution Copilot (executes strategy on BSC Testnet)\nmake test            # Run the 225-test suite and verify all pass\nmake test-coverage   # Run the test suite and display coverage report (100% lines)\nmake ci              # Run the complete CI/CD checks (ruff, mypy, tests, security, readiness)\n```\n\n\u003e [!TIP]\n\u003e **No Accounts or Wallets Required for Judges:**\n\u003e Everything runs seamlessly offline using deterministic fixtures generated via `make seed`. To query live data, add a CMC key to `.env` and append `--live` to the signal script: `python scripts/signal.py --token CAKE --live`.\n\n---\n\n## 🧪 Testing \u0026 CI\n\nBourse maintains **100% line coverage** across the entire core codebase (385 statements). \n\n### CI/CD Pipeline\nRunning `make ci` executes our local validation gate:\n1.  **Stage 1: Code Quality (Ruff):** Code style \u0026 formatting checks.\n2.  **Stage 1: Type Safety (Mypy):** Dynamic and static type checks.\n3.  **Stage 1: Unit Testing (Pytest-Cov):** Validates the divergence engine, regime rules, strategy spec, and backtest loops.\n4.  **Stage 2: Dependency Security Audit (pip-audit):** Verifies all package dependencies against known CVEs.\n5.  **Submission Gate (check_submission_readiness):** Runs final check for SKILL.md layout, test count consistency, and committed secrets.\n\n| Layer | Tool | Status |\n| :--- | :--- | :--- |\n| **Code Quality** | Ruff + mypy | ✅ Passed |\n| **Unit Testing** | pytest (225 tests) | ✅ Passed (100% coverage) |\n| **Security (SAST)** | CodeQL | ✅ Passed |\n| **Security (SCA)** | Dependabot + pip-audit | ✅ Passed |\n| **Secret Scanning** | TruffleHog | ✅ Passed |\n\n---\n\n## 📁 Repository Layout\n\n```text\nskill/bourse/SKILL.md         # Track-2 deliverable (CMC Agent Skills format)\nbourse/engine.py              # Divergence + regime engine (z-scores, rules)\nbourse/spec.py                # Bourse strategy specification generator (bourse.signal.v1)\nbourse/ingest.py              # CMC MCP client (live) + REST (history) + fixtures\nbourse/backtest.py            # Walk-forward backtest (Sharpe, max drawdown, win rate)\nbourse/walkforward.py         # Walk-forward weight optimizer (train/test split, out-of-sample Sharpe)\nscripts/signal.py             # CLI: ranked board / token explanation / live discovery\nserver/app.py                 # ERC-8183 provider (FastAPI)\nserver/identity.py            # ERC-8004 identity registration\nclients/buyer.py              # ERC8183Client buyer simulation\nscripts/probe_cmc_history.py  # Day-1 data gate checklist\nscripts/backtest.py           # CLI backtest wrapper with ASCII chart rendering\nscripts/optimize_weights.py   # Walk-forward optimizer CLI (in-sample vs out-of-sample, multi-token)\nscripts/settle.py             # BSC permissionless settlement runner\nscripts/seed.py               # Deterministic fixture seeding script\nscripts/check_submission_readiness.py  # Pre-submit readiness validator\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fbourse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedycutjong%2Fbourse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedycutjong%2Fbourse/lists"}