# 1. Call a paid endpoint without payment
POST /v1/search
{ "bbox": [8.9, 44.4, 9.0, 44.5], "datetime": "2025-01-01/2025-12-31" }

// → HTTP 402
{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [{
    "scheme":   "exact",
    "network":  "solana-devnet",
    "asset":    "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",  // USDC mint
    "payTo":    "ALpKsLNWqg3iPYz13b5ZqExESK4BGsDni9ASszLA7N5K",  // treasury
    "maxAmountRequired": "50000",  // 0.05 USDC (6 decimals)
    "resource": "/v1/search"
  }]
}

# 2. Client signs USDC transfer, re-sends with X-PAYMENT header
POST /v1/search
X-PAYMENT: <base64-encoded Solana transaction>
{ "bbox": [8.9, 44.4, 9.0, 44.5], "datetime": "2025-01-01/2025-12-31" }
// → HTTP 200 with search results

// Escrow lifecycle

1. lock_funds    → Buyer's USDC → escrow PDA vault
                   Stores: order_id, amount, buyer, seller, expiry_ts

2. release_funds → Escrow vault → treasury (on successful delivery)
                   Requires: delivery_proof_hash (image manifest SHA-256)
                   Must happen before expiry

3. refund_expired → Escrow vault → buyer (if delivery fails)
                    Only callable after expiry_ts passes

# TLSNotary prove endpoint (internal sidecar, port 8090)
POST /prove
{
  "url": "https://earth-search.aws.element84.com/v1/collections/sentinel-2-l2a/items/S2A_...",
  "image_hash": "593674d2b62d017d07b41a24b6bfa9d7..."
}

// → Response
{
  "mpc_tls":            true,
  "presentation_hash":  "32bd574b0a1288...",   // SHA-256 of verified transcript + domain
  "provider_domain":    "earth-search.aws.element84.com",
  "binding_hash":       "8dfe6f11437103...",   // sha256(image_hash || tlsn_hash || scene_id_hash)
  "revealed_recv_bytes": 18984,              // bytes of TLS transcript revealed
  "scene_id":           "S2A_T32TQM_20250115T103251_L2A",
  "lat": 44.4, "lon": 8.9,
  "capture_timestamp":  1742054400
}

// RISC Zero guest output (committed to journal, public on-chain)
{
  "image_hash":      [u8; 32],    // SHA-256 of delivered image
  "provenance_valid": true,        // all 3 checks passed
  "aoi_center_lat":   44400000,   // × 1e6
  "aoi_center_lon":   8900000,    // × 1e6
  "tlsnotary_hash":   [u8; 32],    // TLSNotary presentation hash
  "binding_hash":     [u8; 32]     // sha256(image || tlsn || scene_id)
}

// Guest compiled to RISC-V ELF (220 KB)
// IMAGE_ID: 2c8c4671fc085bd1d54580eb986671bd790f13ad8f1cc09d30649e5d1c5033bd
// Registered with Bonsol on Solana devnet

Provider TLS  →  TLSNotary (MPC-TLS)  →  RISC Zero zkVM  →  Bonsol (Groth16)  →  Solana

Step 1: Provider HTTPS API response authenticated via real MPC-TLS
        → presentation_hash = SHA-256(verified_transcript || domain)

Step 2: RISC Zero guest verifies: TLSNotary hash match + AOI check + time window
        → STARK proof of correct execution

Step 3: Bonsol wraps STARK → Groth16 SNARK (constant-size, cheap to verify on-chain)

Step 4: eo_provenance program stores attestation on Solana:
        → image_hash, binding_hash, tlsnotary_hash, scene_id, coordinates, timestamp

Binding hash: sha256(image_hash || tlsnotary_hash || scene_id_hash)
               Ties the image file to its provenance proof — anyone can recompute and verify

// The flywheel

  Agent pays USDC  →  x402 / escrow  →  Treasury PDA  →  sweep_to_openrouter
        ↑                                                        ↓
        └──── AI-powered search, chat, MCP tools ←── OpenRouter credits

// Treasury instructions
receive_fee(order_id, fee_amount)       // 2.5% platform fee from each order
sweep_to_openrouter(amount)             // USDC → OpenRouter wallet when threshold hit
set_sweep_threshold(new_threshold)      // governance (authority only)

