BlockFlash

BlockFlash is a modernized, read-only cross-exchange spread scanner and simulation tool. It monitors public order books from Exmo and Kraken, calculates volume-weighted average price (VWAP) fills across order book depth, and evaluates hypothetical taker-to-taker arbitrage opportunities.

Safety and Simulation Notice

BlockFlash is strictly a read-only analysis and simulation tool:

• It queries only public market data endpoints.
• It does not authenticate with any exchange API.
• It never places orders, executes trades, manages positions, or transfers funds.
• It requires no API keys, private secrets, or account credentials.

All spread and profit calculations reflect simulated scenarios based on public order book snapshots. BlockFlash does not provide trading advice or guarantee execution profits.

Quote Currency and Stablecoin Basis Risk

• Exmo's BTC_USD market is inactive. BlockFlash uses BTC_USDC on Exmo as the default pair.
• Kraken's default market is XBTUSD (fiat USD).
• BlockFlash treats USDC and USD as equivalent 1:1 quote currencies for spread calculations.
• Stablecoin basis risk (depegging, conversion spreads, redemption fees, banking friction) makes all output strictly illustrative.

Prerequisites

• .NET 10.0 SDK.

To verify your .NET installation:

dotnet --version

Building and Testing

BlockFlash uses the modern solution file BlockFlash.slnx.

Restore Dependencies

dotnet restore BlockFlash.slnx

Build the Solution

dotnet build BlockFlash.slnx --no-restore

Run Tests

The project includes an offline unit test suite for pricing, API payload parsing, and CLI behavior.

dotnet test BlockFlash.slnx --no-build

Running the Scanner

You can run the scanner directly with the .NET CLI.

Default Continuous Polling Mode

By default, BlockFlash polls both exchanges every 30 seconds until stopped:

dotnet run --project src/BlockFlash

Press Ctrl+C at any time to gracefully shut down the scanner (returns exit code 0).

Single Evaluation Mode (--once)

Run a single market data snapshot evaluation and immediately exit:

dotnet run --project src/BlockFlash -- --once

Display Help

dotnet run --project src/BlockFlash -- --help

Command-Line Configuration

All options use culture-invariant parsing.

Option	Argument Format	Default	Description
--size	<btc>	0.05	Target base-asset quantity in BTC. Must be greater than 0.
--interval	<seconds>	30	Delay between evaluation cycles in continuous mode. Must be greater than 0.
--depth	<levels>	100	Order book depth requested from each exchange. Allowed range: 1 to 500.
--transfer-fee-btc	<btc>	0	Additional BTC bought on the buy exchange to cover network withdrawal/transfer fees. Must be 0 or greater.
--exmo-taker	<rate>	0.003	Exmo taker fee rate as a decimal fraction in [0, 1). 0.003 represents 0.30%.
--kraken-taker	<rate>	0.004	Kraken taker fee rate as a decimal fraction in [0, 1). 0.004 represents 0.40%.
--once	flag	disabled	Runs a single evaluation cycle, then exits immediately.
--help	flag	disabled	Displays CLI help and usage information, then exits.

Example CLI Command

Scan for 0.25 BTC with 0.0005 BTC transfer buffer, custom taker fees, and 200 depth levels once:

dotnet run --project src/BlockFlash -- --size 0.25 --transfer-fee-btc 0.0005 --exmo-taker 0.0025 --kraken-taker 0.0035 --depth 200 --once

Exit Codes

BlockFlash returns the following exit codes:

• 0: Success, help display (--help), or graceful shutdown via Ctrl+C.
• 2: Usage error (invalid CLI arguments, unknown flags, or out-of-range numeric inputs).
• 3: Market data or order book depth failure when running in --once mode.

In continuous mode, temporary network or market data errors log a diagnostic message to standard error and retry on the next interval without crashing.

Calculations and Formulas

BlockFlash performs level-by-level depth walking with exact decimal arithmetic to account for price slippage across order book layers.

1. Order Book Depth Walk

For a buy leg, BlockFlash walks the ask order book in ascending price order until reaching the required volume (targetQuantity + transferFeeQuantity). For a sell leg, BlockFlash walks the bid order book in descending price order until reaching targetQuantity.

For each consumed level $i$ with price $P_i$ and matched volume $Q_i$:

