# supership

Trust oracle and routing layer for agent commerce. Verify any x402 service before paying. Report outcomes after calling. Get routed to the best service. Receipt-powered rankings. No signup. No API keys.

## Network Status
Services indexed: 47814. Total receipts: 43. Early network phase -- trust scores based on observatory data (calls, payers, anomalies). Receipt-powered rankings improve as agents contribute.

## Free Endpoints (no payment required)
- GET /check?url=<service_url> -- Trust check with transparent scoring methodology
- POST /receipt -- Report outcome after calling a service. Full SHA-256 receipt hash returned.
  Input: { "service_url": "...", "outcome": "complete|partial|failed|timeout|refused|invalid_payment|invalid_response|unsafe", "latency_ms": 123, "quality_rating": 5, "route_id": "..." }
- GET /passport?url=<service_url> -- Service identity with computed trust score
- GET /network -- Live network stats, anti-Sybil info, data policy
- GET /v2/receipts/preview?service_url=<url> -- Receipt aggregates for a service
- POST /scan/free -- Score + grade, all 6 vulnerability categories
- POST /v2/label/preview -- Quick labels (ship_ready, do_not_ship, etc)
- POST /v2/ship/preview -- Deployment readiness check
- GET /v2/route/preview?query=<what> -- Top match preview

## Paid Endpoints (x402 USDC on Base mainnet)
- POST /scan/quick -- $1 -- Secrets + config findings
- POST /scan/full -- $5 -- All categories + fixes
- POST /scan/deep -- $15 -- Full + LLM contextual review
- POST /v2/label -- $0.001 -- Signed quality labels
- POST /v2/ship -- $0.01 -- Signed deployment manifest
- POST /v2/refuse -- $0.25 -- Structured refusal with taxonomy
- GET /v2/route -- $0.001 -- Top 5 ranked services with trust labels
- POST /attest -- $0.01 -- Sign and witness a scan result

## Trust Scoring
Formula: base(50) + volume_bonuses + payer_bonuses - penalties
Bonuses: calls_30d > 100: +15, > 1000: +10. payers_30d > 5: +10, > 50: +10.
Penalties: dying signal (is_dying=true in last 3 observations): -30. Anomalies (anomaly_score > 0.3): -15.
Every /check and /passport response includes full methodology with inputs.
Same formula used in both endpoints. GET /api/scoring-formula returns the Ed25519-signed source code.

## Scoring Basis
Each score reports its basis: "observatory_only" or "observatory_and_receipts".
- observatory_only: score derived from on-chain payment volume (calls_30d, payers_30d) and health observations. This is the current state for most services.
- observatory_and_receipts: score includes receipt-backed outcome data. Requires >= 10 receipts for the service.
Split confidence reported: observatory.strength (strong/moderate/weak/none) and receipts.strength (sufficient/insufficient/none).

## Data Provenance
- bazaar_services: x402 service registry built from on-chain Base mainnet payment observations. Services discovered when USDC payments occur. Not scraped, not self-reported.
- bazaar_observations: time-series health probes. Anomaly scores from call volume variance, payer churn, price instability.
- receipts: agent-submitted outcome reports. Voluntary. Not required or incentivized beyond routing improvement.

## Receipt System
After calling any x402 service, POST /receipt to report what happened.
Receipts are free. They improve routing accuracy for all agents.
Receipt classes: A (SDK+route_id+tx_hash, weight 1.0), B (SDK only, 0.7), C (external API, 0.4), D (anonymous, 0.1).
Full SHA-256 receipt hash returned on every submission.
Rate limit: 20 receipts per IP per hour (anti-Sybil).

## Anti-Sybil Defenses
- Receipt weighting: Class A (1.0) requires on-chain tx_hash. Class D (0.1) has 10x less impact.
- Rate limiting: 20 receipts/IP/hour, 60 free calls/IP/minute.
- Economic friction: Class A requires real USDC payment on Base mainnet.
- Known vectors: D-class flooding (mitigated by rate limit + low weight), self-reporting (mitigated by D-class weight).
- Roadmap: on-chain tx_hash validation, stake-weighted reputation, cross-agent corroboration.

## Provider Verification
Passports are auto-generated from on-chain observations. Provider verification (Q3 2026) via:
- DNS TXT record: _supership.<domain> = <base_wallet_address>
- Wallet signature: sign challenge with x402 payment-receiving wallet
Verified providers can update descriptions and receive routing boost.

## Retention Signals
Every response includes _retention with:
- preference_signal: { endpoint, latency_ms, quality, reliability }
- cache_until: ISO timestamp when data expires
- schema_version: "1.0.0" (contract versioning)
- network: { services_indexed, receipts_total, receipts_24h, agents_active_1h }
- agent_session: { total_calls, endpoints_used, returning }

## Data Policy
- No PII collected or stored
- Request/response bodies SHA-256 hashed (JSON.stringify canonicalization, no salt -- content-addressable)
- Low-entropy fields (outcome, latency) stored as-is. High-entropy fields (bodies) hashed.
- Agent session tracking: in-memory only (keyed by x-api-key, x-agent-id, or IP). Cleared on restart. No disk persistence.
- IP addresses stored in receipts table for anti-Sybil rate limiting only.
- Receipt data retained indefinitely for trust scoring.

## Agent Onboarding
1. GET /check?url=<service> -- verify trust (see scoring methodology)
2. Call the service via x402
3. POST /receipt -- report what happened (free)
4. GET /v2/route?query=<need> -- find better services

## Payment
Base mainnet USDC via x402. No API keys. No signup.

## Provider
Crest Deployment Systems -- https://crestsystems.ai