AgentMarginRouter

# Agent Margin Router

[![Live API](https://img.shields.io/badge/API-live-22c55e)](https://agent-margin-router-production.up.railway.app/health)
[![Docs](https://img.shields.io/badge/docs-landing%20page-06b6d4)](https://agentmarginrouter.com)
[![x402](https://img.shields.io/badge/payments-x402%20%7C%20USDC%20%2B%20USDT%20on%20Base-8b5cf6)](https://www.x402.org)
[![Python](https://img.shields.io/badge/python-3.11%2B-3776ab)](#)
[![Tests](https://img.shields.io/badge/tests-80%20passing-22c55e)](#9-tests--projektstruktur)

> **EN — TL;DR:** Pay-per-request data broker for AI agents. One API, 7 upstream providers, automatic routing by quality × cost × latency, paid with **x402 micropayments (USDC or USDT on Base)** — no account, no API key, no subscription. 3 free requests per wallet.
>
> - **Live API:** `https://agent-margin-router-production.up.railway.app`
> - **Docs & examples:** https://agentmarginrouter.com
> - **Endpoints:** `POST /extract-clean` (URL → clean JSON, $0.02) · `POST /market-spread` (net spread between two venues after fees, $0.05) · `GET /health` (free)
>
> ```bash
> # Try it free (3 requests per wallet):
> curl -X POST https://agent-margin-router-production.up.railway.app/market-spread \
>   -H "Content-Type: application/json" -H "X-WALLET: 0xYourWallet" \
>   -d '{"asset":"ethereum","buy_venue":"binance","sell_venue":"coinbase"}'
> ```
>
> Full German documentation below · Vollständige deutsche Dokumentation folgt.

> Einheitliche, per **x402** bezahlte Routing-Schicht für AI-Agenten.
> Mehrere Daten-Provider → automatische Auswahl (Qualität, Preis, Latenz, Ausfallrisiko) → normalisiertes JSON → Bezahlung pro Request in **USDC oder USDT auf Base**.

```text
Agent  ──POST /extract-clean──▶  Router ──▶ Provider-Scoring ──▶ bester Provider
  ▲                                │            (Fallback, Circuit-Breaker, Mindestmarge)
  │  402 Payment Required          │
  │  (USDC + USDT Optionen)        ▼
  └──X-PAYMENT (signiert)──▶  Facilitator /verify  ──▶ 200 OK + Daten  ──▶ /settle on-chain
```

## Inhalt

1. [Was ist der Agent Margin Router](#1-was-ist-der-agent-margin-router)
2. [Schnellstart (lokal ohne Docker)](#2-schnellstart-lokal-ohne-docker)
3. [Deployment mit Docker-Compose auf Hetzner](#3-deployment-mit-docker-compose-auf-hetzner)
4. [Cloudflare Tunnel Setup](#4-cloudflare-tunnel-setup)
4b. [Deployment auf Railway](#4b-deployment-auf-railway)
5. [Umgebungsvariablen](#5-umgebungsvariablen)
6. [API-Endpunkte mit Beispielen](#6-api-endpunkte)
6b. [Enterprise: API-Keys, Rate-Limiting, Usage & Stats](#6b-enterprise-api-keys-rate-limiting-usage--stats)
7. [x402 Payment Flow](#7-x402-payment-flow)
8. [Provider hinzufügen](#8-provider-hinzufügen)
9. [Tests & Projektstruktur](#9-tests--projektstruktur)

---

## 1. Was ist der Agent Margin Router

Der Router ist ein **B2B-Daten-Broker für Maschinen**. Ein AI-Agent stellt eine standardisierte Anfrage, der Router

1. prüft den Cache (Redis),
2. bewertet alle passenden Provider mit `score = quality × success_probability / (price + latency_risk)`,
3. führt den Request nur aus, wenn die **Mindestmarge** (Default 20 %) erhalten bleibt,
4. fällt bei Fehlern automatisch auf den nächsten Provider zurück (**Circuit-Breaker**: 3 Fehler → 5 Minuten Pause),
5. normalisiert die Antwort und liefert sie mit Aktualitäts- und Konfidenzangabe aus,
6. protokolliert Kosten, Provider und Marge als strukturierte JSON-Logs.

Bezahlt wird **pro Request** über das x402-Protokoll (HTTP 402). Akzeptiert werden von Anfang an **USDC und USDT auf Base**. Neue Wallets erhalten 3 kostenlose Requests (Free Tier, in Redis getrackt).

**MVP-Endpunkte:**

| Endpunkt | Funktion | Preis (Default) |
|---|---|---|
| `POST /extract-clean` | URL → sauberes, schema-konformes JSON | 0,02 USD |
| `POST /market-spread` | Netto-Spread zwischen zwei Handelsplätzen nach Gebühren, Slippage & Transfer | 0,05 USD |
| `GET /health` | Status, Redis, Provider, Uptime, Fehlerrate, Cache-Hit-Rate | kostenlos |

> **Provider (echte APIs):**
>
> | Name | Capability | Anbieter | Kosten/Call (Default) | Qualität |
> |---|---|---|---|---|
> | `apify_web_scraper` | extract | Apify Actor `apify/web-scraper` (Headless-Browser, optional Proxy) | ~0,005 USD (wird aus `usageTotalUsd` nachjustiert) | 0.90 |
> | `httpx_direct` | extract | direkter HTTP-Abruf, kein JS | ~0,0002 USD | 0.60 |
> | `binance_public` | market_data | Binance Public API `/ticker/24hr` (Bid/Ask) via `data-api.binance.vision` – `api.binance.com` ist regional geo-blockiert | 0 USD, kein Key | 0.95 |
> | `coinbase_public` | market_data | Coinbase Public API `/prices/{pair}/spot` | 0 USD, kein Key | 0.90 |
> | `coingecko` | market_data | CoinGecko `/simple/price`, `/coins/{id}/tickers`, optional `/market_chart` | 0 USD (Demo-Key, Rate-Limit) | 0.88 |
> | `defillama` | market_data | DeFi Llama `coins.llama.fi/prices/current/coingecko:{id}` (Referenzpreis) + `api.llama.fi/tvl/{slug}` (DEX-Tiefe) | 0 USD, kein Key | 0.75 |
> | `coinmarketcap` | market_data | CMC `/cryptocurrency/quotes/latest` (Fallback, nur Referenzpreis) | ~0,0004 USD (Credits) | 0.70 |
>
> Ohne gesetzten API-Key wird ein Provider **nicht geroutet** (`is_configured == False`), taucht aber in `/health` mit `configured: false` auf.
> Der **Free-Tier** nutzt nur Provider mit `cost_per_request <= FREE_TIER_MAX_PROVIDER_COST_USD` (Default 0,001 USD) – also `httpx_direct` bzw. `binance_public`/`coinbase_public`/`coingecko`/`defillama`; `/market-spread` holt dabei jedes Leg vom **eigenen Exchange-Feed** (Binance Bid/Ask, Coinbase Spot), wenn Binance oder Coinbase Teil des Venue-Paars ist; teure Provider sind für kostenlose Requests gesperrt.
> `/extract-clean` prüft Ziel-URLs gegen private/interne Netze (SSRF-Guard: nur http/https, keine RFC-1918-, Loopback-, Link-Local- oder Metadata-Adressen, Prüfung pro Redirect-Hop); abgelehnte URLs liefern `422` und zählen nicht als Provider-Fehler.
>
> **Einschränkung `/market-spread`:** Das Ergebnis ist eine **Analyse**, keine ausführbare Quote. Preise sind Last-Trade-Werte der Venue-Ticker (CoinGecko) bzw. ein Referenzpreis (CMC); „Liquidität“ wird aus 24h-Volumen und einem statischen Depth-Anteil je Venue geschätzt, nicht aus dem Orderbuch. Das Feld `data_source`/`venue_data_source` (`ticker`, `mixed`, `reference`) und `note` im Response kennzeichnen die Datenbasis.

---

## 2. Schnellstart (lokal ohne Docker)

Voraussetzungen: Python ≥ 3.11, optional ein lokaler Redis (ohne Redis nutzt die App im Dev-Modus automatisch einen In-Memory-Fallback).

```bash
git clone <dein-repo> agent_margin_router
cd agent_margin_router

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

cp .env.example .env
# Für lokale Tests ohne Wallet/Zahlung:
sed -i 's/^PAYMENT_ENABLED=.*/PAYMENT_ENABLED=false/' .env
sed -i 's#^REDIS_URL=.*#REDIS_URL=redis://localhost:6379/0#' .env

uvicorn app.main:app --reload --port 8000
```

Dann:

```bash
curl -s localhost:8000/health | jq .status
curl -s -X POST localhost:8000/extract-clean \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/produkt/123"}' | jq
```

Interaktive API-Doku: <http://localhost:8000/docs>

Tests:

```bash
pytest -q
```

---

## 3. Deployment mit Docker-Compose auf Hetzner

Getestet für einen Hetzner Cloud Server (CX22 reicht für den Start, Ubuntu 24.04).

### 3.1 Server vorbereiten

```bash
ssh root@<SERVER-IP>

# System aktualisieren, Docker installieren
apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh

# Nicht-Root-User für den Betrieb
adduser --disabled-password --gecos "" deploy
usermod -aG docker deploy

# Firewall: nur SSH offen lassen (HTTP kommt über Cloudflare Tunnel, s. Abschnitt 4)
apt install -y ufw
ufw allow OpenSSH
ufw --force enable
```

### 3.2 Projekt deployen

```bash
su - deploy
git clone <dein-repo> agent_margin_router
cd agent_margin_router

cp .env.example .env
nano .env        # RECEIVER_WALLET, ENVIRONMENT=production, REDIS_REQUIRED=true, Preise, Provider-Keys
```

Wichtige Produktionswerte in `.env`:

```dotenv
ENVIRONMENT=production
REDIS_URL=redis://redis:6379/0
REDIS_REQUIRED=true
PAYMENT_ENABLED=true
RECEIVER_WALLET=0xDeineEchteWallet
```

Starten:

```bash
docker compose up -d --build
docker compose ps
docker compose logs -f app
curl -s localhost:8000/health | jq
```

Der App-Port `8000` ist im Compose-File **nur auf 127.0.0.1** gebunden – von außen ist der Dienst ausschließlich über den Cloudflare Tunnel (oder einen eigenen Reverse Proxy) erreichbar.

### 3.3 Betrieb

```bash
docker compose pull && docker compose up -d --build   # Update
docker compose logs --tail=200 app                    # JSON-Logs
docker compose exec redis redis-cli INFO memory       # Redis prüfen
docker compose down                                   # Stoppen (Redis-Daten bleiben im Volume)
```

Beide Services haben Healthchecks und `restart: unless-stopped`; nach einem Server-Reboot startet der Stack automatisch.

---

## 4. Cloudflare Tunnel Setup

Mit einem Cloudflare Tunnel braucht der Hetzner-Server **keinen offenen HTTP-Port**; TLS, DDoS-Schutz und WAF übernimmt Cloudflare.

1. Domain bei Cloudflare verwalten (Nameserver umstellen).
2. Cloudflare Dashboard → **Zero Trust** → **Networks** → **Tunnels** → **Create a tunnel** (Typ „Cloudflared“).
3. Namen vergeben (z. B. `agent-margin-router`) und den angezeigten **Token** kopieren.
4. Im Tunnel unter **Public Hostname** einen Eintrag anlegen:
   - Subdomain: `api`, Domain: `deine-domain.tld`
   - Service: `HTTP` → `app:8000` (Docker-Servicename, da cloudflared im selben Compose-Netz läuft)
5. Token in `.env` eintragen:

   ```dotenv
   CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoi...
   ```

6. Stack mit Tunnel-Profil starten:

   ```bash
   docker compose --profile tunnel up -d
   docker compose logs -f cloudflared      # "Registered tunnel connection" = erfolgreich
   curl -s https://api.deine-domain.tld/health | jq .status
   ```

Empfohlen zusätzlich im Cloudflare-Dashboard: **Ra