$$\text{Gross Notional} = \sum (P_i \times Q_i)$$

$$\text{VWAP} = \frac{\text{Gross Notional}}{\text{Filled Quantity}}$$

If either book has insufficient liquidity to satisfy the requested quantity, an InsufficientDepthException is raised.

2. Fee Adjustments

• Buy Leg: $$\text{Buy Quantity} = \text{Target Quantity} + \text{Transfer Fee Quantity}$$ $$\text{Buy Taker Fee} = \text{Gross Notional}{\text{buy}} \times \text{Taker Rate}{\text{buy}}$$ $$\text{Buy Cost (Total After Fee)} = \text{Gross Notional}_{\text{buy}} + \text{Buy Taker Fee}$$

• Sell Leg: $$\text{Sell Quantity} = \text{Target Quantity}$$ $$\text{Sell Taker Fee} = \text{Gross Notional}{\text{sell}} \times \text{Taker Rate}{\text{sell}}$$ $$\text{Sell Proceeds (Total After Fee)} = \text{Gross Notional}_{\text{sell}} - \text{Sell Taker Fee}$$

Note on Transfer Fees: The transfer fee volume is purchased and paid for on the buy leg, but it is not sold on the destination exchange. This accurately models burning base currency in transfer fees.

3. Spread Profitability

$$\text{Total Profit} = \text{Sell Proceeds} - \text{Buy Cost}$$

$$\text{Profit Per BTC} = \frac{\text{Total Profit}}{\text{Target Quantity}}$$

A direction is labelled PROFITABLE when $\text{Total Profit} > 0$, and UNPROFITABLE otherwise.

Example Output

The output below is a representative example:

BlockFlash 1.0 - READ-ONLY cross-exchange spread scanner (simulation).
Reads public order books from Exmo and Kraken and simulates taker fills locally.
It never places orders, never uses credentials, and never touches private endpoints.
Quote note: Exmo BTC_USDC is a USDC proxy; Kraken XBTUSD is USD; the two are
treated as equivalent quote currencies for this simulation.

2026-08-25T12:00:00Z
BUY Exmo -> SELL Kraken | target 0.05 BTC | buy VWAP 95200.5 | sell VWAP 95650.0 | total profit -10.935075 | profit per BTC -218.7015 | UNPROFITABLE
BUY Kraken -> SELL Exmo | target 0.05 BTC | buy VWAP 95680.0 | sell VWAP 95150.0 | total profit -59.9085 | profit per BTC -1198.17 | UNPROFITABLE

Limitations and Operational Constraints

• Read-Only / No Execution: BlockFlash does not place orders, lock prices, or execute hedges.
• Stablecoin Peg Assumption: Assumes 1 USDC equals 1 USD. Currency divergence creates basis risk.
• REST API Latency and Staleness: Order books are polled via public REST endpoints. Market conditions may change between request initiation and response processing.
• API Rate Limits: Aggressive polling intervals may trigger HTTP rate limiting (429) or IP throttling from public exchange gateways.
• Concurrent Execution Risk: In real trading, legs cannot be executed atomically across independent exchanges. Slippage, partial fills, transfer delays, and network latency introduce substantial risk.

Security Notice

• BlockFlash does not require or accept API keys or private credentials.
• Historical repository commits contained a hardcoded Exmo API credential. Treat it as compromised and revoke it if that has not already been done.
• Do not commit API keys or private secrets to this repository.

Project Structure

BlockFlash/
|-- BlockFlash.slnx                 # Solution configuration
|-- src/
|   `-- BlockFlash/
|       |-- BlockFlash.csproj       # Main console project (net10.0)
|       |-- Program.cs              # Entry point and cancellation handling
|       |-- Cli/                    # CLI parsing, options, text, and runner
|       |-- MarketData/             # Order book data models and contracts
|       |-- Pricing/                # VWAP depth walking and fee calculators
|       `-- Providers/              # HTTP clients for Exmo and Kraken
`-- tests/
    `-- BlockFlash.Tests/
        |-- BlockFlash.Tests.csproj # Test project (net10.0, xUnit)
        |-- Cli/                    # Tests for CLI options and formatting
        |-- Pricing/                # Tests for pricing and fee models
        |-- Providers/              # Tests for API response deserialization
        `-- TestInfrastructure/     # HTTP mock handlers

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).