{"id":50970290,"url":"https://github.com/kryptic-sh/tikr","last_synced_at":"2026-06-19T01:32:25.420Z","repository":{"id":358548941,"uuid":"1241783182","full_name":"kryptic-sh/tikr","owner":"kryptic-sh","description":"Modular market-making engine. Venue-agnostic Rust workspace. Pre-alpha.","archived":false,"fork":false,"pushed_at":"2026-06-09T05:11:36.000Z","size":2613,"stargazers_count":1,"open_issues_count":18,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T07:14:17.340Z","etag":null,"topics":["crypto","defi","hyperliquid","market-making","rust","trading-bot"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kryptic-sh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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},"funding":{"github":["mxaddict"],"ko_fi":"mxaddict"}},"created_at":"2026-05-17T20:09:26.000Z","updated_at":"2026-06-09T05:11:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kryptic-sh/tikr","commit_stats":null,"previous_names":["kryptic-sh/tikr"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kryptic-sh/tikr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptic-sh%2Ftikr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptic-sh%2Ftikr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptic-sh%2Ftikr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptic-sh%2Ftikr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kryptic-sh","download_url":"https://codeload.github.com/kryptic-sh/tikr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kryptic-sh%2Ftikr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34514282,"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-18T02:00:06.871Z","response_time":128,"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":["crypto","defi","hyperliquid","market-making","rust","trading-bot"],"created_at":"2026-06-19T01:32:24.111Z","updated_at":"2026-06-19T01:32:25.385Z","avatar_url":"https://github.com/kryptic-sh.png","language":"Rust","funding_links":["https://github.com/sponsors/mxaddict","https://ko-fi.com/mxaddict"],"categories":[],"sub_categories":[],"readme":"# tikr\n\n\u003e ## ⚠️ READ THIS FIRST — FINANCIAL RISK WARNING ⚠️\n\u003e\n\u003e **This is experimental software for educational and personal research use\n\u003e only. It is NOT financial advice and NOT a production trading system.**\n\u003e\n\u003e - **You can lose ALL of your money.** Market making, perpetual futures, and\n\u003e   any leveraged trading carries unlimited downside risk including liquidation\n\u003e   and negative balance.\n\u003e - **Bugs in this code WILL lose you money** if you run it with real funds.\n\u003e   This is pre-alpha, unaudited, written by hobbyists with no fiduciary\n\u003e   relationship to you.\n\u003e - **You are 100% responsible** for any losses, regulatory consequences, tax\n\u003e   obligations, exchange TOS violations, and account actions resulting from\n\u003e   running this bot. The authors accept ZERO liability.\n\u003e - **Test on testnet only** until you fully understand the code. Even then,\n\u003e   start with the smallest possible position sizes if you ever go live.\n\u003e - **Manipulation, wash trading, and other prohibited strategies are NOT legal\n\u003e   on DEXs either** — see the Mango Markets case. Don't use this for anything\n\u003e   that would violate your jurisdiction's market-abuse laws or your exchange's\n\u003e   terms of service.\n\u003e - **Run only on accounts you can afford to zero out.** Never trade with money\n\u003e   you need for rent, debt, dependents, or anything else.\n\u003e\n\u003e By cloning, building, or running this software you acknowledge that you have\n\u003e read this warning and that any financial loss is entirely your own\n\u003e responsibility. See [LICENSE](LICENSE) (MIT — \"AS IS, WITHOUT WARRANTY OF ANY\n\u003e KIND\").\n\nModular, venue-agnostic market-making engine in Rust. Pre-alpha — parquet\nbacktest engine, a multi-strategy library, a live Binance USD-M / Spot adapter,\nand a config-driven multi-bot orchestrator (`tikr`). Unaudited; see the risk\nwarning above before running it with real funds.\n\n[![CI](https://github.com/kryptic-sh/tikr/actions/workflows/ci.yml/badge.svg)](https://github.com/kryptic-sh/tikr/actions/workflows/ci.yml)\n[![release](https://img.shields.io/github/v/release/kryptic-sh/tikr)](https://github.com/kryptic-sh/tikr/releases)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\u003e **Pre-alpha, under active development.** Live trading paths exist and are\n\u003e unaudited — treat every release as experimental. Watch\n\u003e [Roadmap \u0026 exit criteria](https://github.com/kryptic-sh/tikr/issues/1) for\n\u003e progress.\n\n## Why?\n\nMost open-source MM bots (including\n[mxaddict/mmaker](https://github.com/mxaddict/mmaker), 2017) fail on the same\nthings: inventory-blind quoting, broken post-only handling, no kill switches, no\nbacktest-first discipline. `tikr` is the do-over — built backtest-first,\nvenue-agnostic, with risk limits before live capital.\n\n## Crates\n\n| Crate              | Role                                                                                       |\n| ------------------ | ------------------------------------------------------------------------------------------ |\n| `tikr-core`        | Vocabulary types: `Price`, `Size`, `Symbol`, `Position`, `Snapshot`, `MarketEvent`, `Fill` |\n| `tikr-venue`       | `Venue` trait — abstracts over CEX orderbooks, DEX orderbooks, AMMs via quote-intent model |\n| `tikr-strategy`    | `Strategy` trait + impls (Wave, Tide, Tidal, Hydra, Ratchet, GLFT, AvellanedaStoikov, …)   |\n| `tikr-hyperliquid` | Hyperliquid perp adapter                                                                   |\n| `tikr-binance`     | Binance Spot + USD-M Futures adapter (HMAC + Ed25519 auth, WS-API session.logon)           |\n| `tikr-bybit`       | Bybit adapter                                                                              |\n| `tikr-mexc`        | MEXC adapter                                                                               |\n| `tikr-backtest`    | Parquet replay engine + FillSim (queue-priority + cancel modeling) — library only          |\n| `tikr-record`      | Market-data recorder: Binance WS depth + trades → parquet (`record_binance` bin)           |\n| `tikr-paper`       | Paper-trading runner (live feed + simulated fills) + `compare` strategy sweep              |\n| `tikr-risk`        | Risk engine — pre-trade limits, drawdown gates, alerting                                   |\n\nCrates land as phases ship. See\n[roadmap](https://github.com/kryptic-sh/tikr/issues/1).\n\n## Status\n\nPre-alpha and unaudited. Live adapters and the multi-bot orchestrator work, but\nthe engine is still being tuned. **Run only with capital you can afford to\nlose.**\n\n## Install\n\n```bash\n# build from source\ngit clone https://github.com/kryptic-sh/tikr.git\ncd tikr\ncargo build --release --workspace\n```\n\nBinaries land in `./target/release/`. Key entry points:\n\n| Bin                  | Crate        | Purpose                                                    |\n| -------------------- | ------------ | ---------------------------------------------------------- |\n| `tikr`               | apps/tikr    | Multi-bot live/paper orchestrator + TUI (main entry point) |\n| `record_binance`     | tikr-record  | Record Binance market data (depth + aggTrade) to parquet   |\n| `compare`            | tikr-paper   | Backtest a preset sweep on parquet; table + optional JSON  |\n| `run_spot` (example) | tikr-binance | Live Binance Spot runner (testnet/mainnet)                 |\n\n## Development\n\n```bash\ngit clone git@github.com:kryptic-sh/tikr.git\ncd tikr\nrustup toolchain install stable\ncargo test --workspace\n```\n\n## Usage\n\n### Record market data to parquet\n\n```bash\n# Binance Futures USD-M, 1 hour, ./data\ncargo run --release --bin record_binance -- \\\n  --env futures-mainnet --symbols BTCUSDT --hours 1 --out ./data\n```\n\nRecorder writes `book_\u003cBASE\u003e_\u003cDATE\u003e_\u003cNNNNNN\u003e.parquet` +\n`trades_\u003cBASE\u003e_\u003cDATE\u003e_\u003cNNNNNN\u003e.parquet` per flush (1000 rows or 60 s).\n\n### Backtest strategies against recorded data\n\n`compare` is the single backtest entry point: it sweeps a set of strategy\npresets over the same recorded events (apples-to-apples) and prints a `fills`,\n`fills/min`, `realized`, `fees`, `NET`, `$/fill` table. Pass single-element\nsweep lists to backtest one configuration, and `--report-json \u003cpath\u003e` to dump\nthe per-preset `PaperReport` for downstream tooling.\n\n```bash\n# Full preset sweep\ncargo run --release --bin compare -- \\\n  --data-dir ./data --symbol BTCUSDC \\\n  --maker-bps 2 --taker-bps 5\n\n# Single Wave config → machine-readable report\ncargo run --release --bin compare -- \\\n  --data-dir ./data --symbol BTCUSDC \\\n  --wave-step-bps-list 5 --wave-inner-steps-list 2 --wave-grid-levels-list 4 \\\n  --report-json ./wave.json\n```\n\nVenue filters (price tick, lot step, `min_notional`) auto-detect from Binance\n`exchangeInfo` by default (`--no-autodetect-filters` +\n`--tick-size`/`--step-size` for offline runs; `--venue-env` picks the env).\nAccount sizing mirrors the live bot: `--sim-initial-balance` ×\n`--sim-order-balance-pct` per order, a `--sim-max-position-pct` wallet cap, and\n`--leverage` for the exchange margin backstop. Latency is probed from the live\nAPI by default (10 pings → mean latency + stddev jitter; `--no-measure-latency`\nfalls back to `--sim-submit-latency-ms` / `--sim-cancel-latency-ms` /\n`--sim-latency-jitter-ms`).\n\n### Sample config — `config.toml`\n\nThe repo's [`config.toml`](./config.toml) ships in **auto-rotation** mode: no\nfixed bot list. The `[rampage]` manager scores every liquid Binance USD-M perp,\nruns a strategy on the top N, and re-ranks on an interval. One rotator drives\nboth supported strategies — pick the scoring signal (`[rampage.score]`) and the\nstrategy + geometry (`[rampage.strategy]`) independently.\n\n**Scoring (`[rampage.score]`).** `mode` selects how candidates are ranked:\n\n- `candle_height` (Wave's signal): rank by the average height of the last\n  `candle_count` 1-minute candles, as a percent:\n  `mean((high − low) / low × 100)`, wicks included. Big 1m candles mean lots of\n  intra-minute oscillation for the frozen lattice to bank — the signature of a\n  market that just woke up. A _recent_ signal, so it catches the move as it\n  starts rather than diluting it in a 24h aggregate. Floors with\n  `min_candle_pct`.\n- `tick_bps` (Tide's signal): rank by `tick_size / price × 10000` (no extra API\n  calls — read from the discovery snapshot). Floors with `min_tick_bps`.\n\n**Strategy (`[rampage.strategy]`).** `kind` selects what each spawned bot runs:\n\n- `wave` — frozen fixed-step lattice + round-trip refill.\n- `tide` — fill-driven sliding lattice (grid re-centers as fills land).\n\n**Each recheck** (`recheck_interval_secs`): list perps + price + 24h volume,\npre-filter by `min_volume_usdt`, score the survivors, and run the chosen\nstrategy on the top `top_n`.\n\n**Rotation is graceful.** A symbol that drops out of the top N only rotates when\nits bot's NET PnL (`realized + unrealized − fees`) is green, OR its NET loss is\nwithin `rotate_loss_pct` of total wallet balance (default `1` = 1%). A bigger\nNET loss keeps the bot running (`defer_underwater`, default on) until it\nrecovers or the loss shrinks within tolerance — rotation never crystallizes more\nthan the accepted loss. On shutdown, bots cancel their open orders but leave\npositions intact; a restart re-adopts the position (orphan-position adoption)\nand only re-cancels stale orders.\n\nThe `mode`/`kind` tag and its parameters live in separate tables (the params go\nunder a nested `.params` table):\n\n```toml\n[rampage]\nenabled = true\nmin_volume_usdt = \"2000000\"\nrecheck_interval_secs = 60\nquote_asset = \"USDT\"\ntop_n = 10\n# defer_underwater defaults true\n\n[rampage.score]\nmode = \"candle_height\"      # \"candle_height\" (Wave signal) | \"tick_bps\" (Tide signal)\n[rampage.score.params]\ncandle_count = 60\nmin_candle_pct = \"0\"\n\n[rampage.strategy]\nkind = \"wave\"               # \"wave\" | \"tide\"\n[rampage.strategy.params]\ngrid_levels = 10\nstep_bps = 30\ninner_steps = 2\nrefill_threshold = 5\nchase_to_avg = false\nchase = true\n```\n\nKey knobs:\n\n| Section              | Field                                    | What it does                                                                                         |\n| -------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `[account]`          | `env` / `asset`                          | `futures-mainnet`, USDT-margined (USDT perps host the oscillators)                                   |\n| `[account]`          | `order_balance_pct` / `max_position_pct` | per-order size + wallet-relative position cap                                                        |\n| `[account]`          | `leverage`                               | exchange margin backstop                                                                             |\n| `[rampage]`          | `top_n` / `recheck_interval_secs`        | how many bots to run + how often to re-rank                                                          |\n| `[rampage]`          | `min_volume_usdt` / `quote_asset`        | liquidity pre-filter + which quote to scan                                                           |\n| `[rampage]`          | `defer_underwater` / `rotate_loss_pct`   | defer rotation while NET loss exceeds `rotate_loss_pct` % of wallet (NET = realized+unrealized−fees) |\n| `[rampage]`          | `symbols_allowlist`                      | optional explicit symbol set (volume + score filters still apply)                                    |\n| `[rampage.score]`    | `mode` + `params`                        | `candle_height` (`candle_count`/`min_candle_pct`) or `tick_bps` (`min_tick_bps`)                     |\n| `[rampage.strategy]` | `kind` + `params`                        | `wave` or `tide` lattice params forwarded to every spawned bot                                       |\n\nTo run a **fixed bot list** instead, drop `[rampage]` and add `[[bots]]` entries\n(one per symbol/strategy). Re-read the warning above before pointing any of this\nat real funds.\n\n### Run live (testnet first!)\n\n```bash\n# Multi-bot orchestrator (config-driven; testnet env in config.toml first!)\ncargo run --release --bin tikr -- --config config.toml\n\n# Single-symbol Binance Spot smoke test (example)\ncargo run --release --example run_spot -- \\\n  --env spot-testnet --symbol BTCUSDT --minutes 5\n```\n\nAuth lives in `.env` (gitignored). Use Ed25519 PEM for spot (mandatory) or HMAC\nfor futures — see `.env.example`.\n\n## Contributing\n\nSee the org-wide\n[CONTRIBUTING guide](https://github.com/kryptic-sh/.github/blob/main/.github/CONTRIBUTING.md).\nPhase 0 is design-heavy — comment on open design issues before opening PRs.\n\nFor security issues, see the org-wide\n[SECURITY policy](https://github.com/kryptic-sh/.github/blob/main/.github/SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptic-sh%2Ftikr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkryptic-sh%2Ftikr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkryptic-sh%2Ftikr/lists"}