// Treasury wallet
ALpKsLNWqg3iPYz13b5ZqExESK4BGsDni9ASszLA7N5K

# 1. Sign up
POST /v1/auth/signup
{ "email": "you@company.com", "password": "SecurePass10+", "name": "Your Name" }
// → { "access_token": "eyJ...", "user": { ... } }

# 2. Create an API key (recommended for production)
POST /v1/keys
{ "name": "CI/CD pipeline", "type": "live" }
// → { "full_key": "eor_live_sk_a1b2c3..." }  ← save this! shown ONCE

# 3. Use in all requests
Authorization: Bearer eor_live_sk_a1b2c3...

POST /v1/search

{
  // Spatial — GeoJSON Polygon, max 10,000 km²
  "intersects": { "type":"Polygon", "coordinates": [...] },
  "datetime": "2026-03-01T00:00:00Z/2026-03-21T23:59:59Z",

  // CQL2-JSON filter
  "filter": {
    "op": "and",
    "args": [
      { "op": "<=", "args": [{ "property": "eo:cloud_cover" }, 20] },
      { "op": "<=", "args": [{ "property": "gsd" }, 1.0] }
    ]
  },
  "filter-lang": "cql2-json",

  // EO Router extensions
  "eorouter:providers":      ["planet", "iceye", "cdse"],
  "eorouter:sensor_types":   ["optical", "sar"],
  "eorouter:routing":        "sar_fallback_if_cloud",
  "eorouter:cloud_threshold":20,
  "eorouter:max_price":      200,
  "limit": 20
}

GET /v1/collections?provider=iceye&sensor_type=sar&limit=20
GET /v1/collections/iceye_spotlight_grd

POST /v1/orders
{
  "type": "archive",
  "items": [{ "scene_id": "ps_20260315_..." }],
  "processing": { "format": "COG", "clip_to_aoi": true, "aoi": {...} },
  "delivery": { "type": "s3", "destination_id": "dest_prod" },
  "license_accepted": true,
  "confirm": true   // false = estimate only
}
// → 202 { "order_id": "ord_7e2a1b4d", "status": "queued", "amount_eur": 89.4 }

// Step 1: feasibility (free, no charge)
POST /v1/tasking/feasibility
{
  "aoi": { ... },
  "time_window": { "from": "2026-03-22T00:00:00Z", "to": "2026-03-28T23:59:59Z" },
  "requirements": { "sensor_type": "sar", "max_gsd_m": 1.0, "orbit_direction": "ascending" },
  "providers": ["iceye", "capella", "umbra"],
  "priority": "standard",  // standard (1x) | priority (1.75x) | rush (3x)
  "budget_cap": 2000       // optional: max EUR per opportunity
}

// Step 2: order from opportunity_id
POST /v1/tasking/orders
{
  "opportunity_id": "topp_iceye_...",
  "estimated_eur": 1240.5,  // from feasibility response
  "confirm": true                 // false = estimate only
}

POST /v1/subscriptions
{
  "name": "port-genoa-sar",
  "aoi": { ... },
  "filter": { "sensor_types": ["sar"], "max_gsd_m": 3.0 },
  "providers": ["iceye", "cdse"],
  "auto_order": true,
  "auto_order_config": {
    "delivery_destination_id": "dest_prod",
    "max_eur_per_match": 200,
    "daily_eur_cap": 500
  }
}

// Pause/resume
PATCH /v1/subscriptions/{id}
{ "status": "paused" }

POST /v1/credentials
{
  "provider": "planet",
  "type": "api_key",
  "name": "Production Planet key",
  "value": "PLAKxxxxxxxxxxxxxxxx"
}

