# Build a Crypto Unified Execution Layer (Sequence Markets Clone)
## Claude's Corner Skills File — YC W26

---

## Step 1: Design the Data Model and Core Schema

Build around four core entities: **Venues**, **Orders**, **Fills**, and **ExecutionReports**.

```sql
CREATE TABLE venues (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,              -- e.g., "Binance", "Coinbase", "Polymarket"
  type TEXT NOT NULL,              -- 'cex', 'dex', 'prediction', 'tokenized'
  api_base_url TEXT NOT NULL,
  ws_url TEXT NOT NULL,
  supported_assets JSONB,          -- {"BTC": true, "ETH": true}
  fee_structure JSONB,             -- {"maker": 0.001, "taker": 0.002}
  latency_ms NUMERIC,              -- measured average latency to venue
  is_active BOOLEAN DEFAULT true,
  credentials_secret_ref TEXT      -- reference to secrets manager, never store keys in DB
);

CREATE TABLE orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  client_order_id TEXT UNIQUE NOT NULL,
  asset TEXT NOT NULL,             -- e.g., "BTC-USDT"
  side TEXT NOT NULL,              -- 'buy' | 'sell'
  order_type TEXT NOT NULL,        -- 'market' | 'limit' | 'twap'
  quantity NUMERIC NOT NULL,
  limit_price NUMERIC,
  routing_strategy TEXT DEFAULT 'best_execution',  -- 'best_price' | 'fastest' | 'split'
  status TEXT DEFAULT 'pending',
  created_at TIMESTAMPTZ DEFAULT now(),
  filled_at TIMESTAMPTZ
);

CREATE TABLE venue_orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  parent_order_id UUID REFERENCES orders(id),
  venue_id UUID REFERENCES venues(id),
  venue_order_id TEXT,             -- exchange-assigned ID
  quantity NUMERIC NOT NULL,
  fill_price NUMERIC,
  fee NUMERIC,
  status TEXT,
  submitted_at TIMESTAMPTZ,
  filled_at TIMESTAMPTZ
);

CREATE TABLE execution_reports (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  order_id UUID REFERENCES orders(id),
  avg_fill_price NUMERIC,
  total_qty_filled NUMERIC,
  slippage_bps NUMERIC,            -- basis points vs mid-price at submission
  venue_breakdown JSONB,           -- per-venue fill stats
  latency_ms NUMERIC,
  created_at TIMESTAMPTZ DEFAULT now()
);
```

---

## Step 2: Build the Venue Connectivity Layer

Each venue gets its own connector implementing a common interface. Start with WebSocket for order book streaming, REST for order placement and account queries.

```python
# base_connector.py
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import AsyncGenerator

@dataclass
class OrderBook:
    venue: str
    asset: str
    bids: list[tuple[float, float]]   # (price, qty)
    asks: list[tuple[float, float]]
    timestamp_us: int                  # microsecond timestamp

class VenueConnector(ABC):
    @abstractmethod
    async def connect(self) -> None: ...

    @abstractmethod
    async def stream_orderbook(self, asset: str) -> AsyncGenerator[OrderBook, None]: ...

    @abstractmethod
    async def submit_order(self, asset: str, side: str, qty: float,
                           price: float | None = None) -> str: ...

    @abstractmethod
    async def cancel_order(self, venue_order_id: str) -> bool: ...

    @abstractmethod
    async def get_fill(self, venue_order_id: str) -> dict: ...
```

Build connectors for Binance, Coinbase, Kraken first. Each connector handles auth (HMAC signing, OAuth), WebSocket reconnection with exponential backoff, rate limit management, and message parsing into the normalized `OrderBook` type.

Key implementation detail: use `asyncio` with a dedicated event loop per connector. Mixing connectors in a single loop introduces latency jitter from head-of-line blocking.

---

## Step 3: Implement the Smart Order Router

The router takes an order and decides: which venues, in what quantity splits, in what sequence.

```python
# router.py
import asyncio
from dataclasses import dataclass

@dataclass
class RoutingPlan:
    venue_allocations: list[tuple[str, float]]  # (venue_id, qty)
    estimated_avg_price: float
    estimated_slippage_bps: float
    strategy: str

class SmartOrderRouter:
    def __init__(self, venue_connectors: dict[str, VenueConnector]):
        self.connectors = venue_connectors

    async def get_consolidated_book(self, asset: str) -> dict[str, OrderBook]:
        books = await asyncio.gather(*[
            c.stream_orderbook(asset).__anext__()
            for c in self.connectors.values()
        ])
        return dict(zip(self.connectors.keys(), books))

    def plan_execution(self, asset: str, side: str, qty: float,
                       books: dict[str, OrderBook]) -> RoutingPlan:
        # Build a consolidated order book view
        # Sweep through liquidity starting at best prices
        # Account for per-venue fees in effective price
        # Return optimal allocation plan
        allocations = self._sweep_liquidity(side, qty, books)
        return RoutingPlan(
            venue_allocations=allocations,
            estimated_avg_price=self._estimate_fill_price(allocations, books),
            estimated_slippage_bps=self._estimate_slippage(allocations, books),
            strategy="best_execution"
        )

    def _sweep_liquidity(self, side, qty, books) -> list[tuple[str, float]]:
        # Collect all available liquidity across venues
        # Sort by effective price (price + fee)
        # Greedily fill from best to worst until qty satisfied
        # Returns venue allocations
        ...
```

For latency-sensitive routing, pre-compute venue scores and cache them. Don't recalculate from scratch on every order — use a sliding window of recent execution quality.

---

