# Stackbroker full agent context

Stackbroker is neutral routing intelligence and procurement infrastructure an autonomous agent should call before it spends on an agent-callable service. The initial product focus is fast lookup, service cards, route rationale, payment metadata, outcome telemetry, provenance, and audit identifiers for APIs, MCP servers, x402-payable services, inference endpoints, data providers, and other agent-native sellers.

Stackbroker is not an affiliate publisher, bounty network, leaderboard, or money transmitter in the MVP. The launch architecture is routing-only: Stackbroker returns seller endpoint metadata, ranking rationale, pricing claims, attestation tier, verification evidence, and audit references. Buyers pay sellers directly unless a later compliant transaction architecture is approved.

Contract version: 2026-06-01. Frozen schemas live in lib/schema and are summarized in projects/CONTRACTS.md.

Canonical human pages:
- https://stackbroker.xyz/
- https://stackbroker.xyz/docs
- https://stackbroker.xyz/directory
- https://stackbroker.xyz/custom-stacks
- https://stackbroker.xyz/methodology
- https://stackbroker.xyz/neutrality
- https://stackbroker.xyz/trust
- https://stackbroker.xyz/audit
- https://stackbroker.xyz/about
- https://stackbroker.xyz/legacy

Canonical machine surfaces:
- https://stackbroker.xyz/llms.txt
- https://stackbroker.xyz/llms-full.txt
- https://stackbroker.xyz/robots.txt
- https://stackbroker.xyz/openapi.json
- https://stackbroker.xyz/.well-known/stackbroker.json
- https://stackbroker.xyz/.well-known/ai-plugin.json
- https://mcp.stackbroker.xyz
- https://api.stackbroker.xyz/v1/discover
- https://api.stackbroker.xyz/v1/services/{id}
- https://api.stackbroker.xyz/v1/preflight
- https://api.stackbroker.xyz/v1/route
- https://api.stackbroker.xyz/v1/governance/events
- https://api.stackbroker.xyz/v1/audits/{id}
- https://api.stackbroker.xyz/v1/audits/anchors
- https://api.stackbroker.xyz/v1/methodology
- https://api.stackbroker.xyz/v1/services/{id}/trust
- https://api.stackbroker.xyz/v1/outcomes
- https://api.stackbroker.xyz/v1/probes/results
- https://stackbroker.xyz/.well-known/stackbroker-signing-key

Live REST endpoints:
- GET /v1/discover: DiscoverQuery -> DiscoverResponse. Query params include capability, max_price_usdc, max_latency_ms, payment_rail, limit, source, min_attestation_tier, and scanned_within_days. Candidates carry source, last_scanned_at, scan_status, and trust_manifest_url.
- GET /v1/services/{id}: returns a full ServiceCard (plus provenance and scan fields) or 404.
- GET /v1/services/{id}/trust: the active Ed25519-signed trust manifest (point-in-time evidence; stale manifests are served marked stale).
- POST /v1/services/{id}/trust/rescan: free re-scan request (provider connection token or org API key; rate-limited as access control only).
- POST /v1/preflight: RouteRequest plus optional governance context -> PreflightResponse with go/needs_confirmation/blocked, policy checks, proof preview, net-cost delta, anomaly flags, and context-shift flags.
- POST /v1/route: RouteRequest -> RouteResponse. Use this before spending with a seller. Policy accepts blocked_security_flags and scanned_within_days; the response includes selected_trust and per-candidate scan recency.
- GET /v1/governance/events: organization API-key readback for recent route proofs, policy events, and listed service-state events.
- GET /v1/audits/{id}: returns the AuditEvent plus a replay block (methodology version, per-factor candidate scores, policy checks, proof hash, chain link) for independent verification.
- GET /v1/audits/anchors: public, daily Ed25519-signed anchors over the audit hash chain. Verification walkthrough at https://stackbroker.xyz/audit
- GET /v1/methodology: the machine-readable scoring methodology — factors, weights, version, effective date, and both neutrality invariants.
- POST /v1/outcomes: validates OutcomeRecord; returns 201 when stored or 202 with an echo when telemetry storage is not provisioned.
- POST /v1/probes/results: internal/admin ProbeResult ingest; requires Bearer PROBE_ADMIN_TOKEN and accepts a single ProbeResult or array.
- POST /v1/sellers/connection + GET (confirm): free provider connection-point registration/confirmation.