// For OAuth2 providers (ICEYE, Airbus, SentinelHub):
POST /v1/credentials
{
  "provider": "iceye",
  "type": "oauth2_client",
  "name": "ICEYE production",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

// Amazon S3
POST /v1/destinations
{
  "name": "Production S3",
  "type": "s3",
  "bucket": "my-imagery-bucket",
  "region": "eu-west-1",
  "access_key_id": "AKIA...",
  "secret_access_key": "wJa...",
  "path_template": "imagery/{date}/{scene_id}.tif"
}

// Google Cloud Storage
{ "type": "gcs", "bucket": "...", "service_account_json": "{...}" }

// Azure Blob Storage
{ "type": "azure_blob", "container": "...", "connection_string": "..." }

// Platform (download from dashboard — no config needed)
{ "type": "platform", "name": "Dashboard download" }

POST /v1/webhooks
{
  "url": "https://your-server.com/hooks/eorouter",
  "event_types": ["order.completed", "order.failed", "tasking.acquired"]
}
// → { "signing_secret": "whsec_a1b2c3..." }  ← save this! shown ONCE

import hmac, hashlib

def verify_webhook(payload: bytes, header: str, secret: str) -> bool:
    # header format: "t=1711234567,v1=a1b2c3d4..."
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(
        secret.encode(), f'{parts["t"]}.'.encode() + payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

GET /v1/jobs/{job_id}

{
  "job_id": "job_8f3a2b1c",
  "status": "completed",
  "events": [
    { "type": "job_created",   "time": "10:31:00Z", "message": "89.4 Cr pre-authorized" },
    { "type": "provider_queued", "time": "10:31:08Z", "message": "ICEYE order queued" },
    { "type": "job_completed",  "time": "11:04:32Z", "message": "87.3 Cr captured for 10.9 km²" }
  ]
}

GET /v1/providers

{ "providers": [{ "id": "iceye", "status": "operational", "uptime_30d": 99.2, "tasking": true, "byok": true }] }

POST /v1/embeddings
{
  "bbox": [11.34, 44.49, 11.36, 44.50],  // max ~100 km²
  "year": 2024,                              // 2017-2025
  "resolution": 10                           // meters (10m native)
}

// Response
{
  "bbox": [11.34, 44.49, 11.36, 44.50],
  "year": 2024,
  "resolution": 10,
  "dimensions": 64,
  "pixel_count": 22,
  "pixels": [
    { "lon": 11.3405, "lat": 44.4995, "embedding": [0.12, -0.34, ...] },
    // ... 64 floats per pixel
  ]
}

POST /v1/lgnd/search
{
  "latitude": 37.77,
  "longitude": -122.42,
  "top_k": 5,
  "start_date": "2022-01-01",
  "end_date": "2022-12-31"
}

// Response
{
  "query": { "latitude": 37.77, "longitude": -122.42, "top_k": 5 },
  "results": [
    { "chip_id": "naip_ca_2022_abc123", "score": 0.94, "metadata": {...} }
  ],
  "distance_metric": "cosine"
}

POST /v1/lgnd/search-by-chip
{
  "chip_id": "naip_ca_2022_abc123",
  "top_k": 10
}

POST /v1/lgnd/changes
{
  "geometry": { "type": "Polygon", "coordinates": [[...]] },
  "positive_texts_past": ["empty field"],
  "positive_texts_current": ["new construction"],
  "negative_texts_past": ["forest"],
  "negative_texts_current": ["forest"],
  "positive_chip_ids_past": ["chip_id_example"],
  "positive_chip_ids_current": ["chip_id_example"],
  "negative_chip_ids_past": [],
  "negative_chip_ids_current": [],
  "top_k": 10
}

// Response — changed chip pairs
{
  "results": [
    { "chip_past": "s2_2024_a1", "chip_current": "s2_2025_a1", "cell_id": "cell_42", "score": 0.87 }
  ],
  "distance_metric": "cosine"
}

POST /v1/lgnd/filter
{
  "geometry": { "type": "Polygon", "coordinates": [[...]] },
  "start_date": "2022-01-01",
  "limit": 100
}

// Response — chip IDs ordered by capture date
{
  "chips": ["naip_ca_2022_abc123", "naip_ca_2022_abc124"],
  "total": 2
}

GET /v1/credits/balance
// → { "balance_eur": 348.60, "reserved_eur": 89.40, "available_eur": 259.20 }

GET /v1/credits/transactions?limit=20

// Cost formula:
cost_eur = price_eur_per_km2 * clipped_area_km2 * 1.025  // 2.5% platform fee

// BYOK routing fee:
routing_fee = max(area_km2 * 0.10, 0.50)  // EUR

from pystac_client import Client

catalog = Client.open(
    "https://api.eorouter.io/v1",
    headers={"Authorization": f"Bearer {os.environ['EOR_API_KEY']}"}
)
items = catalog.search(intersects=aoi, datetime="2026-03-01/2026-03-21").get_items()

// Set your country code
PATCH /v1/auth/me
{ "country_code": "US" }

// Non-US users ordering Maxar WV-3 will get:
// 403 { "code": "itar_restriction", "message": "...ITAR-controlled..." }

from eorouter import EoRouterClient
client = EoRouterClient(api_key="...")

before = client.search(aoi=aoi, date_from="2026-01-01", date_to="2026-01-31",
                     max_cloud_cover=15, limit=1)[0]
after  = client.search(aoi=aoi, date_from="2026-03-01", date_to="2026-03-21",
                     max_cloud_cover=15, limit=1)[0]

order = client.orders.create(
    scene_ids=[before.scene_id, after.scene_id],
    processing={"format":"COG", "clip_to_aoi":True, "aoi":aoi},
    delivery={"type":"s3", "destination_id":"dest_prod"},
    confirm=True)

order.wait(timeout_minutes=90)
print([i["s3_key"] for i in order.manifest()["items"]])

opps = client.tasking.feasibility(
    aoi=aoi,
    time_window={"from":"2026-03-22T00:00:00Z", "to":"2026-03-27T23:59:59Z"},
    requirements={"sensor_type":"sar", "min_gsd_m":3.0, "orbit_direction":"ascending"},
    providers=["iceye", "capella"], priority="standard"
)
best = min(opps, key=lambda o: o["estimated_eur"])
task = client.tasking.order(opportunity_id=best["opportunity_id"], confirm=True)
# Webhooks: tasking.confirmed → tasking.acquired → order.completed

sub = client.subscriptions.create(
    name="genoa-port-sar", aoi=port_aoi,
    filter={"sensor_types":["sar"], "max_gsd_m":3.0},
    providers=["iceye", "cdse"],  # cdse = Sentinel-1, free
    auto_order=True,
    auto_order_config={
        "delivery_destination_id": "dest_prod",
        "processing": {"format":"COG", "clip_to_aoi":True},
        "max_eur_per_match": 300, "daily_eur_cap": 600,
    })

// Claude Desktop (MCP connected) conversation:

User: "Find best SAR over Suez Canal last 72h, ascending orbit,
       cheapest, order it."

Claude calls:
  eo_search(aoi=suez, sensor_types=["sar"], days=3, routing="cheapest_matching")
  eo_get_balance()
  eo_order_archive(scene_ids=["iceye_..."], confirm=False)  // estimate first

Claude: "Found ICEYE Stripmap (3m, ascending, 8h ago) — €312.00.
         Your balance is €1,240. Shall I place the order?"

User: "Yes, confirm it."

Claude calls:  // MCP clients can set allow_orders in their implementation
  eo_order_archive(scene_ids=["iceye_..."], confirm=True)
  eo_get_order_status(order_id="ord_...")

Claude: "Order placed. ICEYE scene queued for delivery to
         s3://your-bucket/... — €312.00 charged."

POST /v1/chat
{
  "message": "Find Sentinel-2 images over Paris from last week with less than 20% cloud cover",
  "conversation_id": null,       // optional, for multi-turn
  "allow_orders": false          // see Order Safety below
}

// Response
{
  "response": "I found 8 Sentinel-2 scenes over Paris from the last 7 days...",
  "tool_calls": [
    { "tool": "eo_search", "result_summary": "8 scenes found" }
  ],
  "conversation_id": "conv_abc123",
  "beta": true
}

// Step 1: User asks to order — AI returns estimate (allow_orders=false, default)
POST /v1/chat
{ "message": "Order that Sentinel-2 scene over Paris" }
// → AI calls eo_order_archive(confirm=false), returns estimate + _requires_approval

// Step 2: Your app shows the estimate, user clicks "Confirm"

// Step 3: Re-send with allow_orders=true
POST /v1/chat
{ "message": "Yes, confirm the order", "allow_orders": true }
// → AI places the order, charges EUR balance