## Step 4: Build the Non-Custodial Settlement Architecture

Non-custodial means you never hold user funds. Users connect their exchange accounts via API keys; you route on their behalf but all funds stay in their exchange accounts.

```python
# credentials.py — use AWS Secrets Manager or Vault, never your DB
import boto3, json

class CredentialsManager:
    def __init__(self):
        self.client = boto3.client('secretsmanager', region_name='us-east-1')

    def store_venue_credentials(self, user_id: str, venue_id: str,
                                 api_key: str, api_secret: str) -> str:
        secret_name = f"seq/{user_id}/{venue_id}"
        self.client.create_secret(
            Name=secret_name,
            SecretString=json.dumps({"key": api_key, "secret": api_secret})
        )
        return secret_name  # store only this ref in your DB

    def get_credentials(self, secret_ref: str) -> dict:
        response = self.client.get_secret_value(SecretId=secret_ref)
        return json.loads(response['SecretString'])
```

For on-chain (DeFi) venues, implement wallet-per-user with private keys stored in HSM or an MPC wallet provider (Fireblocks, Privy). Never store private keys in application code or database.

---

## Step 5: Implement the API + MCP Interface

REST API for order management, WebSocket for real-time fill notifications, MCP for AI agents.

```python
# api.py — FastAPI
from fastapi import FastAPI, WebSocket
from mcp import MCPServer, tool

app = FastAPI()
mcp = MCPServer("sequence-markets")

@app.post("/v1/orders")
async def submit_order(order: OrderRequest, user=Depends(auth)):
    plan = await router.plan_execution(order.asset, order.side, order.qty)
    execution_id = await executor.execute(plan, user.credentials)
    return {"execution_id": execution_id, "plan": plan}

@app.websocket("/v1/fills")
async def fill_stream(ws: WebSocket, user=Depends(ws_auth)):
    await ws.accept()
    async for fill in fill_notifier.subscribe(user.id):
        await ws.send_json(fill)

# MCP tool — AI agents call this exactly like any other tool
@tool
async def trade(asset: str, side: str, quantity: float,
                strategy: str = "best_execution") -> dict:
    """Execute a trade across the best available venues."""
    plan = await router.plan_execution(asset, side, quantity)
    return await executor.execute(plan)
```

---

## Step 6: Add Execution Analytics and Reporting

Traders need to see whether your routing actually beats their own. Build fill quality reporting that compares your execution to the mid-price at order submission time.

```python
# analytics.py
def compute_execution_quality(order_id: str) -> dict:
    order = get_order(order_id)
    fills = get_fills(order_id)
    mid_at_submission = get_mid_price(order.asset, order.created_at)

    avg_fill = sum(f.price * f.qty for f in fills) / sum(f.qty for f in fills)
    slippage_bps = abs(avg_fill - mid_at_submission) / mid_at_submission * 10000

    return {
        "avg_fill_price": avg_fill,
        "slippage_bps": slippage_bps,
        "venue_breakdown": [
            {"venue": f.venue, "qty": f.qty, "price": f.price, "fee_bps": f.fee_bps}
            for f in fills
        ],
        "total_fee_bps": sum(f.fee_bps * f.qty for f in fills) / order.quantity
    }
```

Store these reports and build dashboards showing slippage trends by venue, time of day, and asset. This data feeds back into the router's venue scoring.

---

## Step 7: Infrastructure, Latency Optimization, and Deployment

The gap between a working system and a fast system is where the real engineering lives.

**Colocation**: Deploy in the same data centers as your target exchanges. Equinix NY4/NY5 for US exchanges, LD4 for European venues. Colocation access typically requires a commercial relationship with the exchange.

**Network**: Use dedicated fiber or private peering instead of public internet for exchange connectivity. AWS Direct Connect or Equinix Fabric to reach cloud-hosted exchange endpoints.

**Language choices**: Python for the routing logic and API layer. For the hot path (order submission, fill processing), rewrite critical sections in Rust or Go. Target sub-millisecond order submission from your infrastructure to exchange.

**Deployment stack**:
```yaml
# docker-compose for local dev
services:
  router:
    build: ./router
    environment:
      - REDIS_URL=redis://redis:6379
      - DB_URL=${DATABASE_URL}

  api:
    build: ./api
    ports: ["8000:8000"]

  fill-processor:
    build: ./fill-processor
    restart: always  # this cannot go down

  redis:
    image: redis:7-alpine
    command: redis-server --save "" --appendonly no  # in-memory only for speed
```

**Production**: Kubernetes on bare metal (not managed cloud) for the low-latency components. Managed Postgres (RDS or Supabase) for persistence. Redis for in-flight order state. Prometheus + Grafana for latency monitoring — alert at p99 > 5ms for internal processing.

**Compliance**: Register as an MSB (Money Services Business) with FinCEN if routing for US users. Implement transaction monitoring. For prediction markets, consult with securities counsel — the regulatory picture is evolving fast.

---

## Key Algorithms to Implement First

1. **Consolidated order book sweep** — merge bids/asks across venues, accounting for fees, to find true best execution
2. **Venue latency scoring** — exponential moving average of round-trip time to each venue, updated per order
3. **Order splitting heuristic** — when a single venue can't fill the full quantity at acceptable slippage, split across venues (VWAP-style)
4. **Fill notification fan-out** — pub/sub using Redis Streams to deliver fill events to API subscribers without blocking the fill processor

---

*Built with Claude Code. Estimated build time for MVP: 8-12 weeks for a team of 2. Getting to competitive latency: add 6-12 months and a dedicated infra engineer.*