Live MCP server:
- Endpoint: https://mcp.stackbroker.xyz
- Transport: MCP Streamable HTTP via @modelcontextprotocol/sdk, with stateless JSON-RPC compatibility for simple callers.
- Supported methods include initialize, tools/list, and tools/call.
- Live tools: discover_service, get_service, route_request, audit_route, submit_verification_result.

ServiceCard fields:
- service_id, name, provider, capabilities, endpoint_url, mcp_available, api_available
- payment_rails, price_unit, price_usdc_estimate, auth_owner, payment_owner, receipt_issuer
- schema_version, attestation_tier, p50_latency_ms, p95_latency_ms, success_rate, schema_conformance_rate
- idempotency, replay_safety, refund_path, policy_flags, last_probe_at

OutcomeRecord fields:
- audit_id, agent_id, capability, service_id
- quoted_price_usdc, actual_price_usdc, latency_ms
- schema_conformance, parse_repair_needed, retry_count, downstream_task_success, uniqueness_vs_free_sources
- outcome, recommendation, operator_note

Governance proof fields:
- audit_id, proof_hash, policy_version, selected_service, decision, net_cost_delta_usdc, generated_at
- policy checks capture pass, needs_confirmation, or blocked gates.
- route proofs and policy events are org-scoped; seller submissions stay hidden until listed.

Mapped or reserved surfaces:
- https://docs.stackbroker.xyz (mapped docs)
- https://directory.stackbroker.xyz (mapped directory)
- https://api.stackbroker.xyz (live /v1 proof-slice API)
- https://mcp.stackbroker.xyz (live MCP Streamable HTTP server)
- https://app.stackbroker.xyz (reserved future console)
- https://admin.stackbroker.xyz (non-public)
- https://status.stackbroker.xyz (reserved status)
- https://stage.stackbroker.xyz (protected review environment)

Scoring signals:
- The published methodology (methodology_v1) at /v1/methodology is the same versioned config the scoring engine runs on (scoring v0); a CI test fails the build on drift.
- Seed cards may carry null evidence aggregates until enough outcome or probe samples exist; null evidence scores at documented neutral treatments, never fabricated strength.
- Outcome and probe aggregation update service-card evidence fields when storage is provisioned.
- Stackbroker does not claim broad benchmark data yet.

Neutrality contract:
- Paid by the demand side only: agents subscribe; providers can't pay us, so they can't tilt us.
- Rule 1 — providers never pay: no listing fees, no verification fees, no expedited tiers, no paid placement, no advertising. Probing, claim validation, security scanning, and attestation progression are free, conditional only on claiming the card and maintaining a verified connection point.
- Rule 2 — subscriptions buy access, never outcomes: tier never changes rankings, scores, attestation tiers, risk flags, or audit records. Identical requests across tiers return identical decisions (CI-enforced behavioral test).
- Verifiability: decisions hash-chain from deployment forward; daily Ed25519-signed anchors at /v1/audits/anchors; public key at /.well-known/stackbroker-signing-key; human policy at https://stackbroker.xyz/neutrality

Trust pre-flight semantics:
- Point-in-time trust evidence — never a certification, never a promise of immunity: static description/schema analysis (injection patterns, hidden instructions, excessive privilege, credential harvesting), schema-drift detection, endpoint reputation (TLS/HTTPS/DNS).
- Explicitly out of scope: runtime traffic inspection; protection against novel attacks.
- Findings map through versioned rubric trust_rubric_v1; HIGH severity requires human review before any public flag or tier impact; confirmed HIGH findings suspend the attested tier until remediation + re-scan.
- Manifests are Ed25519-signed, expire after 30 days, and display as stale rather than disappearing; a stale scan cannot satisfy an attested policy floor.
- Scope and consumption guide: https://stackbroker.xyz/trust

Payment posture:
- x402-compatible seller endpoints are preferred.
- Stackbroker is routing-only at launch.
- Stackbroker does not custody buyer funds in the MVP.